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

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

เมธอด 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 ระหว่างการเปรียบเทียบได้ ตัวอย่างเช่น URL ต่อไปนี้ จะเหมือนกัน

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 ที่ซับซ้อนซึ่งมีฟิลด์อีก 1 รายการ ฟิลด์ 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")

ประเภทตัวอักษรของค่า

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

ตัวเลข

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

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

สตริง

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

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

ประเภท	คำจำกัดความ	ตัวอย่าง
บูลีน	TRUE หรือ FALSE ในรูปแบบตัวอักษรใดก็ได้	TRUE True "true"
ค่าแจกแจง	ชื่อของลิเทอรัลประเภทการแจงนับ Enum จะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่	FINALIZED ไม่เหมือนกับ Finalized
สตริง	สตริงที่มีข้อความที่เข้ารหัส UTF-8 หรือ ASCII แบบ 7 บิต เครื่องหมายคำพูดแบบฝังจะต้องกำหนดเป็นอักขระหลีกด้วยแบ็กสแลช ระบบจะถือว่าสตริงที่ไม่ใส่เครื่องหมายคำพูดแต่มีการเว้นวรรคเป็น "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. มีคอมโพเนนต์ซ้ำเพียง 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 มี size enum ซึ่งตั้งค่าได้เป็น "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 หรือ 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 มีค่าเท่ากับ "Test" และเทียบเท่ากับ "ดีล"
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" และมีสตริงย่อย "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"