نحو و کاربرد فیلتر را فهرست کنید

این راهنما نحو فیلتر لیست و نحوه فیلتر انواع منابع مختلف را شرح می دهد.

برخی از روش‌های 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}

عملیات به ترتیب زیر انجام می شود:

  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 مراجعه کنید.

سمت راست معمولاً یک مقدار اسکالر است که به نوع فیلد تبدیل می‌شود و با آن مقایسه می‌شود. برای جزئیات بیشتر به بخش 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")

ارزش انواع تحت اللفظی

مقدار سمت راست عملگر مقایسه را می توان به حروف عددی و رشته ای دسته بندی کرد.

شماره

این بخش نمایش لفظ های عددی را توضیح می دهد.

تایپ کنید تعریف نمونه ها
دوبل هر عددی که دارای یک نقطه اعشار باشد، با یا بدون علامت ("-") به عنوان یک دو تلقی می شود.
  • 1234.567
  • -789.0123
عدد صحیح هر عددی که دارای نقطه اعشار، با یا بدون علامت ("-") نباشد، به عنوان یک عدد صحیح در نظر گرفته می شود.
  • 1234
  • -789

رشته

این بخش انواعی را که می توانید به صورت یک رشته در دستور فیلتر بنویسید توضیح می دهد.

تایپ کنید تعریف نمونه ها
بولی TRUE یا FALSE در هر مورد.
  • TRUE
  • True
  • "true"
Enum نام یک نوع شمارش لفظی. Enum ها به حروف بزرگ و کوچک حساس هستند. FINALIZED با Finalized یکی نیست
رشته هر رشته ای که حاوی متن اسکی 7 بیتی یا کدگذاری شده UTF-8 باشد. از علامت نقل قول جاسازی شده باید با یک اسلش فرار کرد. رشته های نقل قول نشده با فاصله سفید به عنوان "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 اعمال می شوند.

دارای اپراتور

می توانید از عملگر HAS ( : ) برای عملیات ویژه در زمینه های زیر استفاده کنید:

رشته های فرعی
هنگامی که عملگر HAS برای مقایسه مقادیر یک ستون رشته با یک رشته استفاده می شود، عملگر به عنوان یک عملیات زیر رشته ای عمل می کند. به عنوان مثال، name:"abcd" همه مواردی را که name رشته ای حاوی "abcd" است را برمی گرداند.
بررسی وجود
هنگامی که از عملگر HAS با کاراکتر ویژه * استفاده می کنید، عملگر HAS مقادیر غیر تهی را بررسی می کند. به عنوان مثال، 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 است.

فیلدهای سطح ریشه به طور پیش فرض نادرست هستند. فیلدهای تودرتو به طور پیش فرض خالی از جمعیت هستند.

اشیاء با فیلدهای تودرتو خالی از جمعیت توسط فیلترهای منفی ( != ) برگردانده نمی شوند.

در اینجا یک مثال است:

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 دیرتر از 2018/02/14 11:09:19.378 UTC است
displayName = "proposal" AND proposalRevision = 3

displayName = "proposal" proposalRevision = 3		 رشته displayName مقدار "پیشنهاد" یکسان دارد و پیشنهاد Revision برابر با 3 است.
displayName = "proposal" OR proposalRevision = 3 displayName دارای مقدار رشته ای "پیشنهاد" است یا پیشنهاد Revision برابر با 3 است.
NOT displayName = "proposal"

displayName != "proposal"		 displayName برابر با "پیشنهاد" نیست.
proposalState = (PROPOSED OR BUYER_ACCEPTED)

proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED		 proposalState یک مقدار enum دارد که یا برابر با PROPOSED یا BUYER_ACCEPTED است.
proposalState = (PROPOSED AND BUYER_ACCEPTED)

proposalState = (PROPOSED BUYER_ACCEPTED)

proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED

proposalState = PROPOSED proposalState = 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" OR dealName = "Test2"		 dealName یا برابر با "Test1" یا برابر با "Test2" است.
dealName:* dealName is not null.
dealName:"test"

dealName:test		 dealName شامل زیر رشته "test" است.
dealName:("AB")

dealName:"AB"		 dealName شامل زیر رشته "AB" است.
dealName:(AB)

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:("AB" C)

dealName:"AB" AND dealName:"C"		 dealName شامل زیر رشته "AB" و همچنین شامل زیر رشته "C" است.
dealName:("AB" OR CD) dealName شامل زیر رشته "AB" یا "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" نیست.