Requêtes par lot

Ce document explique comment traiter les appels d'API par lot pour réduire le nombre les connexions que votre client doit établir. Le traitement par lot peut améliorer en réduisant les allers-retours sur le réseau et en augmentant le débit.

Présentation

Chaque connexion établie par votre client entraîne une certaine quantité de frais généraux. L'API Google Docs prend en charge les requêtes par lot pour permettre à votre client de placer des objets de requête, chacun spécifiant un seul type de requête à exécuter, en une seule requête par lot. Une requête par lot peut améliorer les performances combiner plusieurs sous-requêtes en un seul appel au serveur, récupérer une seule réponse.

Nous encourageons les utilisateurs à toujours regrouper leurs requêtes par lot. Voici quelques exemples 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 d'objets.
  • Vous devez supprimer de nombreux objets.

Limites, autorisation et considérations relatives aux dépendances

Voici une liste d'autres éléments à prendre en compte lors 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 requête par lot. Les dernières sous-requêtes peuvent dépendre des mesures prises sous-requêtes antérieures. Par exemple, dans la même requête par lot, les utilisateurs peuvent insérer du texte dans un document existant et 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 du lot sont appliquées de manière atomique. Autrement dit, si une requête n'est pas valide, la mise à jour complète échoue et aucune des sont appliquées.

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

Avec cette approche, vous pouvez créer un document Google complet à l'aide d'une seule requête de mise à jour par lot d'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é obligatoire: requests. Les requêtes sont créées 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 d'une requête par lot est semblable au format de le format de la requête. La réponse du serveur contient une réponse complète .

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 demandes ne comportent pas et que la réponse à cet index de tableau est vide.

Exemple

L'exemple de code suivant illustre l'utilisation du traitement par lot avec l'API Docs.

Requête

Cet exemple de requête par lot montre comment:

  • Insérer "Hello World" au début d'un document, avec l'icône index location sur 1, à l'aide de la InsertTextRequest

  • Mettre à jour le mot "Hello" à l'aide du UpdateTextStyleRequest Les éléments startIndex et endIndex définissent le range du texte mis en forme dans le segment.

  • Avec textStyle, définissez le style de police en gras et la couleur sur bleu pour le mot "Hello".

  • Utiliser WriteControl , vous pouvez contrôler l'exécution des requêtes d'écriture. Pour plus d'informations, consultez la section Établir une cohérence d'état avec WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "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"
  }
}

Remplacer TAB_ID et REQUIRED_REVISION_ID par l'ID d'onglet et l'ID de révision du document, la requête d'écriture s'applique.

Réponse

Cet exemple de réponse par lot affiche des informations sur la façon dont chaque sous-requête dans la requête par lot a été appliquée. Ni la InsertTextRequest ou UpdateTextStyleRequest contiennent une réponse. Les valeurs d'index du tableau [0] et [1] sont donc composées d'accolades vides. La requête par lot affiche l'objet WriteControl, qui montre comment les requêtes ont été exécutées.

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