يصف هذا الدليل بنية فلتر القائمة وكيفية فلترة أنواع الموارد المختلفة.
ويمكن أن تقبل بعض طُرق واجهة برمجة التطبيقات فلترًا للحدّ من الموارد المعروضة في الردّ.
ملخّص
يوفّر هذا القسم نظرة عامة سريعة على بنية بنية فلاتر القوائم.
الفلتر هو سلسلة تحتوي على
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}
تتم العمليات بالترتيب التالي:
NOT
OR
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 | التعريف | أمثلة |
---|---|---|
بلوغ القاعدة الثانية | يتم التعامل مع أي رقم يحتوي على علامة عشرية، بعلامة ("-") أو بدونها، على أنّه رمز مزدوج. |
|
عدد صحيح | يتم التعامل مع أي رقم لا يحتوي على علامة عشرية، سواء بعلامة ("-") أو بدونها كعدد صحيح. |
|
سلسلة
يصف هذا القسم الأنواع التي يمكنك كتابتها كسلسلة حرفية في بنية الفلتر.
Type | التعريف | أمثلة |
---|---|---|
منطقي | TRUE أو FALSE بأي حالة أحرف |
|
قيم التعداد | اسم نوع التعداد حرفي. تكون قيم التعداد حساسة لحالة الأحرف. |
تختلف قيمة FINALIZED عن Finalized .
|
سلسلة | أي سلسلة تحتوي على نص بترميز UTF-8 أو نص ASCII 7 بت. يجب تخطي علامات الاقتباس المضمّنة بشرطة مائلة للخلف. يتم التعامل مع السلاسل غير المدرَجة بين علامات اقتباس مع مسافة بيضاء كـ "AND" ضمني بين جميع الكلمات بعد قسمة السلسلة باستخدام مسافة بيضاء. |
|
الطابع الزمني | سلسلة بتنسيق ISO8601 العادي |
"2014-10-02T15:01:23.045Z"
|
عوامل تشغيل المقارنة
في ما يلي عوامل المقارنة:
- أقل من أو يساوي:
"<="
- أقل من:
"<"
- أكبر من أو يساوي:
">="
- أكبر من:
">"
- لا يساوي:
"!="
- يساوي:
"="
- تحتوي على:
":"
تنطبق هذه العوامل على أنواع القيم المزدوجة، والعددية، والمنطقية، والتعداد، والطابع الزمني.
تحتوي على عامل تشغيل
يمكنك استخدام عامل التشغيل HAS
(:
) لعمليات خاصة في الحقول التالية:
- السلاسل الفرعية
- عند استخدام عامل التشغيل
HAS
لمقارنة القيم في عمود سلسلة بسلسلة، سيعمل عامل التشغيل كعملية سلسلة فرعية. على سبيل المثال، تعرض الدالةname:"abcd"
جميع الحالات التي يكون فيهاname
سلسلة تحتوي على"abcd"
. - التحقق من تواجد الأفراد في المنزل
- عند استخدام عامل التشغيل
HAS
مع الحرف الخاص*
، يبحث عامل التشغيلHAS
عن القيم غير الفارغة. على سبيل المثال، تعرض القيمةname:*
جميع الحالات التي لا تكون فيهاname
فارغة أو غير متوفّرة أو غير محدّدة. - عند استخدام عامل التشغيل
HAS
مع قيم ليست سلسلة، فإنه يعمل بالطريقة نفسها التي يعمل بها عامل التشغيلEQUALS
(=
). على سبيل المثال، يتصرفisCompleted:true
بنفس طريقة عملisCompleted = true
. - الحقول المتكررة
يمكنك استخدام عامل التشغيل
HAS
(:
) للفلترة في حقل موارد واجهة برمجة تطبيقات متكرّر، طالما أنّ المعايير التالية صحيحة:- هناك مكوِّن واحد متكرر فقط على طول مسار معرِّف الحقل.
- المعرّف الأخير لمسار الحقل من النوع العددي
لا تتوفّر إمكانية فلترة الحقول المتكرّرة المتداخلة.
وفي ما يلي مثال لذلك:
يحتوي
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. |
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" AND promotionRevision تساوي 3. |
displayName = "proposal" OR proposalRevision = 3 |
يحتوي displayName على قيمة سلسلة "مقترح" أو تساوي قيمة الاقتراح 3. |
NOT displayName = "proposal" |
displayName لا تساوي "اقتراح". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
قيمة التعداد للدالة proposalState تساوي إما PROPOSED أو BUYER_UPLOADED. |
proposalState = (PROPOSED AND 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" أو "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
يحتوي dealName على السلسلة الفرعية "test". |
dealName:("A B") |
يحتوي dealName على السلسلة الفرعية "A B". |
dealName:(A B) |
يحتوي dealName على السلسلة الفرعية "A" والسلسلة الفرعية "B". |
dealName:("A" OR "B" AND "C") |
يحتوي dealName على السلسلة الفرعية "A" أو "B" وأيضًا يحتوي على السلسلة الفرعية "C" |
dealName:("A B" C) |
يحتوي dealName على السلسلة الفرعية "A B" ويحتوي أيضًا على السلسلة الفرعية "C". |
dealName:("A B" OR C D) |
dealName يحتوي على إما السلسلة الفرعية "A B" أو "C"، ويحتوي أيضًا على السلسلة الفرعية "D". |
dealName:(NOT "A" B) |
لا يحتوي dealName على أي سلسلة فرعية "A" ويحتوي أيضًا على السلسلة الفرعية "B". |
dealName:(NOT "A" OR "B") |
لا يحتوي dealName على أي سلسلة فرعية "A" أو يحتوي على السلسلة الفرعية "B". |