Filtra le risposte dell'elenco

La maggior parte dei servizi dell'API Display & Video 360 fornisce un metodo LIST per il recupero collettivo delle risorse. Questi metodi LIST in genere supportano il filtraggio dei risultati tramite un filter parametro di query. Utilizza questo parametro per ottimizzare l'utilizzo dell'API recuperando solo ciò che ti serve.

Questa guida mostra come utilizzare il parametro filter in modo efficace.

Struttura del filtro

Un valore del parametro filter è una stringa costituita da una o più limitazioni che possono essere combinate con gli operatori AND o OR e raggruppate utilizzando le parentesi.

Le restrizioni sono nel formato {field} {operator} {value}. Ecco un esempio:

entityStatus="ENTITY_STATUS_ACTIVE"

La lunghezza della stringa del filtro non può superare i 500 caratteri. Se la stringa del filtro supera i 500 caratteri, esegui una delle seguenti operazioni:

• Suddividi la logica in più stringhe di filtro e recupera le risorse utilizzando richieste LIST separate.
• Rimuovi parte della logica dalla stringa del filtro e utilizzala per filtrare localmente le risorse recuperate.

Racchiudi i valori delle limitazioni tra virgolette per assicurarti che la logica venga applicata correttamente.

Codifica le stringhe dei filtri in URL se effettui chiamate LIST direttamente senza utilizzare una libreria client.

Per ulteriori dettagli sulla formattazione delle query, consulta la sezione Logica tra le limitazioni.

Campi filtrabili

I campi filtrabili di ogni metodo LIST sono elencati nella descrizione del parametro filter. Nella maggior parte dei casi, puoi applicare un filtro in base a un sottoinsieme di campi standard di una risorsa. In alcuni rari casi, sono disponibili campi aggiuntivi che puoi utilizzare solo per filtrare.

Ogni campo nella descrizione del parametro supporta almeno uno dei seguenti operatori confrontabili:

Operatori paragonabili
EQUALS (=)	Il valore del campo della risorsa è uguale al valore specificato. Esempio: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)	Il valore del campo della risorsa è minore o uguale al valore specificato. Spesso utilizzato per confrontare una data o una data e ora. Esempio: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	Il valore del campo della risorsa è maggiore o uguale al valore specificato. Spesso utilizzato per confrontare una data o una data e ora. Esempio: updateTime>="2023-03-01T12:00:00Z"
HAS (:)	Il valore del campo della risorsa contiene il valore specificato. Se il campo della risorsa è una stringa, viene controllato se il valore specificato è una sottostringa esistente. Se il campo della risorsa è un array, viene controllato se l'array contiene il valore fornito. Esempio: lineItemIds:"1234"

Se non sono specificati operatori per il campo nella descrizione del parametro, puoi utilizzare solo l'operatore EQUALS (=). Alcuni campi supportano più operatori.

Alcuni campi filtrabili, ad esempio quelli per date e ore, richiedono che il valore confrontabile segua un formato specifico. Il formato è specificato accanto al campo nella descrizione del parametro filter.

Logica tra le restrizioni

Puoi combinare più limitazioni per restringere o espandere la risposta della richiesta LIST.

In genere, puoi combinare più limitazioni con gli operatori logici AND e OR. Ogni metodo LIST specifica gli operatori supportati. Alcuni metodi supportano solo l'utilizzo di una singola limitazione nel parametro filter.

Tieni presenti le seguenti limitazioni quando crei stringhe di filtro con gli operatori logici AND o OR:

Nota: gli esempi riportati di seguito sono scritti utilizzando le limitazioni dei parametri filter del metodo advertisers.lineItems.list.

• AND deve essere utilizzato tra limitazioni o gruppi di limitazioni che filtrano campi diversi o filtrano lo stesso campo in modo diverso. Ecco alcuni esempi:
  • 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 deve essere utilizzato tra le singole limitazioni che filtrano in base allo stesso campo. Ecco un esempio:
  • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

• Non puoi utilizzare OR per combinare due gruppi di limitazioni. Utilizza invece più richiesteLIST con valori di filtro diversi. Ad esempio, utilizza le seguenti richieste LIST separate:

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

  Non utilizzare l'operatore OR per combinarli:

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

• Le parentesi potrebbero essere implicite se non le utilizzi per raggruppare le limitazioni in una stringa di filtro. Ad esempio, la seguente 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 interpretato come:

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