Liste yanıtlarını filtrele

Display & Video 360 API'deki çoğu hizmet, kaynakların toplu alınması için bir LIST yöntemi sağlar. Bu LIST yöntemleri genellikle sonuçların filter sorgu parametresiyle filtrelenmesini destekler. Yalnızca ihtiyacınız olanları alarak API kullanımınızı optimize etmek için bu parametreyi kullanın.

Bu kılavuzda, filter parametresinin etkili bir şekilde nasıl kullanılacağı gösterilmektedir.

Filtre yapısı

filter parametre değeri, AND veya OR operatörleriyle birleştirilebilen ve parantez kullanılarak gruplandırılabilen bir veya daha fazla kısıtlamadan oluşan bir dizedir.

Kısıtlamalar {field} {operator} {value} biçimindedir. Bir örnek verelim:

entityStatus="ENTITY_STATUS_ACTIVE"

Filtre dizesi 500 karakterden uzun olamaz. Filtre dizeniz 500 karakteri aşıyorsa aşağıdakilerden birini yapın:

  • Mantığı birden fazla filtre dizesine bölün ve ayrı LIST isteklerini kullanarak kaynakları alın.
  • Filtre dizesinden mantığın bir kısmını kaldırın ve alınan kaynakları yerel olarak filtrelemek için kullanın.

Mantığın doğru şekilde uygulandığından emin olmak için kısıtlama değerlerini tırnak içine alın.

İstemci kitaplığı kullanmadan doğrudan LIST çağrıları yapıyorsanız filtre dizelerinizi URL olarak kodlayın.

Sorgularınızı biçimlendirmeyle ilgili daha fazla ayrıntı için Kısıtlamalar arasındaki mantık bölümünü inceleyin.

Filtrelenebilir alanlar

Her LIST yönteminin filtrelenebilir alanları, yöntemin filter parametre açıklamasında listelenmiştir. Çoğu durumda, kaynağın standart alanlarının bir alt kümesine göre filtreleme yapabilirsiniz. Nadiren de olsa yalnızca filtreleme için kullanabileceğiniz ek alanlar bulunur.

Parametrenin açıklamasındaki her alan, aşağıdaki karşılaştırılabilir operatörlerden en az birini destekler:

Karşılaştırılabilir Operatörler
EQUALS (=) Kaynak alanı değeri belirtilen değere eşit.

Örnek: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Kaynak alanı değeri, belirtilen değerden küçük veya bu değere eşit. Genellikle bir tarih veya tarih ve saati karşılaştırırken kullanılır.

Örnek: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Kaynak alanı değeri belirtilen değerden büyük veya bu değere eşit. Genellikle bir tarih veya tarih ve saati karşılaştırırken kullanılır.

Örnek: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Kaynak alanı değeri, verilen değeri içerir. Kaynak alanı bir dizeyse belirtilen değerin mevcut bir alt dize olup olmadığını kontrol eder. Kaynak alanı bir diziyse dizinin verilen değeri içerip içermediğini kontrol eder.

Örnek: lineItemIds:"1234"

Parametrenin açıklamasındaki alan için operatör belirtilmemişse yalnızca EQUALS (=) operatörünü kullanabilirsiniz. Bazı alanlar birden çok operatörü destekler.

Tarihler ve saatler gibi bazı filtrelenebilir alanlar, karşılaştırılabilir değerin belirli bir biçimi takip etmesini gerektirir. Biçim, filter parametresinin açıklamasındaki alanın yanında belirtilir.

Kısıtlamalar arasındaki mantık

LIST isteğinizdeki yanıtı daraltmak veya genişletmek için birden fazla kısıtlamayı birleştirebilirsiniz.

Genellikle AND ve OR mantıksal operatörleriyle birden fazla kısıtlamayı birleştirebilirsiniz. Her LIST yöntemi, hangi operatörleri desteklediğini belirtir. Bazı yöntemler, filter parametresinde yalnızca tek bir kısıtlama kullanılmasını destekler.

AND veya OR mantıksal operatörleriyle filtre dizeleri oluştururken aşağıdaki kısıtlamaları göz önünde bulundurun:

  • Farklı alanları filtreleyen veya aynı alanı farklı şekilde filtreleyen kısıtlamalar veya kısıtlama grupları arasında AND kullanılmalıdır. Bazı örnekler:
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
  • OR, aynı alana göre filtrelenen bağımsız kısıtlamalar arasında kullanılmalıdır. Aşağıda bir örnek verilmiştir:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • OR aracını iki kısıtlama grubunu birleştirmek için kullanamazsınız. Bunun yerine farklı filtre değerlerine sahip birden fazla LIST isteği kullanın. Örneğin aşağıdaki ayrı LIST isteklerini kullanın:

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    Aşağıdakileri birleştirmek için OR operatörünü kullanmayın:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • Parantezler, bir filtre dizesinde kısıtlamaları gruplandırmak için kullanmıyorsanız ima edilebilir. Örneğin, aşağıdaki filtre dizesi:

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    şu şekilde yorumlanır:

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")