Filtruj odpowiedzi na liście

Większość usług w Interfejs Video 360 API udostępnia metodę LIST do zbiorczego pobierania i zasobami Google Cloud. Te metody LIST zwykle obsługują filtrowanie wyników za pomocą filter parametr zapytania. Za pomocą tego parametru możesz zoptymalizować wykorzystanie interfejsu API tylko przez pobierania potrzebnych informacji.

Z tego przewodnika dowiesz się, jak skutecznie korzystać z parametru filter.

Struktura filtra

Wartość parametru filter to ciąg znaków zawierający co najmniej 1 ograniczenie które można łączyć z operatorami AND lub OR i grupować za pomocą funkcji nawiasy.

Ograniczenia mają postać {field} {operator} {value}. Oto przykład:

entityStatus="ENTITY_STATUS_ACTIVE"

Długość ciągu znaków filtra nie może przekraczać 500 znaków. Jeśli ciąg filtra przekracza 500 znaków, wykonaj jedną z tych czynności:

  • Podziel logikę na kilka ciągów filtrów i pobierz zasoby za pomocą osobne żądania LIST.
  • Usuń część instrukcji z ciągu filtra i użyj jej do filtrowania lokalnie pobiera zasoby.

Wartości ograniczeń umieść w cudzysłowach, aby zapewnić prawidłowe działanie logiczne.

Zakoduj ciągi filtra w adresie URL, jeśli wykonujesz wywołania funkcji LIST bezpośrednio bez za pomocą biblioteki klienta.

Więcej informacji o formatowaniu znajdziesz w sekcji Funkcje logiczne między ograniczeniami. zapytania.

Pola możliwe do filtrowania

Pola możliwe do filtrowania każdej metody LIST są wymienione w tabeli filter metody opis parametru. W większości przypadków możesz filtrować według podzbioru standardowymi. W rzadkich przypadkach dostępne są dodatkowe pola, których możesz użyć, tylko do filtrowania.

Każde pole w opisie parametru obsługuje co najmniej jedną z tych wartości porównywalnych operatorów:

Porównywalne operatory
EQUALS (=) Wartość pola zasobu jest równa podanej wartości.

Przykład: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Wartość pola zasobu jest mniejsza od podanej wartości lub jej równa. Często używane podczas porównywania daty lub daty i godziny.

Przykład: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Wartość pola zasobu jest większa od podanej wartości lub jej równa. Często używane podczas porównywania daty lub daty i godziny.

Przykład: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Wartość pola zasobu zawiera podaną wartość. Jeśli pole zasobu to ciągu znaków, sprawdzi, czy podana wartość jest istniejącym podłańcuchem. Jeśli pole zasobu jest tablicą, sprawdzi, czy tablica zawiera podaną .

Przykład: lineItemIds:"1234"

Jeśli w polu w opisie parametru nie określono żadnych operatorów, może używać tylko operatora EQUALS (=). Niektóre pola obsługują wiele operatorów.

Niektóre pola możliwe do filtrowania, np. dla dat i godzin, wymagają podania wartości porównywalna wartość do określonego formatu. Format jest podany obok pole w opisie parametru filter.

Logika między ograniczeniami

Możesz łączyć wiele ograniczeń, aby zawęzić lub rozszerzyć odpowiedzi na Prośba o: LIST.

Zwykle możesz łączyć kilka ograniczeń z tymi atrybutami AND i OR operatory logiczne. Każda metoda LIST określa obsługiwane operatory. Niektóre metody obsługują w parametrze filter tylko 1 ograniczenie.

Podczas tworzenia ciągów znaków za pomocą funkcji AND weź pod uwagę te ograniczenia lub operatory logiczne OR:

  • AND należy stosować pomiędzy ograniczeniami lub grupami ograniczeń, które filtrować różne pola lub odfiltrowywać to samo pole w inny sposób. Oto kilka przykładów:
    • 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")
  • Parametr OR musi być używany między poszczególnymi ograniczeniami, które filtrują według tego samego kryterium . Oto przykład:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • Nie możesz użyć właściwości OR do połączenia 2 grup ograniczeń. Użyj wielu opcji Zamiast tego LIST żądania z innymi wartościami filtra. Na przykład użyj wartości następujące osobne żądania (LIST):

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

    Nie używaj operatora OR do ich łączenia:

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

  • Nawiasy mogą być domniemane, jeśli nie używasz ich do grupowania ograniczeń w ciągu filtra. Na przykład ten ciąg filtra:

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

    jest interpretowany jako:

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