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

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

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

סיכום

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

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

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

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

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

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

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

  • iWork Numbers
  • מחרוזת
  • ביטויים בסוגריים

  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")

סוגים של ערך ליטראלי

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

מספר

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

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

מחרוזת

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

הערה: אפשר להקיף את ליטרל המחרוזת במירכאות כפולות (" ") או ללא מירכאות. אי אפשר להשתמש במירכאות בודדות כדי לייצג ליטרל של מחרוזת. לדוגמה, "ABC DEF" ו-ABC DEF הם ייצוגים מילוליים של מחרוזת, אבל 'ABC DEF' היא לא.

סוג	הגדרה	דוגמאות
בוליאני	TRUE או FALSE בכל סוג של אות.	TRUE True "true"
Enum	השם של ליטרל סוג ספירה. הערכים האלה הם תלויי אותיות רישיות (case-sensitive).	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"

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

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

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

האופרטורים האלה חלים על הערך Double, Integer, Boolean, Enum ו-Timestamp שונים.

הערה: לערכים שמאוחסנים כמחרוזות, אפשר להשתמש רק בקיצורים "!=", "=" ו- האופרטורים של ":". השוואת מחרוזות לא תלוית אותיות רישיות (case-sensitive).

כולל מפעיל

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

מחרוזת משנה

כשהאופרטור HAS משמש להשוואת ערכים בעמודת מחרוזת מחרוזת, האופרטור יפעל כפעולה של מחרוזת משנה. לדוגמה, הפונקציה name:"abcd" מחזירה את כל המופעים שבהם name הוא מחרוזת שמכילה "abcd".

בדיקת נוכחות

כשמשתמשים באופרטור HAS עם התו המיוחד *, האופרטור HAS בודק אם יש ערכים שהם לא null. לדוגמה, הפונקציה name:* מחזירה את כל המופעים שבהם הערך של name לא אפס, חסר או לא מוגדר.

כשמשתמשים באופרטור 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".

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

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

שדות בתוך שדות הם שדות משנה של שדות ברמת השורש, לדוגמה shape item.tools.shape הוא שדה מקונן של items.tools.

כברירת מחדל, שדות ברמת הבסיס הם 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/02/2018 11:09:19.378 UTC
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	במחרוזת displayName יש ערך זהה – 'הצעה' AND הצעה לתיקון שווה ל-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 או רצ_קיבלתם.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	ל-proposalState יש ערך 'טיפוסים בני מנייה (enum)' שווה ל-PROPOSED וגם BUYER_ כלליED
dealName = Test Deal	ביטוי INVALID
dealName = "Test Deal"	dealName שווה ל'מבצע בדיקה'.
dealName = (Test Deal)	dealName שווה ל-"Test" וגם שווה ל-"Deal".
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' AND מכיל גם את מחרוזת המשנה 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'.