Liste filtresi söz dizimi ve kullanımı

Bu kılavuzda, liste filtresi söz dizimi ve çeşitli kaynak türlerinin nasıl filtreleneceği açıklanmaktadır.

Bazı API yöntemleri, yanıtta döndürülen kaynakları sınırlamak için filtre kabul edebilir.

Özet

Bu bölümde, liste filtresi söz dizimi yapısına hızlı bir genel bakış sunulmaktadır.

• Filtre, expression içeren bir dizedir. expression, karşılaştırmaların bir Boole kombinasyonudur:

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

• comparison, bir kaynak alanını bir değerle eşleştirir. Yaygın olan tüm karşılaştırma operatörlerini kullanabilirsiniz.

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

  has operatörü olan iki nokta üst üste (:) dizelerde ve tekrarlanan alanlarda kullanılabilir. Ayrıntılar için Operatör var bölümüne bakın.

• Filtrelerde aşağıdaki değer türlerini kullanabilirsiniz:

  • Numbers
  • Dize
  • Parantez içindeki ifadeler

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

• Dizeler aşağıdakileri temsil edebilir:

  • Rastgele metin
  • Boole'lar
  • Enum değerleri
  • Zaman damgaları

Boole ifadeleri

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

İşlemler aşağıdaki sırayla gerçekleştirilir:

1. NOT
2. OR
3. AND

Örneğin, aşağıdaki ifadeler eşdeğerdir:

a OR NOT b AND NOT c OR d

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

Karşılaştırmalar arasında AND operatörünü çıkarabilirsiniz. Örneğin, aşağıdaki filtreler aynıdır:

c=d AND e=f

c=d e=f

NOT için alternatif olarak kısa çizgiyi (-) kullanabilirsiniz. Kısa çizgi (-) ile aşağıdaki karşılaştırma arasında boşluk olamaz. Örneğin, aşağıdaki filtreler aynıdır:

NOT e=f

-e=f

Karşılaştırmalar

Bu bölümde, aşağıdaki gibi "name OP value" karşılaştırmaları açıklanmaktadır:

comparison = name OP value

burada:

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

Karşılaştırmanın sol tarafında, bir API kaynak alanının yol adı gösterilir. Ad, noktayla (.) bağlanan bir dizi kaynak tanımlayıcıdan oluşur. Her alan tanımlayıcısının ardından söz konusu alanın bir sonraki ad düzeyi gelir. Örneğin, shape adlı bir alanı olan ve başka bir karmaşık tool alanına sahip karmaşık item alanına sahip bir kaynağı düşünün. Bu kaynağa ait bir filtrede, şekle item.tool.shape adıyla başvurursunuz.

Sağ taraf genellikle alanın türüne dönüştürülen ve alanla karşılaştırılan skaler bir değerdir. Daha ayrıntılı bilgi için Değişmez Değer türleri bölümüne bakın.

Bir karşılaştırmanın sağ tarafı, yalnızca değişmez değerler (NOT ile veya olmadan) içeren değişmez değerler ve/veya boole ifadelerinin parantez içinde Boole kombinasyonu olarak da ifade edilebilir. Sol taraf adı ve karşılaştırma operatörü, değerlerin her birine uygulanır. Örneğin, aşağıdaki filtreler aynıdır:

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

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

Aşağıda, iki eşdeğer filtreye ilişkin daha karmaşık bir örnek daha verilmiştir:

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

Değer Değişmez Değer türleri

Karşılaştırma operatörünün sağ tarafındaki değer, Sayı ve Dize değişmez değerleri olarak kategorize edilebilir.

Sayı

Bu bölümde sayısal değişmez değerlerin temsili açıklanmaktadır.

Tür	Tanım	Örnekler
Çift kişilik	Ondalık virgül içeren, işareti ("-") olan veya içermeyen tüm sayılar Çift olarak kabul edilir.	1234.567 -789.0123
Tamsayı	Ondalık noktası olmayan, işareti ("-") olan veya içermeyen tüm sayılar tam sayı olarak kabul edilir.	1234 -789

Dize

Bu bölümde, filtre söz diziminde dize değişmez değeri olarak yazabileceğiniz türler açıklanmaktadır.

Not: Bir dize sabit değeri çift tırnak (" ") olabilir veya tırnak içinde olmayabilir. Bir dize sabit değerini temsil etmek için tek tırnak kullanamazsınız. Örneğin, "ABC DEF" ve ABC DEF dize değişmez değerleridir, ancak "ABC DEF" değişmez.

Tür	Tanım	Örnekler
Boole	Büyük-küçük harf kullanımı için TRUE veya FALSE.	TRUE True "true"
Enum	Bir numaralandırma türü sabit değerinin adı. Sıralamalar büyük/küçük harfe duyarlıdır.	FINALIZED, Finalized ile aynı değil
Dize	UTF-8 olarak kodlanmış veya 7 bit ASCII metin içeren tüm dizeler. Yerleştirilmiş tırnak işaretlerinin önüne ters eğik çizgi koyulmalıdır. Boşluk içeren tırnak içinde olmayan dizeler, dize boşlukla bölündükten sonra tüm kelimeler arasında örtülü "AND" olarak değerlendirilir.	name = "test \"double quotes\"" name=(ABC DEF), name=ABC AND name=DEF değerine eşittir
Zaman damgası	ISO8601 standart biçimindeki bir dize.	"2014-10-02T15:01:23.045Z"

Karşılaştırma operatörleri

Karşılaştırma operatörleri şunlardır:

• Küçüktür veya eşittir: "<="
• Şundan küçük: "<"
• Büyüktür veya eşittir: ">="
• Büyüktür: ">"
• Eşit değildir: "!="
• Şuna eşit: "="
• Şuna sahip: ":"

Bu operatörler; Çift, Tamsayı, Boole, Enum ve Zaman Damgası değer türleri için geçerlidir.

Not: Dize olarak depolanan değerler için yalnızca "!=", "=" ve ":" operatörlerini kullanabilirsiniz. Dize karşılaştırması büyük/küçük harfe duyarlı değildir.

Operatörü var

Aşağıdaki alanlarda özel işlemler için HAS operatörünü (:) kullanabilirsiniz:

Alt dizeler

HAS operatörü, dize sütunundaki değerlerin bir dizeyle karşılaştırılması için kullanıldığında operatör bir alt dize işlemi görevi görür. Örneğin name:"abcd", name değerinin "abcd" içeren bir dize olduğu tüm örnekleri döndürür.

Varlık kontrolü

HAS operatörünü * özel karakteriyle kullandığınızda HAS operatörü, null olmayan değerleri kontrol eder. Örneğin name:*, name değerinin null, eksik veya tanımsız olmadığı tüm örnekleri döndürür.

Dize olmayan değerlerle HAS operatörünü kullandığınızda EQUALS (=) operatörüyle aynı şekilde davranır. Örneğin, isCompleted:true, isCompleted = true ile aynı şekilde davranır.

Yinelenen Alanlar

Aşağıdaki koşullar geçerli olduğu sürece, tekrarlanan API kaynak alanını filtrelemek için HAS (:) operatörünü kullanabilirsiniz:

1. Alan tanımlayıcısı yolunda yalnızca bir tekrarlanan bileşen var
2. Alan yolunun son tanımlayıcısı skaler türdedir

İç içe yerleştirilmiş yinelenen alanlarda filtreleme desteklenmez.

Aşağıda bir örnek verilmiştir:

item alanında "red", "blue" ve "yellow" gibi dize değerleri içeren bir colors alanı var.

• item.colors:("red"), colors alanında "red" değerine sahip olan tüm öğeleri döndürür.
• item.colors:("red" "yellow"), colors alanında hem "red" hem de "yellow" içeren tüm öğeleri döndürür.
• item.colors:("red" OR "yellow"), colors alanında "red" veya "yellow" içeren tüm öğeleri döndürür.

item, değerleri "square" veya "round" olabilen skaler alana sahip shape karmaşık bir nesne olan tekrarlanan bir tools alanına da sahiptir.

• item.tools.shape:("square"), "square" şekilli araçları olan tüm öğeleri döndürür.
• item.tools.shape:("square" "round"), hem "square" hem de "round" şeklinde aracı olan tüm öğeleri döndürür.
• item.tools.shape:("square" OR "round"), "square" şekil aracı veya "round" şekilli araç içeren tüm öğeleri döndürür.

Not: Tekrarlanan tüm alanlar filtrelenemez. Belirli bir kaynak hakkında daha fazla bilgi için referans belgeleri inceleyin.

Doldurulmamış iç içe yerleştirilmiş alanlar

İç içe yerleştirilmiş alanlar, kök düzeyindeki alanların alt alanlarıdır. Örneğin item.tools.shape bölgesindeki shape, items.tools için iç içe yerleştirilmiş bir alandır.

Kök düzeyindeki alanlar varsayılan olarak "false" değerine ayarlanır. İç içe yerleştirilmiş alanlar varsayılan olarak doldurulmaz.

İç içe yerleştirilmiş alanları doldurulmamış nesneler, negatif filtreler (!=) tarafından döndürülmez.

Aşağıda bir örnek verilmiştir:

item.tools, değeri "SMALL", "MEDIUM" veya "LARGE" olarak ayarlanabilen bir size sıralamasına sahip.

Aşağıdaki öğelere sahipseniz:

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

"tools.size != SMALL" negatif filtresine sahip bir items.list çağrısı şu sonucu döndürür:

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

item3 için item.tools.size ayarlanmadığından, negatif filtre item3 nesnesini döndürmez.

Örnekler

Örnek	Açıklama
externalDealId = "123456789"	Dize değeri "123456789" olan externalDealId.
advertiserId:93641 advertiserId = 93641	93641 tam sayı değerine sahip advertiserId.
isSetupComplete = true isSetupComplete:TRUE isSetupComplete = (True)	isSetupComplete, DOĞRU'ya eşittir.
updateTime > "2018-02-14T11:09:19.378Z"	updateTime, 14.02.2018 11:09:19.378 UTC tarihinden sonradır
displayName = "proposal" AND proposalRevision = 3 displayName = "proposal" proposalRevision = 3	displayName dizesi aynı "teklif" değerine sahip VE offerRevision değeri 3'e eşit.
displayName = "proposal" OR proposalRevision = 3	displayName, "teklif" dize değerine sahip VEYA offerRevision değeri 3'e eşit.
NOT displayName = "proposal" displayName != "proposal"	displayName, "teklife" eşit değildir.
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState, PROPOSED VEYA BUYER_KABULED değerine eşit bir numaralandırma değerine sahip.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = BUYER_ACCEPTED	proposalState, PROPOSED AND BUYER_KABULED değerine eşit bir numaralandırma değerine sahip
dealName = Test Deal	INVALID ifadesi
dealName = "Test Deal"	dealName, "Test Deal"a eşittir.
dealName = (Test Deal)	dealName hem "Test" hem de "Anlaşma"ya eşittir.
dealName = ("Test1" OR "Test2") dealName = "Test1" OR dealName = "Test2"	dealName, "Test1"e veya "Test2"ye eşittir.
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName, "test" alt dizesini içerir.
dealName:("A B") dealName:"A B"	dealName, "A B" alt dizesini içerir.
dealName:(A B) dealName:"A" AND dealName:"B"	dealName, "A" alt dizesini ve "B" alt dizesini içerir.
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" VEYA "B" alt dizesini içerir VE ayrıca "C" alt dizesini de içerir
dealName:("A B" C) dealName:"A B" AND dealName:"C"	dealName, "A B" alt dizesini ve "C" alt dizesini de içerir.
dealName:("A B" OR C D)	dealName, "A B" veya "C" alt dizesini, ayrıca "D" alt dizesini içerir.
dealName:(NOT "A" B) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName, herhangi bir "A" alt dizesini değil, aynı zamanda "B" alt dizesini de içerir.
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName, "A" alt dizesini veya "B" alt dizesini içermiyor.