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

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

يوضّح هذا الدليل كيفية استخدام المَعلمة 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")