Składnia i wykorzystanie filtra listy

W tym przewodniku opisano składnię filtra listy i sposób filtrowania typów zasobów.

Niektóre metody interfejsu API akceptują filtr w celu ograniczenia zasobów zwracanych w .

Podsumowanie

W tej sekcji znajdziesz krótkie omówienie struktury składni filtra listy.

• Filtr to ciąg znaków zawierający expression. Wartość expression jest wartością logiczną kombinacja porównań:

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

• comparison odpowiada polu zasobu z wartością. Możesz użyć wszystkich funkcji najczęściej używane operatory porównania.

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

  Operator has, dwukropek (:), może być używany w ciągach znaków i powtórzone . Więcej informacji znajdziesz w sekcji Zawiera operator.

• W filtrach możesz używać tych typów wartości:

  • Numbers
  • Strings
  • Wyrażenia w nawiasach

  value = number| string | "*" | "(" expression ")"
  

• Ciągi mogą zawierać takie wartości:

  • Dowolny tekst
  • Wartość logiczna
  • Wartości typu enum
  • Sygnatury czasowe

Wyrażenia logiczne

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

Operacje są wykonywane w tej kolejności:

1. NOT
2. OR
3. AND

Na przykład te wyrażenia są równoważne:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

W porównaniach możesz pomijać operator AND. Na przykład: filtry są takie same:

c=d AND e=f

c=d e=f

Możesz użyć łącznika (-) zamiast elementu NOT. Parametr nie może między łącznikiem (-) a poniższym porównaniem. Na przykład parametr te filtry są takie same:

NOT e=f

-e=f

Porównania

W tej sekcji znajdziesz kilka porównań funkcji "name OP value":

comparison = name OP value

gdzie

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

Po lewej stronie porównania znajduje się nazwa ścieżki pola zasobu API. Nazwa składa się z serii identyfikatorów zasobów połączonych kropką (.). Po każdym identyfikatorze pola występuje kolejny poziom nazw tego pola. Dla: załóżmy, że zasób ma złożone pole item, które ma też inne złożone pole tool, które zawiera pole o nazwie shape. W filtrze dla tego zasobu, należy określić kształt o nazwie item.tool.shape.

Prawa strona jest zwykle wartością skalarną, która jest konwertowana na i porównywać je z nim. Zobacz typy literatów wartości. .

Prawa strona porównania może być również wyrażona za pomocą wartości logicznej w nawiasach kombinacja wartości literałów lub wyrażeń logicznych, która zawiera tylko wartości literału (poprzedzone ciągiem NOT lub bez niego). Nazwa po lewej stronie oraz do każdej wartości jest stosowany operator porównania. Na przykład parametr te filtry są takie same:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

Oto kolejny, bardziej złożony przykład dwóch równoważnych filtry:

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

Typy literału wartości

Wartość po prawej stronie operatora porównania można podzielić na Literały łańcuchowe.

Liczba

W tej sekcji opisano reprezentację literałów liczbowych.

Typ	Definicja	Przykłady
Liczba zmiennoprzecinkowa	Dowolna liczba zawierająca separator dziesiętny (ze znakiem „-”) lub bez niego. jest traktowany jako liczba zmiennoprzecinkowa.	1234 567 -789,0123
Liczba całkowita	Dowolna liczba bez kropki dziesiętnej (ze znakiem lub bez niego) („-”) jest traktowany jako liczba całkowita.	1234 -789

Ciąg znaków

W tej sekcji opisano typy, które można zapisać jako literał ciągu znaków w funkcji składni filtra.

Uwaga: literał ciągu znaków może być umieszczony w podwójnym cudzysłowie (" ") lub bez cudzysłowu. Nie możesz użyć cudzysłowy reprezentujące literał łańcuchowy. Na przykład „ABC DEF” i ABC DEF są literałami łańcuchowymi, ale „ABC DEF” jednak nie.

Typ	Definicja	Przykłady
Wartość logiczna	TRUE lub FALSE, bez względu na wielkość liter.	TRUE True "true"
Typ wyliczeniowy	Nazwa literału typu wyliczenia. W wyliczeniach wielkość liter ma znaczenie.	FINALIZED to nie to samo co Finalized
Ciąg znaków	Dowolny ciąg znaków zawierający tekst zakodowany w UTF-8 lub 7-bitowy kod ASCII. Umieszczone cudzysłowy muszą być zastąpione ukośnikiem lewym. Ciągi bez cudzysłowu z odstępami są traktowane jako niejawne „ORAZ” między wszystkimi słowami po podzieleniu ciągu według odstępów.	name = "test \"double quotes\"" name=(ABC DEF) jest tożsame z name=ABC AND name=DEF
Sygnatura czasowa	Ciąg w standardowym formacie ISO8601.	"2014-10-02T15:01:23.045Z"

Operatory porównania

Oto operatory porównania:

• Mniejsze lub równe: "<="
• Mniejsze niż: "<"
• Większe lub równe: ">="
• Większe niż: ">"
• Różne od: "!="
• Równe: "="
• Posiada: ":"

Te operatory mają zastosowanie do wartości liczbowych, liczb całkowitych, wartości logicznych, enum i sygnatury czasowej. .

Uwaga: w przypadku wartości przechowywanych jako ciągi znaków możesz używać tylko "!=", "=" i Operatory ":". W przypadku porównywania ciągów znaków wielkość liter nie ma znaczenia.

Zawiera operatora

Operatora HAS (:) możesz używać do działań specjalnych na tych stronach: pola:

Podłańcuchy

Gdy operator HAS porównuje wartości w kolumnie z ciągami znaków z wartościami w ciągu znaków, operator będzie działać jako operacja na podłańcuchu. Przykład: name:"abcd" zwraca wszystkie wystąpienia, w których name to ciąg znaków zawierający "abcd"

Sprawdzanie obecności

Jeśli używasz operatora HAS ze znakiem specjalnym *, operator HAS szuka wartości innych niż null. Przykład: Funkcja name:* zwraca wszystkie instancje, w których pole name nie ma wartości null, nie ma wartości ani nie jest zdefiniowane.

.

Gdy użyjesz operatora HAS z wartościami, które nie są ciągami znaków, działa on tak samo jak operator EQUALS (=). Na przykład isCompleted:true działa w tak samo jak isCompleted = true.

Pola powtarzane

Możesz użyć operatora HAS (:), aby przefiltrować powtórzony zasób interfejsu API o ile spełnione są te warunki:

1. Na ścieżce identyfikatora pola występuje tylko 1 powtórzony komponent
2. Ostatni identyfikator ścieżki pola jest typu skalarnego

Filtrowanie według zagnieżdżonych pól powtarzanych nie jest obsługiwane.

Oto przykład:

item ma pole colors, które zawiera wartości ciągów znaków takie jak "red", "blue" i "yellow".

• Funkcja item.colors:("red") zwraca wszystkie elementy, które mają wartość "red" w colors.
• item.colors:("red" "yellow") zwraca wszystkie elementy, które mają zarówno "red", jak i "yellow" w polu colors.
• item.colors:("red" OR "yellow") zwraca wszystkie elementy, które zawierają "red" lub "yellow" w polu colors.

item ma również powtarzające się pole tools, które jest obiektem złożonym ze wskaźnikiem skalarnym pole shape, którego wartości mogą być "square" lub "round".

• Funkcja item.tools.shape:("square") zwraca wszystkie elementy, które mają kształt "square" narzędzi.
• item.tools.shape:("square" "round") zwraca wszystkie elementy, które mają zarówno narzędzie w kształcie "square" i "round".
• item.tools.shape:("square" OR "round") zwraca wszystkie elementy, które mają Narzędzie kształtu "square" lub narzędzie w kształcie "round".

.

Uwaga: nie wszystkie pola powtarzane można filtrować. Więcej informacji na temat dotyczące konkretnego zasobu znajdziesz w dokumentacji referencyjnej.

Niewypełnione pola zagnieżdżone

Pola zagnieżdżone to pola podrzędne pól poziomu głównego, np. shape w item.tools.shape to zagnieżdżone pole typu items.tools.

Pola na poziomie głównym mają domyślnie wartość false (fałsz). Zagnieżdżone pola są domyślnie puste.

Obiekty z niewypełnionymi zagnieżdżonymi polami nie są zwracane przez wartości ujemne filtry (!=).

Oto przykład:

item.tools ma wyliczenie size, którego wartość można ustawić na "SMALL", "MEDIUM", lub "LARGE".

Jeśli masz te elementy:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

Wywołanie funkcji items.list z filtrem negatywnym "tools.size != SMALL" zwraca następujące:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

Ponieważ filtr item.tools.size nie został ustawiony dla wartości item3, filtr ujemnych nie zwraca obiekt item3.

Przykłady

Przykład	Opis
externalDealId = "123456789"	externalDealId, który ma wartość ciągu znaków „123456789”.
advertiserId:93641 advertiserId = 93641	advertiserId o wartości całkowitej 93641.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete ma wartość TRUE.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime jest późniejsza niż 14.02.2018 o 11:09:19.378 czasu UTC.
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	Ciąg tekstowy displayName ma identyczną wartość „oferta pakietowa” ORAZ zmiana oferty pakietowej ma wartość 3.
displayName = "proposal" OR proposalRevision = 3	Pole displayName zawiera ciąg znaków „oferta pakietowa” LUB wersja oferty pakietowej ma wartość 3.
NOT displayName = "proposal" displayName != "proposal"	displayName nie równa się „oferta pakietowa”.
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState ma wartość wyliczeniową równą PROPOSED lub BUYER_ACCEPTED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	proposalState ma wartość wyliczeniową równą PROPOSED oraz BUYER_ACCEPTED
dealName = Test Deal	Wyrażenie INVALID
dealName = "Test Deal"	dealName jest równa wartości „Umowa testowa”.
dealName = (Test Deal)	dealName jest równe „Test” oraz „Umowa”.
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName ma wartość równą „Test1” lub „Test2”.
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName zawiera podłańcuch „test”.
dealName:("A B") dealName:"A B"	dealName zawiera podłańcuch „A B”.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName zawiera podłańcuch „A” i podłańcuch „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 zawiera podłańcuch „A” LUB „B” ORAZ zawiera też podłańcuch "C"
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName zawiera podłańcuch „A B” oraz zawiera podłańcuch „C”.
dealName:("A B" OR C D)	dealName zawiera podłańcuch „A B” lub „C” i zawiera również podłańcuch „D”.
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName nie zawiera podłańcucha „A” i zawiera podłańcuch „B”.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName nie zawiera podłańcucha „A” lub zawiera podłańcuch „B”.