Si vous avez des applications existantes basées sur l'API Google Sheets v3, vous pouvez migrer vers l'API Google Sheets v4. La version 4 est basée sur JSON, dispose d'une interface plus facile à utiliser et ajoute une quantité importante de fonctionnalités qui ne sont pas disponibles dans la version 3.
Cette page établit une correspondance entre les anciennes commandes de l'API Sheets v3 et leurs opérations équivalentes dans l'API Sheets v4. Le mappage se concentre principalement sur la collection spreadsheets.values, qui fournit une fonctionnalité de lecture et d'écriture directe des cellules. D'autres aspects, comme l'ajout de feuilles ou la mise à jour de leurs propriétés, sont gérés par la collection spreadsheets. Notez que les structures JSON de l'API v4 ne sont pas rétrocompatibles avec les structures XML utilisées dans la version 3.
Pour en savoir plus sur les ressources disponibles dans l'API Sheets v4, consultez la documentation de référence de l'API.
Notation et termes
L'API v3 désigne les feuilles d'un tableur spécifique sous le nom de "feuilles de calcul". Ce terme est synonyme de "feuilles" utilisé par l'API v4.
Les API vous demandent souvent de spécifier l'ID de la feuille de calcul avec laquelle vous travaillez. Elles nécessitent également souvent l'ID de la feuille manipulée. Ces valeurs apparaissent soit dans l'URL du point de terminaison de l'API, soit en tant que paramètres de requête, soit dans le corps d'une requête. Sur cette page, les espaces réservés spreadsheetId et sheetId font respectivement référence à l'identifiant de la feuille de calcul et à celui de la feuille. Lorsque vous utilisez les méthodes décrites sur cette page, remplacez les ID réels dans ces emplacements.
L'API v3 attribue également un ID aux lignes récupérées à l'aide de son flux de liste. Sur cette page, cet ID est représenté par l'espace réservé rowId.
Autoriser les requêtes
Lorsque votre application s'exécute, elle demande aux utilisateurs d'accorder certaines autorisations. Les niveaux d'accès que vous spécifiez dans votre application déterminent les autorisations qu'elle demande.
API v3
L'API Sheets v3 fonctionne avec un seul champ d'application d'autorisation :
https://spreadsheets.google.com/feeds
qui est un alias de
https://www.googleapis.com/auth/spreadsheets
Les deux formats de portée peuvent être utilisés.
API v4
L'API Sheets v4 utilise un ou plusieurs des ensembles de champs d'application suivants :
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Utilisez des niveaux d'accès en lecture seule si votre application n'a pas besoin de modifier les feuilles ou les propriétés des feuilles d'un utilisateur. Utilisez des champs d'application de feuille de calcul au lieu de champs d'application Drive si l'application n'a pas besoin d'un accès général à Drive.
Visibilité
Dans les anciennes versions de l'API, le terme visibilité est utilisé pour désigner la disponibilité d'une feuille de calcul donnée.
API v3
La visibilité est directement exprimée dans les points de terminaison de l'API Sheets v3. Une feuille de calcul public a été "publiée sur le Web" et est donc accessible par l'API sans autorisation, tandis qu'une feuille de calcul private nécessite une authentification. La visibilité est spécifiée dans le point de terminaison après l'ID de la feuille de calcul :
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API v4
Dans la nouvelle version 4 de l'API Sheets, il n'existe pas de déclaration explicite de visibilité. Les appels d'API sont effectués à l'aide d'ID de feuille de calcul. Si l'application n'est pas autorisée à accéder à la feuille de calcul spécifiée, une erreur est renvoyée. Sinon, l'appel se poursuit.
Projection
Le terme projection est utilisé par l'API Sheets v3 pour désigner l'ensemble de données renvoyé par un appel d'API donné (l'ensemble complet ou un sous-ensemble fixe défini dans l'API). L'API Sheets v4 n'utilise pas de projection. Elle vous permet de mieux contrôler les données renvoyées.
API v3
Il n'existe que deux paramètres de projection possibles dans l'API Sheets v3. La projection full renvoie toutes les informations disponibles, tandis que basic renvoie un sous-ensemble de données plus petit et fixe (pour les flux de feuilles de calcul, de listes et de cellules).
Comme pour la visibilité, la projection doit être spécifiée dans le point de terminaison de l'API (après le paramètre de visibilité) :
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Le sous-ensemble de données plus petit fourni par la projection basic est utile pour rendre le code plus efficace, mais il ne peut pas être personnalisé.
API v4
Bien que l'API Sheets v4 puisse renvoyer un ensemble de données complet, elle ne définit pas de sous-ensembles fixes analogues au paramètre de visibilité basic de l'API Sheets v3.
Les méthodes de la collection spreadsheet limitent la quantité de données qu'elles renvoient à l'aide d'un paramètre de requête fields.
Par exemple, la requête suivante ne renvoie que les titres de toutes les feuilles d'un tableur spécifique :
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Créer une feuille de calcul
API v3
L'API Sheets v3 ne permet pas de créer des feuilles de calcul. Vous pouvez utiliser la méthode Files.create de l'API Drive pour créer des fichiers de feuilles de calcul. Pour ce faire, l'application doit déclarer le champ d'application https://www.googleapis.com/auth/drive.
API v4
La méthode Files.create de l'API Drive peut également être utilisée avec l'API Sheets v4, mais l'application doit fournir le champ d'application https://www.googleapis.com/auth/drive.
L'API Sheets v4 propose une méthode spreadsheets.create équivalente, qui peut également ajouter des feuilles, définir les propriétés de la feuille de calcul et de la feuille, et ajouter des plages nommées (facultatif). Par exemple, le code suivant crée une feuille de calcul et lui donne le nom "NewTitle" :
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Lister les feuilles de calcul pour l'utilisateur authentifié
API v3
Le flux de l'API Sheets v3 permet à une application de récupérer la liste de toutes les feuilles de calcul accessibles à l'utilisateur authentifié. Le point de terminaison du flux de feuille de calcul est le suivant :
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
L'API Sheets v4 ne propose pas cette opération spécifique. Nous vous recommandons de migrer votre application pour qu'elle utilise le champ d'application drive.file en combinaison avec le sélecteur Google pour la sélection de feuilles de calcul.
Si vous devez lister des feuilles de calcul, vous pouvez le faire à l'aide de la méthode Files.list de l'API Drive, en utilisant une requête mimeType :
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Pour lister toutes les feuilles de calcul d'un utilisateur à l'aide de la méthode files.list de l'API Drive, vous devez utiliser un champ d'application restreint.
Récupérer les métadonnées d'une feuille
La version 3 de l'API Sheets fournit un flux permettant d'accéder aux métadonnées de la feuille contenues dans une feuille de calcul donnée (les données de lignes et de cellules sont accessibles via un flux distinct). Les métadonnées incluent des informations telles que les titres et la taille des feuilles.
La méthode spreadsheets.get de l'API Sheets v4 permet d'accéder à ces informations et à bien d'autres.
API v3
Le flux de feuille de calcul est accessible à partir de ce point de terminaison de l'API (à l'aide d'un en-tête d'autorisation approprié) :
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
La réponse à cette requête présente une structure semblable à celle-ci, avec les données de chaque feuille contenues dans un <entry> distinct :
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
API v4
La méthode spreadsheets.get permet d'obtenir les propriétés des feuilles et d'autres métadonnées, bien plus que ce qui est disponible avec l'API Sheets v3. Si vous souhaitez uniquement lire les propriétés de la feuille, définissez le paramètre de requête includeGridData sur false pour éviter d'inclure les données des cellules de la feuille de calcul :
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
La réponse Spreadsheet contient un tableau d'objets Sheet. Les titres et les informations sur la taille des feuilles se trouvent plus précisément sous l'élément SheetProperties de ces objets. Exemple :
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}Ajouter une feuille à une feuille de calcul
Les deux API vous permettent d'ajouter des feuilles à une feuille de calcul existante.
API v3
L'API Sheets v3 peut ajouter des feuilles de calcul à une feuille de calcul en effectuant la requête POST (authentifiée) suivante. Vous pouvez spécifier la taille de la nouvelle feuille :
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
API v4
Vous pouvez ajouter des feuilles en envoyant une requête AddSheet dans la méthode spreadsheets.batchUpdate. Dans le corps de la requête, vous pouvez spécifier les propriétés de la nouvelle feuille. Toutes les propriétés sont facultatives. Fournir un titre déjà utilisé pour une feuille de calcul existante constitue une erreur.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}Modifier le titre et la taille d'une feuille
L'API Sheets v3 vous permet de modifier le titre et la taille des feuilles de calcul. L'API Sheets v4 vous permet également de le faire, mais vous pouvez aussi l'utiliser pour modifier d'autres propriétés des feuilles de calcul. Notez que la réduction de la taille d'une feuille peut entraîner la suppression des données des cellules recadrées sans avertissement.
API v3
Pour modifier le titre ou la taille d'une feuille de calcul, commencez par récupérer le flux de feuilles de calcul et recherchez l'entrée de la feuille de calcul souhaitée, qui contient une URL edit.
Mettez à jour les métadonnées de la feuille de calcul et envoyez-les en tant que corps d'une requête PUT à l'URL de modification. Exemple :
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
API v4
Pour modifier la taille, le titre et d'autres propriétés d'une feuille, envoyez une requête updateSheetProperties dans la méthode spreadsheets.batchUpdate. Le corps de la requête POST doit contenir les propriétés à modifier, et le paramètre fields doit les lister explicitement (si vous souhaitez mettre à jour toutes les propriétés, utilisez fields:"*" comme raccourci pour les lister toutes). Par exemple, le code suivant spécifie que les propriétés de titre et de taille de la feuille doivent être mises à jour pour la feuille portant l'ID indiqué :
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}Pour récupérer les sheetId d'une feuille, utilisez la méthode spreadsheets.get de la feuille de calcul.
Supprimer une feuille
Les deux API peuvent supprimer des feuilles d'un tableur donné.
API v3
Pour supprimer une feuille de calcul, commencez par récupérer le flux de feuilles de calcul, puis envoyez une requête DELETE sur l'URL edit de l'entrée de la feuille de calcul cible.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API v4
Pour supprimer une feuille, envoyez une requête DeleteSheet dans la méthode spreadsheets.batchUpdate. Le corps de la requête POST ne doit contenir que le sheetId de la feuille à supprimer. Exemple :
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}Pour récupérer le sheetId d'une feuille individuelle, utilisez la méthode spreadsheets.get de la feuille de calcul.
Récupérer les données d'une ligne
Le flux de liste des lignes est l'une des deux méthodes fournies par l'API Sheets v3 pour accéder aux données des cellules d'une feuille de calcul (l'autre étant le flux de cellules). Le flux de lignes est conçu pour prendre en charge les opérations courantes sur les feuilles de calcul (lecture ligne par ligne, ajout de lignes, tri), mais il repose sur certaines hypothèses qui le rendent inadapté à certaines tâches. Plus précisément, le flux de liste suppose que les lignes vides sont des terminaisons de flux et que les en-têtes obligatoires sont présents dans la première ligne d'une feuille.
En revanche, l'API Sheets v4 n'utilise pas de méthodes d'accès spécifiques aux lignes. Au lieu de cela, les données des cellules de la feuille sont accessibles en référençant les plages spécifiques requises à l'aide de la notation A1. Les plages peuvent être des blocs de cellules, des lignes entières, des colonnes entières ou des feuilles entières. L'API peut également accéder à des ensembles disjoints de cellules.
API v3
Pour déterminer l'URL d'un flux basé sur une liste pour une feuille de calcul donnée, récupérez le flux de feuille de calcul et recherchez l'URL du flux de liste dans l'entrée de feuille de calcul qui vous intéresse.
Pour récupérer un flux basé sur une liste, envoyez une requête GET à l'URL du flux de liste, en utilisant un en-tête d'autorisation approprié. Exemple :
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
La réponse à cette requête contient, entre autres, des entrées correspondant à des lignes spécifiques. Les cellules individuelles sont référencées par les noms fournis dans la ligne d'en-tête de la feuille (obligatoire). Par exemple, voici une entrée sur une seule ligne :
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
Par défaut, les lignes renvoyées dans le flux de liste sont renvoyées dans l'ordre des lignes. L'API Sheets v3 fournit des paramètres de requête pour modifier cet ordre.
Ordre inverse :
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Trier par une colonne spécifique :
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameL'API Sheets v3 permet également de filtrer des lignes spécifiques à l'aide d'une requête structurée (référencée par les en-têtes de colonne) :
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
Avec l'API Sheets v4, les lignes peuvent être récupérées par plage à l'aide des méthodes spreadsheets.values.get ou spreadsheets.values.batchGet. Par exemple, la requête suivante renvoie toutes les lignes de "Sheet1" :
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
La réponse à cette requête a une structure semblable à celle-ci :
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}Les cellules vides de fin ne sont pas incluses dans la réponse lorsque vous récupérez des lignes, des colonnes ou des feuilles entières.
L'API Sheets v4 ne propose pas d'équivalents pour les paramètres de requête d'ordre des lignes fournis par l'API Sheets v3. L'ordre inverse est trivial : il suffit de traiter le tableau values renvoyé dans l'ordre inverse. L'ordre par colonne n'est pas compatible avec les lectures, mais il est possible de trier les données dans la feuille (à l'aide d'une requête SortRange), puis de les lire.
L'API Sheets v4 ne dispose actuellement pas d'équivalent direct pour les requêtes structurées de l'API Sheets v3. Toutefois, vous pouvez récupérer les données pertinentes et les trier selon vos besoins dans votre application.
Ajouter une ligne de données
Vous pouvez ajouter une ligne de données à une feuille à l'aide de l'une ou l'autre des API.
API v3
Pour déterminer l'URL d'un flux basé sur une liste pour une feuille de calcul donnée, récupérez le flux de feuille de calcul et recherchez l'URL du post dans l'entrée de feuille de calcul qui vous intéresse.
Pour ajouter une ligne de données, envoyez une requête POST à l'URL du post, en utilisant un en-tête d'autorisation approprié. Exemple :
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Le corps de la requête POST doit contenir une entrée pour les données de ligne à ajouter, avec des cellules individuelles référencées par les en-têtes de colonne :
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Les nouvelles lignes sont ajoutées à la fin de la feuille spécifiée.
API v4
Avec la version 4 de l'API Sheets, vous pouvez ajouter des lignes à l'aide de la méthode spreadsheets.values.append. L'exemple suivant écrit une nouvelle ligne de données sous le dernier tableau de la "Feuille1" d'une feuille de calcul.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}De plus, l'API Sheets v4 vous permet également d'ajouter des cellules avec des propriétés et une mise en forme spécifiques à l'aide des requêtes AppendCells dans spreadsheets.batchUpdate.
Modifier une ligne avec de nouvelles données
Les deux API permettent de mettre à jour les données des lignes avec de nouvelles valeurs.
API v3
Pour modifier une ligne de données, examinez le flux de liste pour trouver l'entrée correspondant à la ligne que vous souhaitez modifier. Modifiez le contenu de cette entrée si nécessaire. Assurez-vous que la valeur de l'ID dans l'entrée que vous utilisez correspond exactement à l'ID de l'entrée existante.
Une fois l'entrée mise à jour, envoyez une requête PUT avec l'entrée comme corps de requête à l'URL edit fournie dans cette entrée de ligne, en utilisant un en-tête d'autorisation approprié. Exemple :
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
API v4
Avec l'API Sheets v4, vous pouvez modifier une ligne à l'aide de la notation A1 de la ligne que vous souhaitez modifier et en envoyant une requête spreadsheets.values.update pour remplacer cette ligne. La plage spécifiée ne doit faire référence qu'à la première cellule de la ligne. L'API déduit les cellules à mettre à jour en fonction des valeurs fournies avec la requête. Si vous spécifiez une plage de cellules multiples, les valeurs que vous fournissez doivent s'adapter à cette plage. Si ce n'est pas le cas, l'API renvoie une erreur.
L'exemple de requête et de corps de requête suivant ajoute des données à la quatrième ligne de "Sheet1" :
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}Vous pouvez également mettre à jour les données de ligne à partir de la méthode spreadsheet.values.batchUpdate. Il est plus efficace d'utiliser cette méthode si vous effectuez plusieurs mises à jour de lignes ou de cellules.
De plus, l'API Sheets v4 vous permet également de modifier les propriétés et la mise en forme des cellules à l'aide des requêtes UpdateCells ou RepeatCell dans spreadsheets.batchUpdate.
Supprimer une ligne
Les deux API permettent de supprimer des lignes. Une ligne supprimée est retirée de la feuille de calcul, et les lignes situées en dessous sont décalées d'une ligne vers le haut.
API v3
Pour supprimer une ligne, commencez par récupérer la ligne à supprimer à partir du flux de liste, puis envoyez une requête DELETE à l'URL edit fournie dans l'entrée de la ligne.
Il s'agit de la même URL que celle utilisée pour mettre à jour la ligne.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Si vous voulez vous assurer de ne pas supprimer une ligne qui a été modifiée par un autre client depuis que vous l'avez récupérée, incluez un en-tête HTTP If-Match contenant la valeur ETag de la ligne d'origine. Vous pouvez déterminer la valeur ETag de la ligne d'origine en examinant l'attribut gd:etag de l'élément d'entrée.
Si vous souhaitez supprimer la ligne, que quelqu'un d'autre l'ait modifiée ou non depuis que vous l'avez récupérée, utilisez If-Match: * et n'incluez pas l'ETag. (Dans ce cas, vous n'avez pas besoin de récupérer la ligne avant de la supprimer.)
API v4
La suppression de lignes avec l'API Sheets v4 est gérée par un appel de méthode spreadsheet.batchUpdate, à l'aide d'une requête DeleteDimension. Cette requête peut également être utilisée pour supprimer des colonnes. Les développeurs peuvent choisir de ne supprimer qu'une partie d'une ligne ou d'une colonne. Par exemple, la commande suivante supprime la sixième ligne d'une feuille avec l'ID donné (les index de ligne sont basés sur zéro, avec startIndex inclus et endIndex exclus) :
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}Le sheetId d'une feuille peut être récupéré à l'aide de la méthode spreadsheet.get.
Récupérer les données d'une cellule
L'API Sheets v3 fournit un flux de cellules pour un accès de base à toutes les données stockées dans une feuille de calcul. Pour l'accès en lecture, le flux de cellules peut fournir l'intégralité du contenu de la feuille ou une plage de cellules de la feuille définie par un ensemble de paramètres de requête, mais uniquement sous la forme d'un seul bloc. Les plages disjointes doivent être récupérées séparément à l'aide de requêtes GET supplémentaires.
L'API Sheets v4 peut récupérer n'importe quel ensemble de données de cellules d'une feuille (y compris plusieurs plages disjointes). L'API Sheets v3 ne peut renvoyer que le contenu des cellules sous forme de valeurs d'entrée (telles qu'elles seraient saisies par un utilisateur au clavier) et/ou les résultats de formules (si elles sont numériques). L'API Sheets v4, quant à elle, permet d'accéder entièrement aux valeurs, aux formules, à la mise en forme, aux liens hypertexte, à la validation des données et à d'autres propriétés.
API v3
Pour déterminer l'URL d'un flux basé sur des cellules pour une feuille de calcul donnée, examinez le flux de la feuille de calcul et recherchez l'URL du flux de cellules dans l'entrée de la feuille de calcul qui vous intéresse.
Pour récupérer un flux basé sur des cellules, envoyez une requête GET à l'URL du flux de cellules, en utilisant un en-tête d'autorisation approprié. Exemple :
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Les cellules sont référencées à l'aide du numéro de ligne et de colonne. Pour récupérer une plage spécifique, vous pouvez utiliser les paramètres de requête max-row, min-row, max-col et min-col. Par exemple, la requête suivante récupère toutes les cellules de la colonne 4 (D), en commençant par la ligne 2 :
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4L'API Sheets v3 renvoie le inputValue des cellules récupérées, c'est-à-dire la valeur qu'un utilisateur saisirait dans l'interface utilisateur de Google Sheets pour manipuler la cellule. inputValue peut être une valeur littérale ou une formule. L'API renvoie parfois un numericValue, par exemple lorsqu'une formule génère un nombre. Par exemple, une réponse peut inclure des entrées de cellule dont la structure est semblable à ce qui suit :
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
API v4
Récupérez les données des cellules en appelant une méthode spreadsheets.values.get ou spreadsheets.values.batchGet pour la plage ou les plages qui vous intéressent, respectivement. Par exemple, la requête suivante renvoie les cellules de la colonne D de "Feuille2", en commençant par la ligne 2, dans l'ordre des colonnes et en renvoyant les formules telles qu'elles ont été saisies (les cellules vides à la fin sont omises) :
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
La réponse à cette requête est semblable à la structure suivante :
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}Il est plus efficace d'utiliser spreadsheet.values.batchGet si vous avez l'intention de récupérer plusieurs plages de données de cellules. Si vous souhaitez accéder aux propriétés des cellules, telles que la mise en forme, la méthode spreadsheet.get est requise.
Modifier une cellule
L'API Sheets v3 vous permet de modifier le contenu des cellules en envoyant une commande PUT au flux de cellules avec l'entrée de cellule modifiée comme corps de la requête.
En revanche, la version 4 de l'API Sheets fournit les méthodes spreadsheets.values.update et spreadsheets.values.batchUpdate pour modifier le contenu des cellules.
API v3
Pour modifier le contenu d'une seule cellule, commencez par trouver l'entrée de la cellule dans le flux de cellules.
L'entrée contient une URL de modification. Mettez à jour l'entrée pour refléter le contenu que vous souhaitez voir dans la cellule, puis envoyez une requête PUT à l'URL de modification avec l'entrée de cellule mise à jour comme corps de la requête. Par exemple, la commande suivante met à jour la cellule D2 (R2C4) pour qu'elle contienne une formule SUM :
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
API v4
Dans la version 4 de l'API Sheets, vous pouvez modifier une seule cellule à l'aide de la méthode spreadsheets.values.update. Cette méthode nécessite un paramètre de requête ValueInputOption, qui spécifie si les données d'entrée sont traitées comme si elles étaient saisies dans l'interface utilisateur Sheets (USER_ENTERED) ou laissées non analysées et prises telles quelles (RAW). Par exemple, la requête suivante met à jour la cellule D2 avec une formule :
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}Si vous apportez plusieurs modifications à des cellules, utilisez la méthode spreadsheets.values.batchUpdate pour les émettre en une seule requête.
Modifier plusieurs cellules à l'aide d'une requête par lot
Les deux API permettent de modifier le contenu de plusieurs cellules avec une seule requête (par lot). Les cellules auxquelles fait référence une requête par lot ne doivent pas nécessairement se trouver dans une plage contiguë.
Si une ou plusieurs modifications de cellules du lot échouent, l'API Sheets v3 permet aux autres de réussir. Toutefois, l'API Sheets v4 renvoie une erreur si l'une des mises à jour par lot échoue et n'en applique aucune dans ce cas.
API v3
Pour modifier plusieurs cellules, commencez par récupérer un flux de cellules pour la feuille de calcul. L'entrée contient une URL de lot. Envoyez une requête POST à cette URL, ainsi qu'un corps de requête décrivant les cellules que vous souhaitez mettre à jour et le nouveau contenu des cellules. La requête POST et son corps ont une structure semblable à celle-ci :
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
Le champ batch:id doit identifier de manière unique la requête dans le lot.
Le champ batch:operation doit être update pour les modifications de cellules. gs:cell identifie la cellule par son numéro de ligne et de colonne, et fournit les nouvelles données à insérer. id contient l'URL complète de la cellule à modifier.
link doit comporter un attribut href contenant le chemin d'accès complet à l'ID de la cellule. Tous ces champs sont obligatoires pour chaque entrée.
API v4
L'API Sheets v4 permet de modifier les valeurs des cellules par lots à l'aide de la méthode spreadsheets.values.batchUpdate.
Pour modifier plusieurs cellules, vous pouvez envoyer une requête POST avec les modifications de données spécifiées dans le corps de la requête. Exemple :
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}Si vous avez spécifié une seule cellule comme plage, toutes les valeurs fournies sont écrites dans la feuille en commençant par cette cellule comme coordonnée en haut à gauche. Si vous spécifiez une plage de cellules multiples, les valeurs que vous fournissez doivent correspondre exactement à cette plage. Dans le cas contraire, l'API renvoie une erreur.