فلترة طلبات القائمة

تستردّ طرق list موارد متعدّدة من نوع مجموعة. يتيح لك مَعلمة الاستعلام filter تقديم معايير يجب أن تستوفيها الموارد التي يتم استردادها.

بنية الفلتر

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

يتخذ المعيار الفردي الشكل {field} {operator} {value}. وفي ما يلي مثال لذلك:

  entityStatus="ENTITY_STATUS_ACTIVE"

تقتصر سلاسل الفلاتر على 500 حرف. إذا كانت السلسلة طويلة جدًا:

  • قسِّم المنطق إلى سلاسل منفصلة. إجراء مكالمة list مع كل سلسلة فلترة اجمع النتائج لإنشاء قائمة واحدة.
  • أزِل المعايير من سلسلة الفلتر. استخدِم المعايير التي تمت إزالتها لفلترة الموارد التي تم استردادها محليًا.

ضَع قيم المعيار بين علامتَي اقتباس.

تأكَّد من ترميز سلاسل الفلاتر لاستخدامها في عنوان URL عند إجراء طلبات إلى واجهة برمجة التطبيقات مباشرةً.

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

معايير الفلتر

تتيح كل طريقة من طرق القائمة معايير فلترة معيّنة. يتم إدراج هذه المعايير في وصف المَعلمة 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 (=).

سيشير أحد المعايير إلى ما إذا كان يتطلّب تنسيقًا خاصًا.

معايير الانضمام

يمكنك دمج معايير متعددة لفرض قيود إضافية على الردّ list.

يمكنك ربط معايير الانضمام بعوامل التشغيل المنطقية AND وOR. تحدّد كل طريقة list الطرق المتوافقة. لا تتيح بعض الطرق استخدام فلاتر تتضمّن أكثر من معيار واحد.

يُرجى مراعاة هذه الحدود عند استخدام معايير متعدّدة:

القيود والأمثلة
يجب أن تجمع AND بين القيود أو مجموعات القيود التي تفلتر حقولاً مختلفة أو تفلتر الحقل نفسه بشكل مختلف. 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 متعددة مع قيم فلاتر مختلفة. يجب استخدام سلسلتَي الفلتر التاليتَين في طلبات منفصلة، ولا يمكن دمجهما باستخدام عامل التشغيل OR:
  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (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")