الفلاتر

تتيح Ad Manager 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 (بنية بديلة)

ملاحظة: يجب أن يكون الفلتر مُرمَّزًا بتنسيق عنوان URL لطلبات GET. على سبيل المثال: سلسلة الفلترة: orders.updateTime > "2024-01-01T00:00:00-5:00" عنوان URL المشفَّر: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. وتتولى مكتبات البرامج هذه المعالجة تلقائيًا.

القيم الحرفية

القيمة الحرفية المجردة (أمثلة: 42 وHugo) هي قيمة يجب مطابقتها. تتم مطابقة القيم الثابتة التي تظهر بمفردها تقريبًا مع جميع الحقول المتوافقة في أحد الموارد. توثّق الموارد الحقول التي يتمّ اعتبارها للمطابقة باستخدام طريقة list. تتشابه هذه الميزة مع بحث Universal في واجهة مستخدم "مدير إعلانات Google"، ولكن يكون نطاقها محصورًا بنوع مورد واحد.

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

العوامل المنطقية

تتيح Ad Manager API عاملَي التشغيل الثنائيَين AND وOR.

ملاحظة: تكون عوامل التشغيل هذه حساسة لحالة الأحرف. يتم التعامل مع القيم الثابتة and وor كقيم ثابتة.

عامل التشغيل	مثال	المعنى
AND	a AND b	صحيحة إذا كانت a وb صحيحتَين.
OR	a OR b OR c	صحيح إذا كانت أي من القيم a أو b أو c صحيحة.

ملاحظة: لمطابقة أنماط الكلام الشائعة، يكون OR عامل التشغيل الذي يُمنَح له الأولوية أعلى من AND، على عكس ما هو موجود في معظم لغات البرمجة. يتم تقييم العبارة a AND b OR c على أنّها a AND (b OR c). استخدِم قوسَين واضحَين قدر الإمكان لتجنُّب حدوث التباس.

عوامل تشغيل النفي

توفّر Ad Manager API عاملَي التشغيل الأحاديَين NOT و-. ويمكن استخدام هذين المصطلحين بدلاً من بعضهم.

عامل التشغيل	مثال	المعنى
NOT	NOT a	صحيح إذا لم تكن a صحيحة.
-	-a	صحيح إذا لم تكن a صحيحة.

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

تتيح Ad Manager 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" يمكن استخدام فروقات التوقيت عن التوقيت العالمي المنسّق.

تحذير: لا تحمل المعرّفات true وfalse وnull سوى معنى أساسي عند استخدامها في سياق مرجع حقل مكتوب.

أحرف البدل

عند مقارنة السلاسل بحثًا عن المساواة، تتيح Ad Manager API استخدام أحرف البدل باستخدام الحرف *.

مثال	المعنى
a = "*.foo"	صحيح إذا كان a ينتهي بـ "‎.foo".

عامل تشغيل التنقّل

تتيح Ad Manager API عامل التشغيل . الذي يشير إلى التنقّل في رسالة أو خريطة أو بنية.

مثال	المعنى
a.b = true	صحيح إذا كان a يحتوي على حقل b منطقي صحيح.
a.b > 42	صحيح إذا كان a يحتوي على حقل b رقمي أكبر من 42.
a.b.c = "foo"	صحيح إذا كان a.b يحتوي على حقل سلسلة c يساوي "foo".

يتم كتابة التنقّل باستخدام أسماء الحقول من المورد. يمكن للخدمات الفردية تحديد مجموعة فرعية من الحقول المتوافقة مع التنقّل.

ملاحظة مهمة: لا يمكن استخدام عامل التشغيل . للتنقّل في حقل أو قائمة متكرّرة، باستثناء استخدام محدّد مع عامل التشغيل :.

توفُّر مشغِّل

تتيح Ad Manager API عامل التشغيل :، الذي يعني "يملك". يمكن استخدامه مع المجموعات (الحقول أو الخرائط المتكررة) والرسائل والسلاسل، ويختلف سلوكه قليلاً في كل حالة.

تبحث طلبات البحث في حقول السلاسل لمعرفة ما إذا كانت السلسلة تحتوي على سلسلة فرعية مطابقة:

مثال	المعنى
r.displayName:"_250x250"	صحيح إذا كان حقل السلسلة r.displayName يحتوي على السلسلة الفرعية _250x250.

يُجري استعلام الحقول المتكرّرة لمعرفة ما إذا كانت البنية المتكرّرة تحتوي على عنصر مطابق:

مثال	المعنى
r:42	صحيح إذا كان r يحتوي على 42.
r.foo:42	صحيح إذا كانت r تحتوي على عنصر e بحيث e.foo = 42.

ملاحظة مهمة: لا يمكن للفلاتر البحث عن عنصر محدّد في حقل متكرّر للحصول على قيمة. على سبيل المثال، e.0.foo = 42 وe[0].foo = 42 ليسا فلترَين صالحَين.

يمكن للخرائط والبنى والرسائل البحث عن توفّر حقل في الخريطة أو قيمة معيّنة:

مثال	المعنى
m:foo	صحيح إذا كان m يحتوي على المفتاح "foo".
m.foo:*	صحيح إذا كان m يحتوي على المفتاح "foo".
m.foo:42	صحيح إذا كان m.foo يساوي 42.

عند التنقّل في الرسائل، لا يُعتبَر الحقل متوفّرًا إلا إذا كان يحتوي على قيمة غير تلقائية.

القيود

يمكن للخدمات الفردية تحديد المزيد من البنية أو القيود على طلبات بحث الفلاتر بالإضافة إلى ما هو محدّد هنا.

طلب

تتيح Ad Manager API الطلب وفقًا لطرق List. بنية orderBy الحقول هي قائمة مفصولة بفواصل بأسماء الحقول. على سبيل المثال: "foo,bar".

يكون ترتيب الفرز التلقائي تصاعديًا. لتحديد الترتيب التنازلي لحقل معيّن، أضِف اللاحقة " desc". على سبيل المثال: "foo desc, bar".

يتم تجاهل أحرف المسافة المتكرّرة في البنية. القيم "foo, bar desc" و" foo , bar desc " و"foo,bar desc" متكافئة.

يتم تحديد الحقول الفرعية باستخدام عامل التشغيل للتنقّل. على سبيل المثال: foo.bar أو address.street.