Filtra le risposte dell'elenco

La maggior parte dei servizi nell'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 parametro di query filter. Utilizza questo parametro per ottimizzare l'utilizzo dell'API recuperando solo ciò di cui hai bisogno.

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

Struttura dei filtri

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

Il formato delle limitazioni è {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, procedi in uno dei seguenti modi:

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

Racchiudi i valori di limitazione tra virgolette per garantire che la logica venga applicata correttamente.

Codifica URL per le stringhe di filtro se effettui chiamate LIST direttamente senza utilizzare una libreria client.

Per ulteriori dettagli sulla formattazione delle query, consulta Logica tra restrizioni.

Campi filtrabili

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

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

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 risorsa è inferiore o uguale al valore specificato. Spesso utilizzato per il confronto di date o data/ora. Esempio: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	Il valore del campo risorsa è maggiore o uguale al valore specificato. Spesso utilizzato per il confronto di date o data/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, controllerà se il valore specificato è una sottostringa esistente. Se il campo delle risorse è un array, controllerà se l'array contiene il valore specificato. 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, come 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 restrizioni

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

Solitamente puoi combinare più restrizioni con gli operatori logici AND e OR. Ogni metodo LIST specifica gli operatori che supporta. Alcuni metodi supportano solo l'utilizzo di una singola limitazione nel parametro filter.

Quando crei stringhe di filtro con gli operatori logici AND o OR, tieni presente le seguenti restrizioni:

Nota: gli esempi seguenti sono scritti utilizzando le restrizioni relative ai parametri filter del metodo advertisers.lineItems.list.

• AND deve essere utilizzato tra restrizioni o gruppi di restrizioni, che filtrano campi diversi o che 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")
• È necessario utilizzare OR tra singole limitazioni che vengono filtrate 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ù richieste LIST 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")