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

اکثر سرویس‌ها در Display & Video 360 API یک روش LIST برای بازیابی انبوه منابع ارائه می‌کنند. این روش های LIST معمولاً از فیلتر کردن نتایج از طریق پارامتر filter و جو فیلتر پشتیبانی می کنند. از این پارامتر برای بهینه سازی استفاده از API خود فقط با بازیابی آنچه نیاز دارید استفاده کنید.

این راهنما نحوه استفاده موثر از پارامتر filter را نشان می دهد.

ساختار فیلتر

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

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

entityStatus="ENTITY_STATUS_ACTIVE"

طول رشته فیلتر نمی تواند بیش از 500 کاراکتر باشد. اگر رشته فیلتر شما بیش از 500 کاراکتر است، یکی از موارد زیر را انجام دهید:

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

برای اطمینان از اینکه منطق به درستی اعمال می شود، مقادیر محدودیت را در گیومه قرار دهید.

اگر مستقیماً بدون استفاده از کتابخانه سرویس گیرنده تماس‌های 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")