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

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

במדריך הזה מוסבר איך להשתמש ביעילות בפרמטר 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. כל method של 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")