סינון התשובות ברשימה

רוב השירותים ב-Display & Video 360 API מספקים שיטה LIST לאחזור בכמות גדולה של משאבים. בדרך כלל, השיטות האלה של LIST תומכות בסינון תוצאות באמצעות פרמטר של שאילתה filter. אפשר להשתמש בפרמטר הזה כדי לבצע אופטימיזציה של השימוש ב-API על ידי אחזור רק של מה שדרוש לכם.

במדריך הזה נסביר איך להשתמש בפרמטר filter ביעילות.

מבנה המסנן

ערך הפרמטר filter הוא מחרוזת, שמכילה הגבלה אחת או יותר שאפשר לשלב עם אופרטורים AND או OR ולקבץ באמצעות סוגריים.

ההגבלות צריכות להיות בפורמט {field} {operator} {value}. לדוגמה:

entityStatus="ENTITY_STATUS_ACTIVE"

אורך מחרוזת המסנן לא יכול לחרוג מ-500 תווים. אם מחרוזת הסינון מכילה יותר מ-500 תווים, מבצעים אחת מהפעולות הבאות:

  • מפצלים את הלוגיקה לכמה מחרוזות מסנן ומאחזרים את המשאבים באמצעות בקשות LIST נפרדות.
  • מסירים חלק מהלוגיקה ממחרושת המסנן ומשתמשים בה כדי לסנן את המשאבים שאוחזרו באופן מקומי.

צריך להוסיף מירכאות לערכי ההגבלות כדי לוודא שהלוגיקה תחול בצורה נכונה.

אם אתם מבצעים קריאות ל-LIST ישירות בלי להשתמש בספריית לקוח, צריך לבצע קידוד URL למחרוזות המסנן.

פרטים נוספים על הפורמט של השאילתות מופיעים בקטע לוגיקה בין הגבלות.

שדות שניתן לסנן

השדות שאפשר לסנן בכל שיטה של LIST מפורטים בתיאור הפרמטר filter של השיטה. ברוב המקרים, אפשר לסנן לפי קבוצת משנה של השדות הרגילים של המשאב. במקרים נדירים, יש שדות נוספים שאפשר להשתמש בהם רק לסינון.

כל שדה בתיאור הפרמטר תומך לפחות באחד מהאופרטורים הבאים:

אופרטורים להשוואה
EQUALS (=) הערך בשדה המשאב שווה לערך שצוין.

לדוגמה: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) הערך בשדה המשאב קטן מהערך הנתון או שווה לו. בדרך כלל משתמשים ב-‎isequal כשמשווים בין תאריך או תאריך ושעה.

לדוגמה: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) הערך בשדה המשאב גדול מהערך שצוין או שווה לו. בדרך כלל משתמשים ב-‎isequal כשמשווים בין תאריך או תאריך ושעה.

לדוגמה: 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")