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

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

מבנה המסנן

הערכים של הפרמטר filter הם מחרוזות. המחרוזות האלה מורכבות מקריטריון אחד או יותר. הקריטריונים מחוברים באמצעות האופרטורים AND או OR.

קריטריון יחיד הוא בפורמט {field} {operator} {value}. לדוגמה:

  entityStatus="ENTITY_STATUS_ACTIVE"

מחרוזות של מסננים מוגבלות ל-500 תווים. אם המחרוזת ארוכה מדי:

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

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

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

מידע נוסף על מבנה מחרוזת המסנן מופיע בקטע קריטריונים להצטרפות.

קריטריוני סינון

כל שיטה של רשימה תומכת בקריטריונים מסוימים של מסננים. הקריטריונים האלה מפורטים בתיאור של הפרמטר 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 (=).

אם נדרש פורמט מיוחד, זה יצוין בקריטריון.

קריטריונים להצטרפות

אפשר לשלב כמה קריטריונים כדי לצמצם עוד יותר את התשובה של list.

צירוף קריטריונים באמצעות האופרטורים הלוגיים AND ו-OR. בכל list שיטה מצוין אילו מאפיינים נתמכים. חלק מהשיטות תומכות רק במסננים עם קריטריון אחד.

כשמשתמשים בכמה קריטריונים, חשוב לקחת בחשבון את המגבלות הבאות:

מגבלות ודוגמאות
AND צריך לשלב הגבלות או קבוצות של הגבלות שמסננות שדות שונים או שמסננות את אותו שדה בצורה שונה. 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 עם ערכי מסנן שונים. חובה להשתמש בשתי מחרוזות הסינון הבאות בבקשות נפרדות, ואסור לשלב אותן באמצעות האופרטור OR:
  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (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")