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