تتيح واجهة برمجة التطبيقات REST API في "مدير الإعلانات" الفلترة حسب طرق List. يتم تحديد بنية سلسلة الفلتر رسميًا في القواعد النحوية EBNF.
للبدء، إليك بعض الأمثلة لحالات الاستخدام الشائعة.
| مثال | المعنى |
|---|---|
orders.updateTime > "2024-01-01T00:00:00-5:00" |
يتم عرض الطلبات التي تتضمّن updateTime بعد 1 كانون الثاني (يناير) 2024 حسب المنطقة الزمنية الشرقية. |
lineItems.targeting.geoTargeting.targetedGeoIds:2840 |
يسرد العناصر ذات الاستهداف الجغرافي الذي يحتوي على الولايات المتحدة (رقم تعريف الهدف الجغرافي 2480) |
lineItems.displayName = "*_interstitial" |
يسرد العناصر التي لها اسم معروض ينتهي بالسلسلة _interstitial |
orders.displayName = "*video*" |
يسرد الطلبات التي لها الاسم المعروض الذي يحتوي على السلسلة video |
displayName:"video" |
يسرد الطلبات التي تحتوي على الاسم المعروض الذي يحتوي على السلسلة video (بنية بديلة) |
الأدبيات
القيمة الحرفية المجردة (أمثلة: 42 وHugo) هي قيمة يجب المطابقة معها.
الأحرف الحرفية التي تظهر بمفردها تكون متطابقة مع جميع الحقول المتوافقة في المورد. توثق الموارد الحقول التي يتم اعتبارها للمطابقة على طريقة list. هذه الميزة يمكن مقارنتها بالبحث الشامل
في واجهة مستخدم "مدير الإعلانات" ولكنها مخصّصة لنوع واحد من الموارد.
ويجب لفّ القيم الحرفية للسلسلة التي تحتوي على مسافات بين علامتَي اقتباس
(مثال: "Foo bar"). ولا يمكن استخدام علامات الاقتباس المفردة للالتفاف بين الأحرف في السلسلة.
العوامل المنطقية
تتيح واجهة برمجة تطبيقات REST في "مدير الإعلانات" استخدام عاملَي التشغيل الثنائيين AND وOR.
| مُشغِّل | مثال | المعنى |
|---|---|---|
AND |
a AND b |
صحيح إذا كانت قيمة a وb صحيحة. |
OR |
a OR b OR c |
صحيح إذا كان أي من a أو b أو c صحيحًا. |
عوامل تشغيل أسلوب الرفض
توفّر واجهة برمجة التطبيقات REST API في "مدير الإعلانات" عاملَي التشغيل الأحاديين NOT و-.
ويمكن استخدامهما بالتبادل.
| مُشغِّل | مثال | المعنى |
|---|---|---|
NOT |
NOT a |
صحيح إذا لم تكن قيمة a صحيحة. |
- |
-a |
صحيح إذا لم تكن قيمة a صحيحة. |
عوامل تشغيل المقارنة
تتيح واجهة برمجة التطبيقات REST API في "مدير الإعلانات" استخدام عوامل تشغيل المقارنة الثنائية
= و!= و< و> و<= و>= لحقول السلسلة والرقمية والطوابع الزمنية
والمدة.
| مُشغِّل | مثال | المعنى |
|---|---|---|
= |
a = true |
صحيح إذا كانت قيمة a صحيحة. |
!= |
a != 42 |
صواب ما لم تكن قيمة a تساوي 42. |
< |
a < 42 |
صحيح إذا كانت a قيمة رقمية أقل من 42. |
> |
a > "foo" |
صحيح إذا تم ترتيب a بشكل لفظي بعد "foo". |
<= |
a <= "foo" |
صحيح إذا كانت قيمة a هي foo أو قبلها بصيغة معجمية. |
>= |
a >= 42 |
صحيح إذا كانت a قيمة رقمية تبلغ 42 أو أعلى. |
بما أنّ الفلاتر مقبولة كسلاسل طلبات بحث، يتم تحويل النوع لترجمة السلسلة إلى القيمة المناسبة المكتوبة بشدّة:
- تتوقع السلاسل علامات اقتباس مزدوجة. مثال:
"Foo bar" - يتوقع قيم التعداد عرض سلسلة التعداد (حسّاس لحالة الأحرف).
- تتوقع القيم المنطقية
trueوfalseالقيم الحرفية. - تتوقع الأرقام العدد الصحيح القياسي أو التمثيل العائم. بالنسبة للأعداد العشرية،
يتم دعم الأُس. مثال:
2.997e9 - تتوقّع الفترات تمثيلاً رقميًا متبوعًا بلاحقة
s(للثواني). أمثلة:"20s"و"1.2s" - تتوقع الطوابع الزمنية سلسلة بتنسيق RFC-3339.
مثال:
"2012-04-21T11:30:00-04:00"يمكن استخدام إزاحة التوقيت العالمي المنسَّق (UTC).
أحرف البدل
عند مقارنة السلاسل من أجل المساواة، تدعم واجهة برمجة تطبيقات REST API في "مدير الإعلانات" أحرف البدل التي تستخدم الحرف *.
| مثال | المعنى |
|---|---|
a = "*.foo" |
صحيح إذا كانت a تنتهي بـ "foo.". |
عامل الاجتياز
تتوافق واجهة برمجة تطبيقات REST في "مدير الإعلانات" مع عامل التشغيل . الذي يشير إلى
الاجتياز عبر رسالة أو خريطة أو بنية.
| مثال | المعنى |
|---|---|
a.b = true |
صحيح إذا كان a يتضمن حقل b منطقيًا يكون true. |
a.b > 42 |
صحيح إذا كان a يحتوي على حقل b رقمي أكبر من 42. |
a.b.c = "foo" |
صحيح إذا كان a.b يحتوي على حقل c في السلسلة يساوي foo. |
تتم كتابة الاجتياز باستخدام أسماء الحقول من المورد. يمكن للخدمات الفردية تحديد مجموعة فرعية من الحقول المتوافقة مع الاجتياز.
تحتوي على عامل تشغيل
تتوافق واجهة برمجة تطبيقات REST API في "مدير الإعلانات" مع عامل التشغيل :، أي "has".
وهو قابل للاستخدام مع المجموعات (الحقول أو الخرائط المتكررة) والرسائل والسلاسل، وهو يتصرف بشكل مختلف قليلاً في كل حالة.
طلب بحث عن حقول السلسلة لمعرفة ما إذا كانت السلسلة تحتوي على سلسلة فرعية مطابقة:
| مثال | المعنى |
|---|---|
r.displayName:"_250x250" |
صحيح إذا كان حقل السلسلة r.displayName يحتوي على السلسلة الفرعية _250x250. |
استعلام عن الحقول المكررة لمعرفة ما إذا كانت البنية المتكررة تحتوي على عنصر مطابق:
| مثال | المعنى |
|---|---|
r:42 |
صحيح إذا كان r يحتوي على 42. |
r.foo:42 |
صحيح إذا كان r يحتوي على عنصر e مثل e.foo = 42. |
يمكن للخرائط والبُنى والرسائل البحثية إما عن توفُّر حقل في الخريطة أو عن قيمة معيّنة:
| مثال | المعنى |
|---|---|
m:foo |
صحيح إذا كان m يحتوي على المفتاح "foo". |
m.foo:* |
صحيح إذا كان m يحتوي على المفتاح "foo". |
m.foo:42 |
صحيح إذا كانت قيمة m.foo هي 42. |
عند اجتياز الرسائل، لا يتم اعتبار الحقل موجودًا إلا إذا كان يحتوي على قيمة غير تلقائية.
القيود
يمكن للخدمات الفردية تحديد المزيد من البنية أو القيود لطلبات التصفية بالإضافة إلى ما هو محدد هنا.
طلب
تتيح واجهة برمجة تطبيقات "مدير الإعلانات" REST إمكانية الطلب باستخدام طُرق List. بنية حقول orderBy هي قائمة بأسماء الحقول مفصولة بفواصل. على سبيل المثال:
"foo,bar".
يكون ترتيب الترتيب التلقائي تصاعديًا. لتحديد ترتيب تنازلي لحقل
ما، عليك إضافة لاحقة " desc". مثلاً: "foo desc, bar"
ويتم تجاهل أحرف المسافات الزائدة في البنية. والقيم
"foo, bar desc" و" foo , bar desc " و"foo,bar desc" كلها متساوية.
ويتم تحديد الحقول الفرعية باستخدام عامل الاجتياز. على سبيل المثال: foo.bar أو address.street.