I metodi list recuperano più risorse di un tipo di set. Il parametro di query filter consente di specificare i criteri che devono soddisfare le risorse recuperate.
Struttura del filtro
I valori del parametro filter sono stringhe. Queste stringhe sono composte da uno o più
criteri. I criteri sono uniti dagli operatori AND o OR.
Un singolo criterio ha la forma {field} {operator} {value}. Ecco un esempio:
entityStatus="ENTITY_STATUS_ACTIVE"
Le stringhe di filtro sono limitate a 500 caratteri. Se la stringa è troppo lunga:
- Suddividi la logica in stringhe separate. Effettua una chiamata
listcon ogni stringa di filtro. Combina i risultati per creare un unico elenco. - Rimuovi i criteri dalla stringa del filtro. Utilizza i criteri rimossi per filtrare le risorse recuperate localmente.
Racchiudi i valori di un criterio tra virgolette.
Assicurati che le stringhe di filtro siano codificate per l'utilizzo in un URL quando effettui chiamate API direttamente.
Per saperne di più sulla struttura della stringa di filtro, consulta la sezione Criteri di unione.
Criteri di filtro
Ogni metodo di elenco supporta determinati criteri di filtro. La descrizione del parametro filter del metodo elenca questi criteri. I criteri di filtro sono spesso un sottoinsieme dei campi della risorsa recuperata.
Ogni criterio supporta uno o più operatori:
| Operatori paragonabili | |
|---|---|
EQUALS (=)
|
Il campo è uguale al valore specificato. Esempio: |
LESS THAN OR EQUAL TO (<=)
|
Il campo è minore o uguale al valore specificato. Spesso utilizzato per filtrare in base a una data o a una data e ora. Esempio: |
GREATER THAN OR EQUAL TO (>=)
|
Il campo è maggiore o uguale al valore specificato. Spesso utilizzato per filtrare in base a una data o a una data e ora. Esempio: |
HAS (:)
|
Il campo contiene il valore specificato. Se il campo è una stringa, viene verificato se il valore specificato è una sottostringa. Se il campo è un array, verrà verificato se contiene il valore specificato. Esempio: |
Se un criterio non specifica un operatore, supporta solo EQUALS (=).
Un criterio indicherà se è necessario un formato speciale.
Criteri di unione
Combina più criteri per limitare ulteriormente la risposta di list.
Combina i criteri con gli operatori logici AND e OR. Ogni metodo list
specifica quali sono supportati. Alcuni metodi supportano solo filtri con un criterio.
Tieni presenti questi limiti quando utilizzi più criteri:
| Limitazioni ed esempi | |
|---|---|
AND deve combinare limitazioni o gruppi di limitazioni che filtrano campi diversi o che filtrano lo stesso campo in modo diverso.
|
updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
|
OR deve combinare le singole limitazioni che filtrano in base allo stesso campo.
|
(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
|
OR non può combinare due gruppi di limitazioni. Utilizza più richieste list con valori di filtro diversi.
|
Le seguenti due stringhe di filtro devono essere utilizzate in richieste separate e non possono essere combinate utilizzando l'operatore OR:
|
| Le parentesi possono essere implicite per raggruppare le limitazioni anche se non sono incluse. |
La stringa di filtro updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" viene interpretata come updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")
|