L'API Ad Manager fournit des collections de données, le plus souvent dans des méthodes List. Les collections peuvent avoir une taille arbitraire et sont paginées dans les réponses de l'API.
Principes de base
Les messages de requête pour les collections définissent un champ pageSize entier facultatif pour spécifier le nombre maximal de résultats à renvoyer.
Définissez le paramètre pageSize sur un nombre positif inférieur à 1000. Si vous ne définissez aucune valeur ou si vous définissez le paramètre sur zéro, l'API utilise la valeur par défaut 50. Si vous définissez le paramètre sur une valeur négative, l'API renvoie une erreur INVALID_ARGUMENT.
Reportez-vous à la documentation de référence de la ressource, par exemple AdBreaks, pour obtenir une valeur pageSize spécifique à la ressource.
L'API peut renvoyer moins de résultats que le nombre demandé (y compris zéro résultat), même si ce n'est pas la fin de la collection. Utilisez la présence du champ nextPageToken pour déterminer s'il existe d'autres résultats dans la collection.
Les messages de réponse pour les collections définissent un champ de chaîne nextPageToken, qui peut être utilisé pour récupérer la page suivante. Le champ nextPageToken est vide lorsque la fin de la collection est atteinte. C'est le seul moyen de déterminer si vous êtes arrivé à la fin d'une collection.
Les messages de requête pour les collections définissent un champ pageToken de chaîne facultatif pour passer à la page suivante de la collection. Les modifications apportées à pageSize dans une requête pour les pages suivantes sont autorisées. Tous les autres arguments doivent être identiques. Si l'un d'eux est différent, l'API renvoie une erreur INVALID_ARGUMENT.
Exemple
cURL
Demande initiale
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500
{
"adUnits": [ ... ],
"nextPageToken": "eCGwAcs6hUerggzd2DGv"
}
Demande de page suivante
curl https://admanager.googleapis.com/v1/networks/123456/adUnits?pageSize=500&pageToken=eCGwAcs6hUerggzd2DGv
{
"adUnits": [ ... ]
}
Taille totale
Les messages de réponse pour les collections fournissent un entier totalSize qui représente le nombre total d'entités après l'application du filtrage. Ce champ n'est renseigné que lorsqu'il est demandé dans le masque de champ.
GET https://admanager.googleapis.com/v1/networks/123456/adUnits?$fields=adUnits,nextPageToken,totalSize
Classer les résultats
Les messages de requête pour les collections définissent un champ de chaîne orderBy pour spécifier l'ordre de tri.
Les valeurs doivent être une liste de champs séparés par une virgule. Exemple : foo,bar. L'ordre de tri par défaut est croissant. Pour spécifier un ordre décroissant pour un champ, ajoutez un suffixe desc (par exemple, foo desc, bar). Les espaces vides sont ignorés. Les valeurs orderBy foo, bar desc, foo , bar desc et foo,bar desc sont toutes équivalentes. Les sous-champs sont spécifiés avec un caractère ., par exemple foo.bar ou address.street.
Le tri n'est accepté que pour les champs primitifs.
Ignorer les résultats
Les méthodes d'une opération paginée définissent un champ skip entier pour ignorer les résultats. La valeur de saut fait référence au nombre de ressources individuelles à ignorer, et non au nombre de pages.
Exemple :
Une requête sans jeton de page et avec une valeur de saut de 30 renvoie une seule page de résultats à partir du 31e résultat.
Une requête avec un jeton de page correspondant au 51e résultat (car les 50 premiers résultats ont été renvoyés sur la première page) et une valeur de saut de 30 renvoie une seule page de résultats à partir du 81e résultat.
Si une valeur de saut est fournie et que le curseur se déplace au-delà de la fin de la collection de résultats, la réponse est 200 OK avec un ensemble de résultats vide sans nextPageToken.