Requêtes par lot

Ce document explique comment autoriser les appels d'API par lot pour réduire le nombre de connexions que votre client doit effectuer. La mise en lot peut améliorer l'efficacité d'une application en diminuant les allers-retours réseau et en augmentant le débit.

Présentation

Chaque connexion effectuée par votre client entraîne certains coûts. L'API Google Slides accepte les requêtes par lot, ce qui permet à votre client de placer plusieurs objets de requête, chacun spécifiant un seul type de requête à effectuer, dans une seule requête par lot. Une requête par lot peut améliorer les performances en combinant plusieurs sous-requêtes en un seul appel au serveur, ce qui permet de récupérer une seule réponse.

Nous encourageons les utilisateurs à regrouper plusieurs requêtes par lot. Voici quelques exemples de situations dans lesquelles vous pouvez utiliser le traitement par lot :

  • Vous commencez tout juste à utiliser l'API et avez beaucoup de données à importer.
  • Vous devez mettre à jour les métadonnées ou les propriétés, telles que la mise en forme, de plusieurs objets.
  • Vous devez supprimer de nombreux objets.

Limites, autorisation et dépendances

Voici une liste d'autres éléments à prendre en compte lorsque vous utilisez la mise à jour par lot :

  • Chaque requête par lot, y compris toutes les sous-requêtes, est comptabilisée comme une requête API dans votre limite d'utilisation.
  • Une requête par lot est authentifiée une seule fois. Cette authentification unique s'applique à tous les objets de mise à jour par lot de la requête.
  • Le serveur traite les sous-requêtes dans l'ordre dans lequel elles apparaissent dans la requête par lot. Les sous-requêtes ultérieures peuvent dépendre des actions effectuées lors des sous-requêtes précédentes. Par exemple, dans la même requête par lot, les utilisateurs peuvent insérer du texte dans un document existant, puis le mettre en forme.

Informations sur les lots

Une requête par lot se compose d'un appel de méthode batchUpdate avec plusieurs sous-requêtes permettant, par exemple, d'ajouter une présentation, puis de la mettre en forme.

Chaque demande est validée avant d'être appliquée. Toutes les sous-requêtes de la mise à jour par lot sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, l'ensemble de la mise à jour échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée.

Certaines requêtes fournissent des réponses contenant des informations sur les requêtes appliquées. Par exemple, toutes les requêtes de mise à jour par lot pour ajouter des objets renvoient des réponses. Vous pouvez ainsi accéder aux métadonnées de l'objet nouvellement ajouté, telles que l'ID ou le titre.

Cette approche vous permet de créer un document Google entier à l'aide d'une seule requête de mise à jour par lot de l'API, avec plusieurs sous-requêtes.

Format d'une requête par lot

Une requête est une requête JSON unique contenant plusieurs sous-requêtes imbriquées avec une propriété requise : requests. Les requêtes sont construites dans un tableau de requêtes individuelles. Chaque requête utilise JSON pour représenter l'objet de requête et contenir ses propriétés.

Format d'une réponse par lot

Le format de la réponse à une requête par lot est semblable à celui de la requête. La réponse du serveur contient une réponse complète de l'objet de réponse unique.

La propriété de l'objet JSON principal est nommée replies. Les réponses sont renvoyées dans un tableau, chaque réponse à l'une des requêtes occupant le même ordre d'index que la requête correspondante. Certaines requêtes n'ont pas de réponse, et la réponse à cet index de tableau est vide.

Exemple

L'exemple de code suivant montre comment utiliser le traitement par lot avec l'API Slides.

Requête

Cet exemple de requête par lot montre comment :

{    "requests":[       {          "createSlide":{             "insertionIndex":1,             "objectId":"newSlide"          }       },       {          "createShape":{             "elementProperties":{                "pageObjectId":"newSlide",                "size":{                   "height":{                      "magnitude":50,                      "unit":"PT"                   },                   "width":{                      "magnitude":200,                      "unit":"PT"                   }                }             },             "shapeType":"TEXT_BOX",             "objectId":"newTextBox"          }       },       {          "insertText":{             "objectId":"newTextBox",             "text":"Hello World"          }       }    ] }

Réponse

Cet exemple de réponse par lot affiche des informations sur la façon dont chaque sous-requête de la requête par lot a été appliquée. Notez que la méthode InsertTextRequest ne contient pas de réponse. La valeur d'index du tableau à l'emplacement [2] se compose donc d'accolades vides. La requête par lot affiche la propriété WriteControl, qui indique comment les requêtes d'écriture ont été exécutées.

{    "requiredRevisionId": ID    "presentationId": "",    "replies":[       {          "createSlide":{             "objectId":"newSlide"          }       },       {          "createShape":{             "objectId":"newTextBox"          }       },       {                 }    ],    "writeControl":{       "requiredRevisionId": REVISION_ID    } }