این راهنما نحو فیلتر لیست و نحوه فیلتر انواع منابع مختلف را شرح می دهد.
برخی از روشهای API میتوانند فیلتری را برای محدود کردن منابع بازگشتی در پاسخ بپذیرند.
خلاصه
این بخش یک نمای کلی از ساختار نحوی فیلتر لیست ارائه می دهد.
فیلتر رشته ای است که حاوی یک
expression
است. یکexpression
ترکیبی بولی از مقایسه ها است:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
یک فیلد منبع را با یک مقدار مطابقت می دهد. شما می توانید از تمام عملگرهای مقایسه رایج استفاده کنید.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
عملگر
has
، دو نقطه (:
)، می تواند در رشته ها و فیلدهای تکراری استفاده شود. برای جزئیات بیشتر به بخش Has operator مراجعه کنید.می توانید از انواع مقادیر زیر در فیلترها استفاده کنید:
- شماره
- رشته های
- عبارات پرانتز شده
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
مراجعه کنید.
سمت راست معمولاً یک مقدار اسکالر است که به نوع فیلد تبدیل میشود و با آن مقایسه میشود. برای جزئیات بیشتر به بخش Value Literal Types مراجعه کنید.
سمت راست مقایسه را میتوان بهعنوان یک ترکیب بولی پرانتزی از مقادیر تحت اللفظی و/یا عبارات بولی که فقط حاوی مقادیر تحت اللفظی (قبل یا بدون 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 | نام یک نوع شمارش لفظی. Enum ها به حروف بزرگ و کوچک حساس هستند. | FINALIZED با Finalized یکی نیست |
رشته | هر رشته ای که حاوی متن اسکی 7 بیتی یا کدگذاری شده UTF-8 باشد. از علامت نقل قول جاسازی شده باید با یک اسلش فرار کرد. رشته های نقل قول نشده با فاصله سفید به عنوان "AND" ضمنی در بین همه کلمات پس از تقسیم رشته به فاصله سفید در نظر گرفته می شوند. |
|
مهر زمان | رشته ای در قالب استاندارد ISO8601. | "2014-10-02T15:01:23.045Z" |
عملگرهای مقایسه
در اینجا عملگرهای مقایسه وجود دارد:
- کمتر یا مساوی با:
"<="
- کمتر از:
"<"
- بزرگتر یا مساوی با:
">="
- بزرگتر از:
">"
- برابر نیست با:
"!="
- برابر با:
"="
- دارد:
":"
این عملگرها برای انواع مقادیر Double، Integer، Boolean، Enum و Timestamp اعمال می شوند.
دارای اپراتور
می توانید از عملگر HAS
( :
) برای عملیات ویژه در زمینه های زیر استفاده کنید:
- رشته های فرعی
- هنگامی که عملگر
HAS
برای مقایسه مقادیر یک ستون رشته با یک رشته استفاده می شود، عملگر به عنوان یک عملیات زیر رشته ای عمل می کند. به عنوان مثال،name:"abcd"
همه مواردی را کهname
رشته ای حاوی"abcd"
است را برمی گرداند. - بررسی وجود
- هنگامی که از عملگر
HAS
با کاراکتر ویژه*
استفاده می کنید، عملگرHAS
مقادیر غیر تهی را بررسی می کند. به عنوان مثال،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
است.
فیلدهای سطح ریشه به طور پیش فرض نادرست هستند. فیلدهای تودرتو به طور پیش فرض خالی از جمعیت هستند.
اشیاء با فیلدهای تودرتو خالی از جمعیت توسط فیلترهای منفی ( !=
) برگردانده نمی شوند.
در اینجا یک مثال است:
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 دیرتر از 2018/02/14 11:09:19.378 UTC است |
displayName = "proposal" AND proposalRevision = 3 | رشته displayName مقدار "پیشنهاد" یکسان دارد و پیشنهاد Revision برابر با 3 است. |
displayName = "proposal" OR proposalRevision = 3 | displayName دارای مقدار رشته ای "پیشنهاد" است یا پیشنهاد Revision برابر با 3 است. |
NOT displayName = "proposal" | displayName برابر با "پیشنهاد" نیست. |
proposalState = (PROPOSED OR BUYER_ACCEPTED) | proposalState یک مقدار enum دارد که یا برابر با PROPOSED یا BUYER_ACCEPTED است. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) | proposalState یک مقدار enum دارد که برابر با PROPOSED و BUYER_ACCEPTED است |
dealName = Test Deal | عبارت INVALID |
dealName = "Test Deal" | dealName برابر با "Test Deal" است. |
dealName = (Test Deal) | dealName برابر با "Test" و همچنین برابر با "Deal" است. |
dealName = ("Test1" OR "Test2") | dealName یا برابر با "Test1" یا برابر با "Test2" است. |
dealName:* | dealName is not null. |
dealName:"test" | dealName شامل زیر رشته "test" است. |
dealName:("AB") | dealName شامل زیر رشته "AB" است. |
dealName:(AB) | dealName شامل زیر رشته "A" و زیر رشته "B" است. |
dealName:("A" OR "B" AND "C") | dealName شامل یکی از زیر رشته های "A" یا "B" و همچنین حاوی زیررشته "C" است. |
dealName:("AB" C) | dealName شامل زیر رشته "AB" و همچنین شامل زیر رشته "C" است. |
dealName:("AB" OR CD) | dealName شامل زیر رشته "AB" یا "C" و همچنین حاوی زیررشته "D" است. |
dealName:(NOT "A" B) | dealName شامل هیچ زیررشته ای "A" نیست و همچنین حاوی زیررشته "B" است. |
dealName:(NOT "A" OR "B") | dealName شامل هیچ زیر رشته ای "A" یا حاوی زیررشته "B" نیست. |