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

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

يمكن لبعض طرق واجهة برمجة التطبيقات قبول فلتر لتقييد الموارد التي يتم عرضها في الاستجابة.

ملخّص

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

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

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

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

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

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

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

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

  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")

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

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

العدد

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

النوع	التعريف	أمثلة
مزدوجة	أي رقم يحتوي على علامة عشرية مع علامة ("-") أو بدونها على أنه مزدوج.	1234.567 -789.0123
عدد صحيح	يشير ذلك المصطلح إلى أي عدد لا يحتوي على علامة عشرية أو بعلامة أو بدونه. يتم التعامل مع ("-") كعدد صحيح.	1234 -789

سلسلة

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

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

النوع	التعريف	أمثلة
منطقي	تمثّل هذه السمة TRUE أو FALSE في أي حالة أحرف.	TRUE True "true"
Enum	يشير ذلك المصطلح إلى اسم نوع التعداد الحرفي. تُعد قيم التعداد حساسة لحالة الأحرف.	إنّ FINALIZED ليس مثل Finalized.
سلسلة	تمثّل هذه السمة أي سلسلة تحتوي على نص بترميز UTF-8 أو ASCII 7 بت. ويجب تخطي علامات الاقتباس المضمَّنة بشرطة مائلة للخلف. يتم التعامل مع السلاسل التي لا تتضمن علامتي اقتباس والتي تتضمن مسافة بيضاء على أنها "و" ضمنية بين جميع الكلمات بعد قسمة السلسلة بمسافة بيضاء.	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.
• يمكن إرجاع جميع السلع التي تتضمّن "red" أو من خلال item.colors:("red" OR "yellow") "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 بالتوقيت العالمي المنسق (UTC)
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	سلسلة displayName تحتوي على قيمة "proposal" متطابقة AND OfferRevision تساوي 3.
displayName = "proposal" OR proposalRevision = 3	تحتوي displayName على قيمة سلسلة "proposal" أو عرض الاقتراح تساوي 3.
NOT displayName = "proposal" displayName != "proposal"	displayName لا يساوي "اقتراح".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	تتضمن قيمة proposalState تعداد مساوية لقيمة PROPOSED أو acceptED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	يحتوي proposalState على قيمة تعداد تساوي PROPOSED AND 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" أو "ب" يحتوي AND أيضًا على سلسلة فرعية "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".