إدراج بنية الفلتر واستخدامه

يصف هذا الدليل بنية فلتر القائمة وكيفية فلترة أنواع الموارد المختلفة.

ويمكن أن تقبل بعض طُرق واجهة برمجة التطبيقات فلترًا للحدّ من الموارد المعروضة في الردّ.

ملخّص

يوفّر هذا القسم نظرة عامة سريعة على بنية بنية فلاتر القوائم.

• الفلتر هو سلسلة تحتوي على expression. تمثّل expression مجموعة منطقية من المقارنات:

  expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
  expression = ( expression )
  

• تتطابق السمة comparison مع قيمة في حقل مورد. يمكنك استخدام جميع عوامل المقارنة الشائعة.

  comparison = name OP value
  OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  

  يمكن استخدام عامل التشغيل has، وهو علامة النقطتين (:)، في السلاسل والحقول المتكرّرة. راجِع القسم تحتوي على عامل تشغيل لمزيد من التفاصيل.

• يمكنك استخدام أنواع القيم التالية في الفلاتر:

  • الأرقام
  • السلاسل
  • التعبيرات الموضوعة بين قوسين

  value = number| string | "*" | "(" expression ")"
  

• يمكن أن تمثّل السلاسل ما يلي:

  • نص عشوائي
  • قيم منطقية
  • قيم التعداد
  • الطوابع الزمنية

التعبيرات المنطقية

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

تتم العمليات بالترتيب التالي:

1. NOT
2. OR
3. AND

على سبيل المثال، التعبيرات التالية متكافئة:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

يمكنك حذف عامل التشغيل AND بين المقارنات. على سبيل المثال، عوامل التصفية التالية هي نفسها:

c=d AND e=f

c=d e=f

يمكنك استخدام الواصلة (-) كبديل لـ NOT. لا يمكن أن تكون هناك مسافة بين الواصلة (-) والمقارنة التالية. على سبيل المثال، عوامل التصفية التالية هي نفسها:

NOT e=f

-e=f

المقارنات

يصف هذا القسم مقارنات ""name OP value"" على النحو التالي:

comparison = name OP value

أين

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

الجانب الأيسر من المقارنة هو اسم مسار حقل مورد واجهة برمجة التطبيقات. يتكوّن الاسم من سلسلة من معرّفات الموارد المرتبطة بنقطة (.). يلي كل معرّف حقل المستوى التالي من أسماء هذا الحقل. على سبيل المثال، لنفترض أنّ موردًا يتضمن حقلاً معقدًا item يضم حقلاً معقدًا آخر tool يشمل حقلاً اسمه shape. في عامل تصفية لهذا المورد، يمكنك الرجوع إلى الشكل باسم item.tool.shape.

الجانب الأيمن يكون عادةً قيمة عددية يتم تحويلها إلى نوع الحقل ومقارنتها به. راجع قسم أنواع القيمة الحرفية للحصول على المزيد من التفاصيل.

يمكن أيضًا التعبير عن الجانب الأيمن من المقارنة كمجموعة منطقية بين قوسين من القيم الحرفية و/أو التعبيرات المنطقية التي تحتوي على قيم حرفية فقط (مسبقة بـ NOT أو بدونها). يتم تطبيق اسم الجانب الأيسر وعامل المقارنة على كل قيمة من القيم. على سبيل المثال، عوامل التصفية التالية هي نفسها:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

في ما يلي مثال آخر أكثر تعقيدًا لفلترين مكافئين:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

الأنواع الحرفية للقيمة

يمكن تصنيف قيمة الجانب الأيمن لعامل المقارنة إلى رقم وسلسلة حرفية.

العدد

يصف هذا القسم تمثيل القيم الحرفية الرقمية.

Type	التعريف	أمثلة
بلوغ القاعدة الثانية	يتم التعامل مع أي رقم يحتوي على علامة عشرية، بعلامة ("-") أو بدونها، على أنّه رمز مزدوج.	1234.567 -789.0123
عدد صحيح	يتم التعامل مع أي رقم لا يحتوي على علامة عشرية، سواء بعلامة ("-") أو بدونها كعدد صحيح.	1234 -789

سلسلة

يصف هذا القسم الأنواع التي يمكنك كتابتها كسلسلة حرفية في بنية الفلتر.

ملاحظة: يمكن إدراج قيمة حرفية للسلسلة بين علامة اقتباس مزدوجة (" ") أو بدون علامتي اقتباس. لا يمكنك استخدام علامات اقتباس مفردة لتمثيل سلسلة حرفية. على سبيل المثال، ABC DEF وABC DEF هما قيمتان حرفيتان للسلسلة، بينما ABC DEF ليسا كذلك.

Type	التعريف	أمثلة
منطقي	TRUE أو FALSE بأي حالة أحرف	TRUE True "true"
قيم التعداد	اسم نوع التعداد حرفي. تكون قيم التعداد حساسة لحالة الأحرف.	تختلف قيمة FINALIZED عن Finalized.
سلسلة	أي سلسلة تحتوي على نص بترميز UTF-8 أو نص ASCII 7 بت. يجب تخطي علامات الاقتباس المضمّنة بشرطة مائلة للخلف. يتم التعامل مع السلاسل غير المدرَجة بين علامات اقتباس مع مسافة بيضاء كـ "AND" ضمني بين جميع الكلمات بعد قسمة السلسلة باستخدام مسافة بيضاء.	name = "test \"double quotes\"" name=(ABC DEF) تكافئ name=ABC AND name=DEF
الطابع الزمني	سلسلة بتنسيق ISO8601 العادي	"2014-10-02T15:01:23.045Z"

عوامل تشغيل المقارنة

في ما يلي عوامل المقارنة:

• أقل من أو يساوي: "<="
• أقل من: "<"
• أكبر من أو يساوي: ">="
• أكبر من: ">"
• لا يساوي: "!="
• يساوي: "="
• تحتوي على: ":"

تنطبق هذه العوامل على أنواع القيم المزدوجة، والعددية، والمنطقية، والتعداد، والطابع الزمني.

ملاحظة: بالنسبة إلى القيم المخزّنة كسلاسل، يمكنك فقط استخدام عوامل التشغيل "!=" و"=" و":". مقارنة السلاسل غير حساسة لحالة الأحرف.

تحتوي على عامل تشغيل

يمكنك استخدام عامل التشغيل HAS (:) لعمليات خاصة في الحقول التالية:

السلاسل الفرعية

عند استخدام عامل التشغيل HAS لمقارنة القيم في عمود سلسلة بسلسلة، سيعمل عامل التشغيل كعملية سلسلة فرعية. على سبيل المثال، تعرض الدالة name:"abcd" جميع الحالات التي يكون فيها name سلسلة تحتوي على "abcd".

التحقق من تواجد الأفراد في المنزل

عند استخدام عامل التشغيل HAS مع الحرف الخاص *، يبحث عامل التشغيل HAS عن القيم غير الفارغة. على سبيل المثال، تعرض القيمة name:* جميع الحالات التي لا تكون فيها name فارغة أو غير متوفّرة أو غير محدّدة.

عند استخدام عامل التشغيل HAS مع قيم ليست سلسلة، فإنه يعمل بالطريقة نفسها التي يعمل بها عامل التشغيل EQUALS (=). على سبيل المثال، يتصرف isCompleted:true بنفس طريقة عمل isCompleted = true.

الحقول المتكررة

يمكنك استخدام عامل التشغيل HAS (:) للفلترة في حقل موارد واجهة برمجة تطبيقات متكرّر، طالما أنّ المعايير التالية صحيحة:

1. هناك مكوِّن واحد متكرر فقط على طول مسار معرِّف الحقل.
2. المعرّف الأخير لمسار الحقل من النوع العددي

لا تتوفّر إمكانية فلترة الحقول المتكرّرة المتداخلة.

وفي ما يلي مثال لذلك:

يحتوي item على الحقل colors الذي يحتوي على قيم سلسلة مثل "red" و"blue" و"yellow".

• تعرض السمة item.colors:("red") جميع السلع التي تحتوي على القيمة "red" في الحقل colors.
• يعرض item.colors:("red" "yellow") جميع السلع التي تتضمّن "red" و"yellow" في الحقل colors.
• يعرض item.colors:("red" OR "yellow") كل السلع التي تحتوي على "red" أو "yellow" في الحقل colors.

تحتوي item أيضًا على حقل tools متكرّر، وهو كائن معقد ذو حقل عددي shape، ويمكن أن تكون قيمه "square" أو "round".

• تعرض item.tools.shape:("square") جميع السلع التي تحتوي على أدوات على شكل "square".
• يعرض item.tools.shape:("square" "round") جميع السلع التي تحتوي على كلٍّ من أداة الشكل "square" وأداة الشكل "round".
• يعرض item.tools.shape:("square" OR "round") جميع العناصر التي تحتوي على أداة الشكل "square" أو أداة الشكل "round".

ملاحظة: لا يمكن فلترة جميع الحقول المتكرّرة. لمعرفة المزيد من التفاصيل حول مورد محدّد، يُرجى الاطّلاع على المستندات المرجعية.

حقول مدمجة غير معبأة

الحقول المتداخلة هي حقول فرعية من الحقول على مستوى الجذر، على سبيل المثال shape في item.tools.shape هو حقل مدمج لـ items.tools.

يتم ضبط حقول مستوى الجذر تلقائيًا على "خطأ". تكون الحقول المُدمَجة غير مُعبَّأة تلقائيًا.

ولا يتم عرض العناصر التي تحتوي على حقول مدمجة غير معبأة بواسطة الفلاتر السالبة (!=).

وفي ما يلي مثال لذلك:

يحتوي item.tools على تعداد size يمكن ضبط قيمته على "SMALL" أو "MEDIUM" أو "LARGE".

إذا كان لديك العناصر التالية:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

تؤدي استدعاء items.list مع الفلتر السالب "tools.size != SMALL" إلى عرض ما يلي:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

بما أنّه لم يتم ضبط item.tools.size للسمة item3، لا يعرض الفلتر السالب العنصر item3.

أمثلة

مثال	الوصف
externalDealId = "123456789"	externalDealId التي تحتوي على قيمة السلسلة "123456789".
advertiserId:93641 advertiserId = 93641	advertiserId الذي يحتوي على قيمة عدد صحيح 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete يساوي TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime بعد 14/02/2018 الساعة 11:09:19.378 بالتوقيت العالمي المنسق
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	تحتوي سلسلة displayName على قيمة متطابقة لـ "proposal" AND promotionRevision تساوي 3.
displayName = "proposal" OR proposalRevision = 3	يحتوي displayName على قيمة سلسلة "مقترح" أو تساوي قيمة الاقتراح 3.
NOT displayName = "proposal" displayName != "proposal"	displayName لا تساوي "اقتراح".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	قيمة التعداد للدالة proposalState تساوي إما PROPOSED أو BUYER_UPLOADED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	قيمة تعداد proposalState تساوي PROPOSED AND BUYER_acceptED
dealName = Test Deal	تعبير INVALID
dealName = "Test Deal"	إنّ قيمة dealName هي "صفقة تجريبية".
dealName = (Test Deal)	القيمة dealName هي "اختبار" ويساوي أيضًا "الصفقة".
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName إما تساوي "Test1" أو "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	يحتوي dealName على السلسلة الفرعية "test".
dealName:("A B") dealName:"A B"	يحتوي dealName على السلسلة الفرعية "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	يحتوي dealName على السلسلة الفرعية "A" والسلسلة الفرعية "B".
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	يحتوي dealName على السلسلة الفرعية "A" أو "B" وأيضًا يحتوي على السلسلة الفرعية "C"
dealName:("A B" C) dealName:"A B" AND dealName:"C"	يحتوي dealName على السلسلة الفرعية "A B" ويحتوي أيضًا على السلسلة الفرعية "C".
dealName:("A B" OR C D)	dealName يحتوي على إما السلسلة الفرعية "A B" أو "C"، ويحتوي أيضًا على السلسلة الفرعية "D".
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	لا يحتوي dealName على أي سلسلة فرعية "A" ويحتوي أيضًا على السلسلة الفرعية "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	لا يحتوي dealName على أي سلسلة فرعية "A" أو يحتوي على السلسلة الفرعية "B".