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

רוב השירותים ברשת המדיה טכנולוגיית 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")