Impaginazione

L'API Ad Manager fornisce raccolte di dati, più comunemente in List metodi. Le raccolte possono avere dimensioni arbitrarie e sono suddivise in pagine nelle risposte dell'API.

Nozioni di base

I messaggi di richiesta per le collezioni definiscono un campo intero facoltativo pageSize per specificare il numero massimo di risultati da restituire.

Imposta il parametro pageSize su un numero positivo inferiore a 1000. Se non imposti alcun valore o imposti il parametro su zero, l'API utilizza un valore predefinito di 50. Se imposti il parametro su un valore negativo, l'API restituisce un errore INVALID_ARGUMENT.

Per un valore pageSize specifico della risorsa, consulta la documentazione di riferimento della risorsa, ad esempio AdBreaks.

L'API potrebbe restituire meno risultati rispetto al numero richiesto (inclusi zero risultati), anche se non alla fine della raccolta. Utilizza la presenza del campo nextPageToken per determinare se sono presenti altri risultati nella raccolta.

I messaggi di risposta per le raccolte definiscono un campo di stringa nextPageToken, che può essere utilizzato per recuperare la pagina successiva. Il campo nextPageToken è vuoto quando viene raggiunta la fine della raccolta. Questo è l'unico modo per stabilire se hai raggiunto la fine di una raccolta.

I messaggi di richiesta per le raccolte definiscono un campo stringa facoltativo pageToken per avanzare alla pagina successiva della raccolta. Le modifiche al parametro pageSize in una richiesta per le pagine successive sono consentite. Tutti gli altri argomenti devono essere uguali. Se uno o più argomenti sono diversi, l'API restituisce un errore INVALID_ARGUMENT.

Esempio

cURL

Richiesta iniziale

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500

{
  "adUnits": [ ... ],
  "nextPageToken": "eCGwAcs6hUerggzd2DGv"
}

Richiesta di pagina successiva

curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv

{
  "adUnits": [ ... ]
}

Dimensione totale

I messaggi di risposta per le raccolte forniscono un numero intero totalSize che rappresenta il numero totale di entità dopo l'applicazione del filtro. Questo campo viene compilato solo se richiesto nella maschera di campo.

GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize

Ordina risultati

I messaggi di richiesta per le raccolte definiscono un campo di stringa orderBy per specificare l'ordine di ordinamento.

I valori devono essere un elenco di campi separati da virgole. Ad esempio: foo,bar. L'ordine di ordinamento predefinito è crescente. Per specificare l'ordinamento decrescente per un campo, aggiungere un suffisso desc; ad esempio: foo desc, bar. I caratteri di spazio ridondanti nella sintassi vengono ignorati. I valori orderBy foo, bar desc, foo , bar desc e foo,bar desc sono tutti equivalenti. I sottocampi vengono specificati con un carattere ., ad esempio foo.bar o address.street.

L'ordinamento è supportato solo per i campi primitivi.

Saltare i risultati

I metodi per un'operazione paginata definiscono un campo intero skip per saltare i risultati. Il valore di salto si riferisce al numero di singole risorse da saltare, non al numero di pagine.

Ad esempio:

Una richiesta senza token pagina e con un valore di salto pari a 30 restituisce una singola pagina di risultati a partire dal 31° risultato.

Una richiesta con un token pagina corrispondente al 51° risultato (poiché i primi 50 risultati sono stati restituiti nella prima pagina) e un valore di salto pari a 30 restituisce una singola pagina di risultati a partire dal 81° risultato.

Se viene fornito un valore di salto che fa avanzare il cursore oltre la fine della raccolta dei risultati, la risposta è 200 OK con un insieme di risultati vuoto senza nextPageToken.