ברוב השירותים ב-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 (=)
|
הערך של שדה המשאב שווה לערך הנתון.
לדוגמה: |
|
LESS THAN OR EQUAL TO (<=)
|
הערך של שדה המשאב קטן מהערך הנתון או שווה לו. משתמשים בהם לעיתים קרובות
כשמשווים בין תאריך או תאריך ושעה.
לדוגמה: |
|
GREATER THAN OR EQUAL TO (>=)
|
הערך של שדה המשאב גדול מהערך הנתון או שווה לו. משתמשים בהם לעיתים קרובות
כשמשווים בין תאריך או תאריך ושעה.
לדוגמה: |
|
HAS (:)
|
הערך של שדה המשאב מכיל את הערך הנתון. אם שדה המשאב הוא
מחרוזת, הפונקציה בודקת אם הערך הנתון הוא מחרוזת משנה קיימת. אם שדה המשאב הוא מערך, הוא יבדוק אם המערך מכיל את הערך הנתון.
לדוגמה: |
אם לא צוינו אופרטורים לשדה בתיאור הפרמטר, אפשר להשתמש רק באופרטור 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")