الفلاتر

تتيح 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. تتشابه هذه الميزة مع البحث الشامل في واجهة مستخدِم "مدير إعلانات 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 صحيحة.

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

تتيح واجهة برمجة تطبيقات "مدير إعلانات Google" عوامل التشغيل الثنائية للمقارنة = و!= و< و> و<= و>= للحقول التي تتضمّن سلاسل وأرقام وطابع زمني و مدة.

مُشغِّل	مثال	المعنى
=	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.

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

القيود

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

طلب

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

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

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

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