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

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