L'une des approches spécifiques au traitement par lot, le point de terminaison mondial pour les requêtes HTTP par lot (www.googleapis.com/batch), a été arrêté le 12 août 2020, comme annoncé sur le blog Google Developers. Les autres approches du traitement par lot fonctionnent toujours, comme indiqué sur le reste de cette page. Si votre code utilise le point de terminaison mondial pour les requêtes HTTP par lot, consultez l'article de blog pour obtenir des instructions sur la transition vers d'autres approches, telles que les points de terminaison pour les requêtes HTTP par lot spécifiques à l'API (www.googleapis.com/batch/API/VERSION).
Ce document explique comment autoriser les appels d'API par lot pour réduire le nombre de connexions HTTP que votre client doit effectuer.
Ce document concerne spécifiquement l'envoi d'une requête par lot en envoyant une requête HTTP. Si vous utilisez plutôt une bibliothèque cliente Google pour effectuer une requête par lot, consultez la documentation sur la bibliothèque cliente.
Présentation
Chaque connexion HTTP effectuée par votre client entraîne certains coûts. L'API Google Ad Experience Report accepte les requêtes par lot, ce qui permet à votre client d'intégrer plusieurs appels d'API dans une seule requête HTTP.
Voici quelques exemples de situations dans lesquelles l'utilisation de requêtes par lot peut s'avérer utile :
- Vous commencez tout juste à utiliser l'API et avez beaucoup de données à importer.
- Un utilisateur a modifié des données lorsque votre application était hors connexion (déconnectée d'Internet). Celle-ci doit donc envoyer un certain nombre d'opérations de mise à jour et de suppression pour synchroniser ses données locales avec le serveur.
Dans chaque cas, au lieu d'envoyer chaque appel séparément, vous pouvez les regrouper en une seule requête HTTP. Toutes les requêtes internes doivent être dirigées vers la même API Google.
Vous êtes limité à 1 000 appels par requête. Si vous devez effectuer plus d'appels que celui-ci, utilisez plusieurs requêtes par lot.
Remarque: Le système de requêtes par lot de l'API Google Ad Experience Report utilise la même syntaxe que le système de traitement par lot OData, mais la sémantique diffère.
Informations sur les lots
Une requête par lot est constituée de plusieurs appels d'API combinés en une seule requête HTTP, qui peut être envoyée au chemin batchPath spécifié dans le document de découverte des API. Le chemin par défaut est /batch/api_name/api_version. Cette section décrit la syntaxe des requêtes par lot plus en détail. Vous en trouverez un exemple plus bas.
Remarque: Un ensemble de requêtes n regroupées est comptabilisé dans votre limite d'utilisation comme n requêtes, et non comme une seule requête. La requête par lot est décomposée en un ensemble de requêtes avant son traitement.
Format d'une requête par lot
Une requête par lot est une requête HTTP standard unique qui comprend plusieurs appels d'API Google Ad Experience Report et utilise le type de contenu multipart/mixed. Chacune des parties de cette requête HTTP principale contient une requête HTTP imbriquée.
Chaque partie commence par son en-tête HTTP Content-Type: application/http, mais peut également comporter un en-tête Content-ID facultatif. Les en-têtes des différentes parties ne servent toutefois qu'à signaler le début des parties et sont séparés de la requête imbriquée. Une fois que le serveur a décomposé la requête par lot en requêtes distinctes, les en-têtes de parties sont ignorés.
Le corps de chaque partie est lui-même composé d'une requête HTTP complète dotée de son propre verbe, de son URL, de ses en-têtes et de son corps. Comme les requêtes par lot n'acceptent pas les URL complètes, la requête HTTP ne doit contenir que le chemin de l'URL.
Les en-têtes HTTP des requêtes par lot externes s'appliquent à toutes les requêtes au sein du lot, à l'exception des en-têtes Content- tels que Content-Type. Si vous spécifiez un en-tête HTTP spécifique à la fois dans la requête externe et dans un appel individuel, la valeur de l'en-tête de l'appel individuel remplace alors celle de la requête par lot externe. Les en-têtes d'un appel individuel ne s'appliquent qu'à cet appel.
Par exemple, si vous fournissez un en-tête "Authorization" à un appel spécifique, l'en-tête ne s'applique qu'à cet appel. Mais si vous fournissez un en-tête "Authorization" à la requête externe, il s'applique à tous les appels individuels, sauf s'ils le remplacent par leurs propres en-têtes "Authorization".
Lorsque le serveur reçoit la requête par lot, il applique les paramètres de requête et les en-têtes (selon le cas) de la requête externe à chaque partie, puis traite ces parties comme s'il s'agissait de requêtes HTTP distinctes.
Réponse à une requête par lot
La réponse du serveur est une réponse HTTP standard unique avec un type de contenu multipart/mixed. Chaque partie constitue la réponse à l'une des requêtes de la requête par lot et apparaît dans le même ordre que celles-ci.
À l'instar des parties de la requête, les parties de la réponse contiennent chacune une réponse HTTP complète, qui comprend un code d'état, des en-têtes et un corps. Elles sont aussi précédées d'un en-tête Content-Type signalant le début de la partie.
Si une partie donnée de la requête possède un en-tête Content-ID, la partie correspondante de la réponse dispose alors du même en-tête Content-ID, avec une valeur initiale précédée de la chaîne response-, comme le montre l'exemple suivant.
Remarque : Le serveur peut effectuer vos appels dans n'importe quel ordre. Ne vous attendez pas à ce qu'ils soient exécutés selon l'ordre dans lequel vous les avez spécifiés. Si vous souhaitez que deux appels se produisent dans un ordre donné, évitez de les envoyer dans la même requête. Vous devez plutôt envoyer le premier appel seul, attendre la réponse, puis envoyer le second.
Exemple
L'exemple suivant illustre l'utilisation du traitement par lot avec l'API Google Ad Experience Report.
Exemple de requête par lot
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
Exemple de réponse par lot
Il s'agit de la réponse à l'exemple de requête abordé dans la section précédente.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--