فلترة الردود على القائمة

معظم الخدمات في "الشبكة الإعلانية" توفّر Video 360 API طريقة LIST لاسترداد البيانات بشكل مجمّع. الموارد. تتيح عادةً طريقة LIST هذه فلترة النتائج من خلال معلَمة طلب البحث filter يمكنك استخدام هذه المعلمة لتحسين استخدام واجهة برمجة التطبيقات من خلال واسترجاع ما تحتاجه.

يوضّح هذا الدليل كيفية استخدام مَعلمة filter بفعالية.

بنية الفلتر

قيمة المعلَمة filter هي سلسلة تتكوّن من قيد واحد أو أكثر. يمكن دمجها مع عوامل التشغيل AND أو OR وتجميعها باستخدام الأقواس.

وتكون القيود بالنموذج {field} {operator} {value}. إليك مثال:

entityStatus="ENTITY_STATUS_ACTIVE"

لا يمكن أن يتجاوز طول سلسلة الفلتر 500 حرف. إذا كانت سلسلة الفلتر يتجاوز 500 حرف، يمكنك تنفيذ أحد الإجراءَين أدناه:

  • قسِّم المنطق إلى سلاسل فلاتر متعددة، واسترِد الموارد باستخدام طلبات LIST منفصلة.
  • أزِل بعض العناصر المنطقية من سلسلة الفلتر واستخدمها لفلترة استرداد الموارد محليًا.

ألغِ قيم التقييد بين علامتَي اقتباس لضمان تطبيق المنطق بشكل صحيح.

يمكنك ترميز سلاسل الفلاتر باستخدام عنوان URL في حال إجراء استدعاءات LIST مباشرةً بدون باستخدام مكتبة برامج.

راجِع المنطق بين القيود للحصول على مزيد من التفاصيل حول التنسيق. استعلاماتك.

حقول قابلة للفلترة

يتم سرد الحقول القابلة للتصفية لكل طريقة LIST في filter للطريقة. ووصف المعلمة. وفي معظم الحالات، يمكنك إجراء فلترة على مجموعة فرعية من بيانات الحقول القياسية. في بعض الحالات النادرة، تتوفّر حقول إضافية يمكنك استخدامها. للتصفية فقط.

يدعم كل حقل في وصف المعلمة واحدًا على الأقل مما يلي المشغلات المماثلة:

عوامل التشغيل المشابهة
EQUALS (=) قيمة حقل المورد تساوي القيمة المحددة.

مثلاً: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) قيمة حقل المورد أقل من أو تساوي القيمة المحددة. مستخدمة عادةً عند مقارنة التاريخ أو التاريخ.

مثلاً: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) قيمة حقل المورد أكبر من أو تساوي القيمة المحددة. مستخدمة عادةً عند مقارنة التاريخ أو التاريخ.

مثلاً: updateTime>="2023-03-01T12:00:00Z"
HAS (:) تحتوي قيمة حقل المورد على القيمة المحددة. إذا كان حقل المورد فستتحقق مما إذا كانت القيمة المحددة سلسلة فرعية موجودة. إذا كانت حقل الموارد عبارة عن صفيف، فسيتحقق مما إذا كان الصفيف يحتوي على

مثلاً: lineItemIds:"1234"

إذا لم يتم تحديد أي عوامل تشغيل للحقل في وصف المعلمة، يمكنك يمكن فقط استخدام عامل التشغيل EQUALS (=). تتيح بعض الحقول عوامل تشغيل متعددة.

تتطلب بعض الحقول القابلة للفلترة، مثل تلك الخاصة بالتواريخ والأوقات، ما يلي: قيمة مشابهة لاتباع تنسيق معين. يتم تحديد التنسيق بجوار الحقل في وصف معلمة filter.

المنطق بين القيود

يمكنك دمج قيود متعدّدة لتضييق نطاق الردّ أو توسيعه من طلب "LIST".

يمكنك عادةً دمج قيود متعددة مع AND وOR. والعوامل المنطقية. وتحدِّد كل طريقة LIST عوامل التشغيل المتوافقة. تتيح بعض الطرق استخدام قيد واحد فقط في مَعلمة filter.

يجب مراعاة القيود التالية عند إنشاء سلاسل فلاتر باستخدام AND أو OR من العوامل المنطقية:

  • يجب استخدام AND بين القيود أو مجموعات القيود التي تصفية حقول مختلفة، أو تصفية نفس الحقل بشكلٍ مختلف. إليك بعض الأمثلة:
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
  • يجب استخدام OR بين قيود فردية تتم فلترتها حسب . وفي ما يلي مثال لذلك:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • لا يمكنك استخدام OR للجمع بين مجموعتَين من القيود. استخدام خيارات متعددة LIST طلبات باستخدام قيم فلاتر مختلفة بدلاً من ذلك. على سبيل المثال، استخدم العنصر بعد طلب LIST منفصل:

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    لا تستخدم عامل التشغيل OR لدمجها:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • قد يتم تضمين الأقواس إذا لم تستخدمها لفرض قيود على المجموعات في سلسلة التصفية. على سبيل المثال، سلسلة الفلتر التالية:

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    على أنه:

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")