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 lots peut améliorer l'efficacité d'une application en réduisant les aller-retours réseau et en augmentant le débit.
Présentation
Chaque connexion établie par votre client entraîne une certaine surcharge. L'API Google Sheets accepte les requêtes par lot pour permettre à 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 dans un seul appel au serveur, et en récupérant une seule réponse.
Nous encourageons les utilisateurs à regrouper leurs 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 des métadonnées ou des propriétés, telles que la mise en forme, sur plusieurs objets.
- Vous devez supprimer de nombreux objets.
Limites, autorisation et considérations concernant les dépendances
Voici d'autres éléments à prendre en compte lors de 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 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, par exemple pour ajouter et mettre en forme une feuille de calcul.
Chaque requête 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 afin que vous puissiez accéder aux métadonnées de l'objet nouvellement ajouté, comme l'ID ou le 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 le format JSON pour représenter l'objet de requête et en contenir les propriétés.
Format d'une réponse par lot
Le format de la réponse d'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 indice de tableau est vide.
Exemple
L'exemple suivant montre comment utiliser les requêtes par lot avec l'API Sheets.
Requête
Cet exemple de requête par lot montre comment:
- Ajoutez une feuille à une feuille de calcul existante, avec un
sheetIdde 12345, à l'aide deAddSheetRequest. - Ajoutez des données à la nouvelle feuille, en commençant par la cellule A1, à l'aide de
UpdateCellsRequest. - Ajoutez une vue
namedRangeou une vue filtrée à la nouvelle feuille.
En ajoutant l'ID de la feuille dans la requête, les utilisateurs peuvent l'utiliser pour d'autres sous-requêtes dans le même appel d'API. Cela améliore les performances en évitant un cycle d'écriture-lecture-écriture.
Pour obtenir la liste des types de requêtes de mise à jour par lot, regroupés en différentes catégories, consultez le tableau sous Opérations de mise à jour par lot.
{
"requests":[
{
"addSheet":{
"properties":{
"sheetId":123456
}
}
},
{
"updateCells":{
"start":{
"sheetId":123456
},
"rows":[
{
"values":[
{
"userEnteredValue":{
"stringValue":"hello"
}
}
]
},
{
"values":[
{
"userEnteredValue":{
"stringValue":"world"
}
}
]
}
],
"fields":"userEnteredValue"
}
},
{
"addNamedRange":{
"namedRange":{
"name":"newRange",
"range":{
"sheetId":123456,
"endRowIndex":2
}
}
}
}
]
}
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 UpdateCellsRequest ne contient pas de réponse. Par conséquent, la valeur d'index du tableau à [1] se compose de crochets ouvrants et fermants vides.
"replies":[
{
"addSheet":{
"properties":{
"sheetId":123456,
"title":"Sheet3",
"index":2,
"sheetType":"GRID",
"gridProperties":{
"rowCount":1000,
"columnCount":26
}
}
}
},
{
},
{
"addNamedRange":{
"namedRange":{
"namedRangeId":"2104325079",
"name":"newRange",
"range":{
"sheetId":123456,
"startRowIndex":0,
"endRowIndex":2,
"startColumnIndex":0,
"endColumnIndex":26
}
}
}
}
]