Requêtes par lot

Ce document explique comment regrouper les appels d'API pour réduire le nombre de connexions que votre client doit établir. Cette opération 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 une certaine surcharge. L'API Google Docs accepte les requêtes par lot pour permettre à votre client de placer plusieurs objets de requête, chacun spécifiant un type de requête à exécuter, 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, récupérant ainsi une seule réponse.

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

  • Vous venez de commencer à utiliser l'API et vous 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, sur plusieurs objets.
  • Vous devez supprimer de nombreux objets.

Limites, autorisations et dépendances

Voici une liste d'autres éléments à prendre en compte lors de l'utilisation de la mise à jour groupée:

  • 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. Ces sous-requêtes peuvent dépendre des actions entreprises 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 lui appliquer un style.

Informations sur les lots

Une requête par lot consiste en un appel de méthode batchUpdate avec plusieurs sous-requêtes pour, par exemple, ajouter, puis mettre en forme un document.

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, la mise à jour entière échoue et aucune des modifications (potentiellement dépendantes) n'est appliquée.

Certaines requêtes fournissent des réponses sur les requêtes appliquées. Par exemple, toutes les requêtes de mise à jour par lot visant à ajouter des objets renvoient des réponses afin que vous puissiez 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 complet à l'aide d'une requête API de mise à jour groupée 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é obligatoire: requests. Les requêtes sont construites dans un tableau de requêtes individuelles. Chaque requête utilise JSON pour représenter l'objet de la requête et contenir ses propriétés.

Format d'une réponse par lot

Le format de réponse à une requête par lot est semblable au format de 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 Docs.

Requête

Cet exemple de requête par lot montre comment:

  • Insérez le texte "Hello World" au début d'un document existant, avec un index location de 1, à l'aide de InsertTextRequest.

  • Modifiez le mot "Hello" à l'aide de UpdateTextStyleRequest. startIndex et endIndex définissent l'élément range du texte mis en forme dans le segment.

  • À l'aide de textStyle, définissez le style de police sur gras et la couleur sur bleu pour uniquement le mot "Hello".

  • Le champ WriteControl vous permet de contrôler la manière dont les requêtes d'écriture sont exécutées. Pour en savoir plus, consultez la section Établir la cohérence de l'état avec WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Remplacez REQUIRED_REVISION_ID par l'ID de révision du document auquel la requête d'écriture est appliquée.

Réponse

Cet exemple de réponse par lot affiche des informations sur la manière dont chaque sous-requête au sein de la requête par lot a été appliquée. Ni InsertTextRequest, ni UpdateTextStyleRequest ne contiennent de réponse. Par conséquent, les valeurs d'index du tableau en [0] et [1] sont des accolades vides. La requête par lot affiche l'objet WriteControl, qui indique comment les requêtes ont été exécutées.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}