درخواست های لیست را فیلتر کنید

متدهای list چندین منبع از یک نوع مشخص را بازیابی می‌کنند. پارامتر پرس‌وجوی filter به شما امکان می‌دهد معیارهایی را که منابع بازیابی شده باید داشته باشند، تعیین کنید.

ساختار فیلتر

مقادیر پارامترهای filter رشته هستند. این رشته‌ها از یک یا چند معیار تشکیل شده‌اند. معیارها توسط عملگرهای AND یا OR به هم متصل می‌شوند.

یک معیار واحد به شکل {field} {operator} {value} است. در اینجا مثالی آورده شده است:

  entityStatus="ENTITY_STATUS_ACTIVE"

رشته‌های فیلتر به ۵۰۰ کاراکتر محدود می‌شوند. اگر رشته شما خیلی طولانی است:

  • منطق را به رشته‌های جداگانه تقسیم کنید. با هر رشته فیلتر یک فراخوانی list انجام دهید. نتایج را برای ایجاد یک لیست واحد ترکیب کنید.
  • معیارها را از رشته فیلتر حذف کنید. از معیارهای حذف شده برای فیلتر کردن منابع بازیابی شده به صورت محلی استفاده کنید.

مقادیر مربوط به یک معیار را داخل گیومه قرار دهید.

هنگام فراخوانی مستقیم API، مطمئن شوید که رشته‌های فیلتر شما برای استفاده در URL کدگذاری شده‌اند.

برای اطلاعات بیشتر در مورد ساختار رشته فیلتر، به بخش معیارهای Join مراجعه کنید.

معیارهای فیلتر

هر متد لیست از معیارهای فیلتر خاصی پشتیبانی می‌کند. توضیحات مربوط به پارامتر 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") تفسیر می‌شود.