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

במדריך הזה מתואר התחביר של מסנן הרשימות, ואיך מסננים סוגי משאבים שונים.

בחלק משיטות ה-API אפשר לקבל מסנן כדי להגביל את המשאבים שמוחזרים בתגובה.

סיכום

בקטע הזה מוצגת סקירה כללית מהירה של מבנה התחביר של מסנן הרשימה.

  • מסנן הוא מחרוזת שמכילה את הערך expression. expression הוא שילוב בוליאני של השוואות:

    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
expression = ( expression )

  • השדה comparison תואם לשדה משאב עם ערך. אפשר להשתמש בכל האופרטורים הנפוצים להשוואה.

    comparison = name OP value
OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"

    אפשר להשתמש באופרטור has, בנקודתיים (:), במחרוזות ובשדות חוזרים. פרטים נוספים זמינים בקטע יש אופרטור.

  • אפשר להשתמש בסוגי הערכים הבאים במסננים:

    • מספרים
    • מחרוזת
    • ביטויים בסוגריים
    value = number| string | "*" | "(" expression ")"

  • מחרוזות יכולות לייצג את הערכים הבאים:

    • טקסט שרירותי
    • בוליאני
    • ערכי Enum
    • חותמות זמן

ביטויים בוליאניים

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

הפעולות נעשות לפי הסדר הבא:

  1. NOT
  2. OR
  3. AND

לדוגמה, הביטויים הבאים שקולים:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

אפשר להשמיט את האופרטור AND בין השוואות. לדוגמה, המסננים הבאים זהים:

c=d AND e=f

c=d e=f

אפשר להשתמש במקף (-) כחלופה של NOT. לא יכול להיות רווח בין המקף (-) לבין ההשוואה הבאה. לדוגמה, המסננים הבאים זהים:

NOT e=f

-e=f

השוואות

בקטע הזה מתוארות השוואות של "name OP value", כמו בדוגמאות הבאות:

comparison = name OP value

איפה

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

בצד ימין של ההשוואה מופיע שם הנתיב של שדה משאב ה-API. השם מורכב מסדרה של מזהי משאבים שמחוברים לפי נקודה (.). אחרי כל מזהה שדה מופיעה הרמה הבאה של שמות לאותו שדה. לדוגמה, נניח שמשאב מכיל שדה מורכב item, שמכיל שדה מורכב נוסף tool, שמכיל שדה בשם shape. במסנן של המשאב הזה, צריך להתייחס לצורה בשם item.tool.shape.

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

ניתן לבטא גם את הצד הימני של השוואה כשילוב בוליאני בסוגריים של ערכים מילוליים ו/או ביטויים בוליאניים, שמכילים רק ערכים מילוליים (לפני או בלי NOT). השם בצד שמאל ואופרטור ההשוואה חלים על כל אחד מהערכים. לדוגמה, המסננים הבאים זהים:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

הנה דוגמה נוספת, מורכבת יותר, של שני מסננים מקבילים:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

סוגי ערכים ליטראליים

אפשר לסווג את הערך בצד ימין של האופרטור 'השוואה' לליטרלים של מספרים ומחרוזות.

מספרים

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

תיאור הגדרה דוגמאות
דאבל כל מספר שמכיל נקודה עשרונית, עם או בלי הסימן ("-") נחשב כ-Double.
  • 1234.567
  • -789.0123
מספר שלם כל מספר ללא נקודה עשרונית, עם או בלי סימן ("-") נחשב כמספר שלם.
  • 1234
  • -789

מחרוזת

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

תיאור הגדרה דוגמאות
בוליאני TRUE או FALSE בכל אותיות רישיות.
  • TRUE
  • True
  • "true"
טיפוסים בני מנייה (enum) שם ליטרל של סוג המספור. ערכי Enum הם תלויי אותיות רישיות. FINALIZED לא זהה ל-Finalized
מחרוזת כל מחרוזת שמכילה טקסט בקידוד UTF-8 או ASCII 7 ביט. אם מירכאות מוטמעות מוטמעות, צריך לסמן אותן בתו בריחה (escape) עם לוכסן הפוך. מחרוזות לא מוקפות עם רווח לבן יטופלו כ-'AND' מרומז בין כל המילים אחרי פיצול המחרוזת לפי רווח לבן.
  • name = "test \"double quotes\""
  • name=(ABC DEF) שווה ערך ל-
    name=ABC AND name=DEF
חותמת זמן מחרוזת בפורמט הסטנדרטי ISO8601. "2014-10-02T15:01:23.045Z"

אופרטורים להשוואה

אלה האופרטורים להשוואה:

  • קטן מ- או שווה ל-: "<="
  • קטן מ-: "<"
  • גדול מ- או שווה ל-: ">="
  • גדול מ-: ">"
  • שונה מ-: "!="
  • שווה ל-: "="
  • כולל: ":"

האופרטורים האלה חלים על סוגי הערכים Dual, מספר שלם, בוליאני, Enum וחותמת זמן.

כולל מפעיל

אפשר להשתמש באופרטור HAS (:) לפעולות מיוחדות בשדות הבאים:

מחרוזת משנה
כשהאופרטור HAS משמש להשוואת ערכים בעמודת מחרוזת למחרוזת, האופרטור יפעל כפעולה של מחרוזת משנה. לדוגמה, הפונקציה name:"abcd" מחזירה את כל המופעים שבהם name היא מחרוזת שמכילה את הערך "abcd".
בדיקת קיום
כשמשתמשים באופרטור HAS עם התו המיוחד *, האופרטור HAS בודק אם יש ערכים שאינם ריקים. לדוגמה, הפונקציה name:* מחזירה את כל המופעים שבהם name הוא לא null, חסר או לא מוגדר.
כשמשתמשים באופרטור HAS עם ערכים שאינם מחרוזת, הוא פועל כמו האופרטור EQUALS (=). לדוגמה, הפונקציה isCompleted:true פועלת באותו אופן כמו isCompleted = true.
שדות חוזרים

אפשר להשתמש באופרטור HAS (:) כדי לסנן שדה משאב חוזר של API, כל עוד מתקיימים התנאים הבאים:

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

אין תמיכה בסינון של שדות חוזרים בתוך שדות.

לדוגמה:

ב-item יש את השדה colors, שמכיל ערכי מחרוזת כמו "red", "blue" ו-"yellow".

  • הפונקציה item.colors:("red") מחזירה את כל הפריטים שיש להם הערך "red" בשדה colors.
  • הפונקציה item.colors:("red" "yellow") מחזירה את כל הפריטים שיש להם גם "red" וגם "yellow" בשדה colors.
  • הפונקציה item.colors:("red" OR "yellow") מחזירה את כל הפריטים שיש בהם "red" או "yellow" בשדה colors.

ב-item יש גם שדה tools חוזר שהוא אובייקט מורכב עם שדה סקלרי shape, שהערכים שלו יכולים להיות "square" או "round".

  • הפונקציה item.tools.shape:("square") מחזירה את כל הפריטים שיש להם כלים בצורת "square".
  • הפונקציה item.tools.shape:("square" "round") מחזירה את כל הפריטים שכוללים גם כלי בצורת "square" וגם כלי בצורת "round".
  • הפונקציה item.tools.shape:("square" OR "round") מחזירה את כל הפריטים שמכילים כלי צורות "square" או כלי בצורת "round".

שדות מקננים שלא אוכלסו

שדות מקוננים הם שדות משנה של שדות ברמה הבסיסית (root). לדוגמה, השדה shape ב-item.tools.shape הוא שדה מקונן של items.tools.

שדות ברמה הבסיסית (root) מוגדרים כברירת מחדל כ-FALSE. כברירת מחדל, שדות מקננים לא מאוכלסים.

אובייקטים עם שדות מקוננים שלא מולאו לא מוחזרים על ידי מסננים שליליים (!=).

לדוגמה:

ל-item.tools יש טיפוסים בני מנייה (enum) מסוג size שאפשר להגדיר את הערך שלו ל-"SMALL", ל-"MEDIUM" או ל-"LARGE".

אם יש לכם את הפריטים הבאים:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

קריאה ל-items.list עם המסנן השלילי "tools.size != SMALL" מחזירה את הערך הבא:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

מכיוון שלא הוגדר item.tools.size עבור item3, המסנן השלילי לא מחזיר את האובייקט item3.

דוגמאות

דוגמה התיאור
externalDealId = "123456789" externalDealId עם ערך המחרוזת "123456789".
advertiserId:93641

advertiserId = 93641		 advertiserId שהערך שלו הוא מספר שלם 93641.
isSetupComplete = true

isSetupComplete:TRUE

isSetupComplete = (True)		 isSetupComplete שווה ל-TRUE.
updateTime > "2018-02-14T11:09:19.378Z" updateTime מאוחר יותר מ-14/2/2018 בשעה 11:09:19.378 UTC
displayName = "proposal" AND proposalRevision = 3

displayName = "proposal" proposalRevision = 3		 למחרוזת displayName יש ערך זהה של 'הצעה' וגם הצעה לתיקון שווה ל-3.
displayName = "proposal" OR proposalRevision = 3 ל-displayName יש ערך המחרוזת 'הצעה' או שההצעה 'תיקון' שווה ל-3.
NOT displayName = "proposal"

displayName != "proposal"		 displayName לא שווה ל "הצעה".
proposalState = (PROPOSED OR BUYER_ACCEPTED)

proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED		 ב-proposalState יש ערך טיפוסים בני מנייה (enum) ששווה ל-PROPOSED OR BUYER_Receive.
proposalState = (PROPOSED AND BUYER_ACCEPTED)

proposalState = (PROPOSED BUYER_ACCEPTED)

proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED

proposalState = PROPOSED proposalState = BUYER_ACCEPTED		 ב-proposalState יש ערך טיפוסים בני מנייה (enum) ששווה ל-PROPOSED AND BUYER_ בהעלאה
dealName = Test Deal ביטוי אחד (INVALID)
dealName = "Test Deal" dealName שווה ל "מבצע בדיקה".
dealName = (Test Deal) dealName שווה ל "בדיקה" וגם ל "מבצע".
dealName = ("Test1" OR "Test2")

dealName = "Test1" OR dealName = "Test2"		 dealName שווה ל-"Test1" או שווה ל-"Test2".
dealName:* dealName is not null.
dealName:"test"

dealName:test		 הערך dealName מכיל את מחרוזת המשנה 'test'.
dealName:("A B")

dealName:"A B"		 הערך dealName מכיל את מחרוזת המשנה 'A B'.
dealName:(A B)

dealName:"A" AND dealName:"B"		 הערך dealName מכיל את מחרוזת המשנה 'A' ואת מחרוזת המשנה 'B'.
dealName:("A" OR "B" AND "C")

dealName:("A" OR "B" "C")

dealName:"A" OR dealName:"B" AND dealName:"C"

dealName:"A" OR dealName:"B" dealName:"C"

(dealName:"A" OR dealName:"B") AND dealName:"C"

(dealName:"A" OR dealName:"B") dealName:"C"		 השדה dealName מכיל את מחרוזת המשנה "A" או "B", וגם את מחרוזת המשנה "C"
dealName:("A B" C)

dealName:"A B" AND dealName:"C"		 השדה dealName מכיל את מחרוזת המשנה 'A B' וגם את מחרוזת המשנה C.
dealName:("A B" OR C D) השדה dealName מכיל את מחרוזת המשנה 'A B' או 'C', וגם את מחרוזת המשנה 'D'.
dealName:(NOT "A" B)

NOT dealName:"A" AND dealName:"B"

(NOT dealName:"A") AND dealName:"B"

(NOT dealName:"A") dealName:"B"		 השדה dealName לא מכיל אף מחרוזת משנה "A" וגם את מחרוזת המשנה "B".
dealName:(NOT "A" OR "B")

NOT dealName:"A" OR dealName:"B"
(NOT dealName:"A") OR dealName:"B"		 העמודה dealName לא מכילה אף מחרוזת משנה "A" או את מחרוזת המשנה "B".