ระบุไวยากรณ์และการใช้งานตัวกรอง

คู่มือนี้จะอธิบายไวยากรณ์ตัวกรองรายการและวิธีกรองทรัพยากรประเภทต่างๆ

เมธอด API บางเมธอดยอมรับตัวกรองเพื่อจำกัดทรัพยากรที่แสดงผลในการตอบสนองได้

สรุป

ส่วนนี้จะแสดงภาพรวมโดยสรุปของโครงสร้างไวยากรณ์ตัวกรองรายการ

• ตัวกรองเป็นสตริงที่มี expression expression เป็นชุดค่าผสม บูลีนสำหรับการเปรียบเทียบ

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

• comparison จะจับคู่ช่องทรัพยากรที่มีค่า คุณใช้โอเปอเรเตอร์การเปรียบเทียบทั่วไปได้ทั้งหมด

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

  โอเปอเรเตอร์ has ซึ่งก็คือโคลอน (:) สามารถใช้กับสตริงและช่องที่ซ้ำกันได้ โปรดดูรายละเอียดที่ส่วนมีโอเปอเรเตอร์

• คุณใช้ค่าประเภทต่อไปนี้ในตัวกรองได้

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

ตัวอย่างอีกรายการที่ซับซ้อนมากขึ้นของ ตัวกรองที่เหมือนกัน 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")

ประเภทลิเทอรัลของค่า

ค่าด้านขวาของโอเปอเรเตอร์การเปรียบเทียบจะจัดหมวดหมู่เป็น "ตัวเลข" และ "ลิเทอรัลสตริง" ได้

ตัวเลข

ส่วนนี้อธิบายการแสดงลิเทอรัลที่เป็นตัวเลข

Type	คำจำกัดความ	ตัวอย่าง
ดับเบิล	จำนวนที่มีจุดทศนิยมที่มีหรือไม่มีเครื่องหมาย ("-") จะถือว่าเป็น Double	1234.567 -789.0123
จำนวนเต็ม	ตัวเลขที่ไม่มีจุดทศนิยม หรือมีหรือไม่มีเครื่องหมาย ("-") จะถือว่าเป็นจำนวนเต็ม	1234 -789

สตริง

ส่วนนี้อธิบายประเภทที่คุณจะเขียนเป็นสตริงลิเทอรัลในไวยากรณ์ของตัวกรองได้

หมายเหตุ: สตริงลิเทอรัลอาจเป็นเครื่องหมายอัญประกาศคู่ (" ") หรือไม่ใส่ก็ได้ คุณไม่สามารถใช้เครื่องหมายคำพูดเดี่ยวเพื่อแสดงแทนสตริงได้ เช่น "ABC DEF" และ ABC DEF เป็นลิเทอรัลสตริง แต่ "ABC DEF" ไม่เป็น

Type	คำจำกัดความ	ตัวอย่าง
บูลีน	TRUE หรือ FALSE ในอักษรตัวใดก็ได้	TRUE True "true"
ค่าแจกแจง	ชื่อของลิเทอรัลประเภทการแจกแจง Enum คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่	FINALIZED ต่างจาก Finalized
สตริง	สตริงที่มีข้อความ ASCII ที่เข้ารหัสแบบ UTF-8 หรือข้อความ ASCII แบบ 7 บิต เครื่องหมายคำพูดที่ฝังต้องกำหนดเป็นอักขระหลีกด้วยแบ็กสแลช สตริงที่ไม่ได้ใส่เครื่องหมายอัญประกาศที่มีช่องว่างจะถือเป็น "และ" โดยนัยในคำทั้งหมดหลังจากแยกสตริงด้วยช่องว่าง	name = "test \"double quotes\"" name=(ABC DEF) เทียบเท่ากับ name=ABC AND name=DEF
การประทับเวลา	สตริงในรูปแบบมาตรฐาน ISO8601	"2014-10-02T15:01:23.045Z"

โอเปอเรเตอร์การเปรียบเทียบ

โอเปอเรเตอร์การเปรียบเทียบมีดังนี้

• น้อยกว่าหรือเท่ากับ: "<="
• น้อยกว่า: "<"
• มากกว่าหรือเท่ากับ: ">="
• มากกว่า: ">"
• ไม่เท่ากับ: "!="
• เท่ากับ: "="
• มี: ":"

โอเปอเรเตอร์เหล่านี้ใช้กับประเภทค่า Double, Integer, บูลีน, Enum และการประทับเวลา

หมายเหตุ: สำหรับค่าที่เก็บไว้เป็นสตริง คุณจะใช้ได้เฉพาะโอเปอเรเตอร์ "!=", "=" และ ":" การเปรียบเทียบสตริงจะไม่พิจารณาตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

มีโอเปอเรเตอร์

คุณใช้โอเปอเรเตอร์ HAS (:) สำหรับการดำเนินการพิเศษได้ในช่องต่อไปนี้

สตริงย่อย

เมื่อใช้โอเปอเรเตอร์ HAS เพื่อเปรียบเทียบค่าในคอลัมน์สตริงกับสตริง โอเปอเรเตอร์จะทำหน้าที่เป็นการดำเนินการสตริงย่อย ตัวอย่างเช่น name:"abcd" จะแสดงผลทุกอินสแตนซ์ที่ name เป็นสตริงที่มี "abcd"

การตรวจสอบการมีอยู่

เมื่อคุณใช้โอเปอเรเตอร์ HAS ที่มีอักขระพิเศษ * โอเปอเรเตอร์ HAS จะตรวจหาค่าที่ไม่ใช่ null ตัวอย่างเช่น name:* จะแสดงผลอินสแตนซ์ทั้งหมดที่ name ไม่เป็นค่าว่าง หายไป หรือไม่กำหนด

เมื่อใช้โอเปอเรเตอร์ HAS กับค่าที่ไม่ใช่สตริง โอเปอเรเตอร์จะเหมือนกับโอเปอเรเตอร์ EQUALS (=) เช่น isCompleted:true จะทำงานในลักษณะเดียวกันกับ isCompleted = true

เขตข้อมูลที่ซ้ำได้

คุณใช้โอเปอเรเตอร์ HAS (:) เพื่อกรองในช่องทรัพยากร API ที่ซ้ำกันได้ตราบใดที่เงื่อนไขต่อไปนี้เป็นจริง

1. มีคอมโพเนนต์ที่ซ้ำกันเพียง 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 มีค่า "ข้อเสนอ" ที่เหมือนกันกับ "การแก้ไขข้อเสนอ" เท่ากับ 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 หรือ 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 AND BUYER_ACCEPTED
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" 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"