במדריך הזה נתאר את התחביר של מסנני הרשימה ונסביר איך לסנן בסוגי המשאבים.
חלק מהשיטות של ה-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}
הפעולות מבוצעות בסדר הבא:
NOT
OR
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")
סוגים של ערך ליטראלי
אפשר לסווג את הערך הימני של אופרטור השוואה למספר ו ייצוגים מילוליים של מחרוזת.
מספר
הקטע הזה מתאר את הייצוג של ייצוגים מספריים.
סוג | הגדרה | דוגמאות |
---|---|---|
כפול | כל מספר שמכיל נקודה עשרונית, עם או בלי סימן ('-') נחשב לכפולה. |
|
מספר שלם | כל מספר שאין בו נקודה עשרונית, עם או בלי סימן ("-") נחשב כמספר שלם. |
|
מחרוזת
בקטע הזה מתוארים הסוגים שניתן לכתוב כליטרל מחרוזת תחביר של מסננים.
סוג | הגדרה | דוגמאות |
---|---|---|
בוליאני | TRUE או FALSE בכל סוג של אות. |
|
Enum | השם של ליטרל סוג ספירה. הערכים האלה הם תלויי אותיות רישיות (case-sensitive). |
FINALIZED לא זהה ל-Finalized
|
מחרוזת | כל מחרוזת שמכילה טקסט בקידוד UTF-8 או טקסט ASCII בגרסת 7 ביט. כשמוסיפים מירכאות מוטמעות, צריך לסמן אותן בתו בריחה (escape) באמצעות לוכסן הפוך. מחרוזות ללא מרכאות עם רווחים לבנים נחשבות כ-'AND' מרומז בין כל המילים אחרי פיצול המחרוזת ברווח לבן. |
|
חותמת זמן | מחרוזת בפורמט הסטנדרטי ISO8601. |
"2014-10-02T15:01:23.045Z"
|
אופרטורים להשוואה
אלה האופרטורים להשוואה:
- קטן מ- או שווה ל-:
"<="
- פחות מ-
"<"
- גדול מ- או שווה ל-:
">="
- גדול מ-:
">"
- לא שווה ל-:
"!="
- שווה ל:
"="
- כולל:
":"
האופרטורים האלה חלים על הערך Double, Integer, Boolean, Enum ו-Timestamp שונים.
כולל מפעיל
אפשר להשתמש באופרטור HAS
(:
) לביצוע פעולות מיוחדות:
שדות:
- מחרוזת משנה
- כשהאופרטור
HAS
משמש להשוואת ערכים בעמודת מחרוזת מחרוזת, האופרטור יפעל כפעולה של מחרוזת משנה. לדוגמה, הפונקציהname:"abcd"
מחזירה את כל המופעים שבהםname
הוא מחרוזת שמכילה"abcd"
. - בדיקת נוכחות
- כשמשתמשים באופרטור
HAS
עם התו המיוחד*
, האופרטורHAS
בודק אם יש ערכים שהם לא null. לדוגמה, הפונקציהname:*
מחזירה את כל המופעים שבהם הערך שלname
לא אפס, חסר או לא מוגדר. - כשמשתמשים באופרטור
HAS
עם ערכים שאינם מחרוזות, הוא מתנהג בדיוק כמו האופרטורEQUALS
(=
). לדוגמה,isCompleted:true
מתנהג במסגרת בדיוק כמוisCompleted = true
. - שדות חוזרים
אפשר להשתמש באופרטור
HAS
(:
) כדי לסנן לפי משאב API חוזר כל עוד התנאים הבאים מתקיימים:- יש רק רכיב אחד חוזר לאורך הנתיב של מזהה השדה
- המזהה האחרון של נתיב השדה הוא סקלרי
אי אפשר לסנן שדות חוזרים בתוך שדות.
לדוגמה:
בפונקציה
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. |
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 יש ערך זהה – 'הצעה' AND הצעה לתיקון שווה ל-3. |
displayName = "proposal" OR proposalRevision = 3 |
ערך המחרוזת displayName הוא "הצעה" או שההצעה הקודמת שווה ל-3. |
NOT displayName = "proposal" |
displayName לא שווה ל"הצעה". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
ל-proposalState יש ערך 'טיפוסים בני מנייה (enum)' שהוא שווה ל-PROPOSED או רצ_קיבלתם. |
proposalState = (PROPOSED AND 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" או שווה ל-"Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName מכיל את מחרוזת המשנה test (בדיקה). |
dealName:("A B") |
dealName מכיל את מחרוזת המשנה A B. |
dealName:(A B) |
dealName מכיל את מחרוזת המשנה "A" ואת מחרוזת המשנה B. |
dealName:("A" OR "B" AND "C") |
dealName מכיל את מחרוזת המשנה A או 'B' AND מכיל גם את מחרוזת המשנה C |
dealName:("A B" C) |
dealName מכיל את מחרוזת המשנה A B וגם מכיל את מחרוזת המשנה C. |
dealName:("A B" OR C D) |
dealName מכיל את מחרוזת המשנה A B או C, וגם מכיל את מחרוזת המשנה D. |
dealName:(NOT "A" B) |
dealName לא מכיל מחרוזת משנה "A" וגם מכיל את מחרוזת המשנה B. |
dealName:(NOT "A" OR "B") |
dealName לא מכיל מחרוזת משנה "A" או מכיל את מחרוזת המשנה 'B'. |