Si vous avez des applications existantes basées sur la version 3 de l'API Google Sheets, vous pouvez migrer vers la version 4 de l'API Google Sheets. La version 4 est basée sur le format JSON, dispose d'une interface plus facile à utiliser et ajoute un grand nombre 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, tels que l'ajout de feuilles ou la mise à jour de leurs propriétés, sont gérés par la collection feuilles de calcul. 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 conditions
L'API v3 désigne les feuilles d'une feuille de calcul spécifique par "feuilles de calcul". Ce terme est synonyme de "feuilles" utilisé par l'API v4.
Les API vous demandent souvent de spécifier un ID de feuille de calcul pour 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 aux ID de la feuille de calcul et de la feuille. Lorsque vous utilisez les méthodes décrites sur cette page, remplacez les ID réels à ces emplacements.
L'API v3 attribue également un ID aux lignes récupérées à l'aide de son flux de listes. Il est représenté sur cette page 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 champs d'application 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
Vous pouvez utiliser l'un ou l'autre.
API v4
La version 4 de l'API Sheets utilise un ou plusieurs des 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 portées en lecture seule si votre application n'a pas besoin de modifier les feuilles ou les propriétés de feuilles d'un utilisateur. Utilisez des champs d'application de feuilles 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 version 3 de l'API Sheets exprime la visibilité directement dans ses points de terminaison. Une feuille de calcul public a été "publiée sur le Web" et peut donc être 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'y a pas de déclaration explicite de la 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
L'API Sheets v3 utilise le terme projection pour désigner l'ensemble de données renvoyé par un appel d'API donné, soit l'ensemble complet, soit un sous-ensemble fixe défini dans l'API. La version 4 de l'API Sheets n'utilise pas de projection. Elle vous permet plutôt 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 fixe de données plus petit (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 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 feuille de calcul 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'une feuille de calcul 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 de feuilles de calcul. À la place, 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 la portée 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.
À titre de solution équivalente, l'API Sheets v4 fournit une méthode spreadsheets.create, qui peut également ajouter des feuilles, définir les propriétés de la feuille et de la feuille, et ajouter des plages nommées. Par exemple, l'exemple suivant crée une nouvelle feuille de calcul et lui attribue le nom "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}Lister les feuilles de calcul accessibles à 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 fournit pas cette opération spécifique. Nous vous recommandons de migrer votre application pour qu'elle utilise la portée drive.file en combinaison avec le sélecteur Google pour la sélection de feuilles de calcul.
Lorsque la liste des feuilles de calcul est requise, vous pouvez la répliquer à l'aide de la méthode Files.list de l'API Drive, à l'aide d'une requête mimeType:
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'
L'utilisation de la méthode files.list de l'API Drive pour lister toutes les feuilles de calcul d'un utilisateur nécessite 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 ligne et de cellule sont accessibles via un flux distinct). Les métadonnées incluent des informations telles que les titres des feuilles et les informations sur la taille.
La méthode spreadsheets.get de la version 4 de l'API Sheets permet d'accéder à ces informations et bien plus encore.
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 a une structure semblable à celle-ci, les données de chaque feuille étant 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'acquérir des propriétés de feuille et d'autres métadonnées, bien plus que ce qui est disponible avec la version 3 de l'API Sheets. Si vous ne souhaitez lire que 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 des feuilles et les informations sur la taille se trouvent spécifiquement 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 suivante (authentifiée). 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. Vous ne pouvez pas fournir un titre déjà utilisé pour une feuille existante.
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 fiche
L'API Sheets v3 vous permet de modifier les titres et la taille des feuilles. L'API Sheets v4 vous permet également de le faire, mais elle peut également être utilisée pour modifier d'autres propriétés de feuille. Notez que réduire 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, puis recherchez l'entrée de 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 mettre à jour la taille, le titre et d'autres propriétés de la 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 associée à l'ID donné:
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 l'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'une feuille de calcul donnée.
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 des lignes
Le flux de lignes de liste est l'une des deux méthodes proposées 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 de feuille de calcul courantes (lecture ligne par ligne, ajout de lignes, tri), mais fait 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 fins 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, vous accédez aux données des cellules de la feuille 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 de cellules disjoints.
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 la feuille de calcul et recherchez l'URL du flux de liste dans l'entrée de la 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 à l'aide d'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 listes sont renvoyées dans l'ordre des lignes. La version 3 de l'API Sheets 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:lastname
L'API Sheets v3 permet également de filtrer des lignes spécifiques via une requête structurée (référencée par les en-têtes de colonnes):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175API v4
Avec la version 4 de l'API Sheets, vous pouvez récupérer des lignes par plage à l'aide des méthodes spreadsheets.values.get ou spreadsheets.values.batchGet. Par exemple, la formule suivante renvoie toutes les lignes de "Feuille1":
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 lors de la récupération de lignes, de colonnes ou de feuilles entières.
L'API Sheets v4 ne propose pas d'équivalents pour les paramètres de requête par ordre des lignes fournis par l'API Sheets v3. L'ordre inverse est simple : il suffit de traiter le tableau values renvoyé dans l'ordre inverse. La commande "Trier par colonne" n'est pas prise en charge pour les lectures, mais vous pouvez trier les données de la feuille (à l'aide d'une requête SortRange) et les lire.
La version 4 de l'API Sheets ne dispose actuellement pas d'équivalent direct pour les requêtes structurées de la version 3 de l'API Sheets. 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 la feuille de calcul et recherchez l'URL du post dans l'entrée de la feuille de calcul qui vous intéresse.
Pour ajouter une ligne de données, envoyez une requête POST à l'URL de publication à l'aide d'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 des 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 la dernière table de "Sheet1" 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 un formatage spécifiques à l'aide des requêtes AppendCells dans une spreadsheets.batchUpdate.
Modifier une ligne avec de nouvelles données
Les deux API permettent de mettre à jour les données de ligne avec de nouvelles valeurs.
API v3
Pour modifier une ligne de données, examinez le flux de listes pour trouver l'entrée de la ligne que vous souhaitez mettre à jour. Modifiez le contenu de cette entrée si nécessaire. Assurez-vous que la valeur d'ID de l'entrée que vous utilisez correspond exactement à celle de l'entrée existante.
Une fois l'entrée mise à jour, envoyez une requête PUT avec l'entrée comme corps de la requête à l'URL edit fournie dans cette entrée de ligne, à l'aide d'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 la version 4 de l'API Sheets, vous pouvez modifier une ligne à l'aide de la notation A1 de la ligne que vous souhaitez modifier et en émettant une requête spreadsheets.values.update pour écraser cette ligne. La plage spécifiée ne doit faire référence qu'à la première cellule de la ligne. L'API infère les cellules à mettre à jour en fonction des valeurs fournies avec la requête. Si vous spécifiez plutôt une plage multicellulaire, les valeurs que vous fournissez doivent s'inscrire dans cette plage. Sinon, 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 le formatage des cellules à l'aide des requêtes UpdateCells ou RepeatCell dans une spreadsheets.batchUpdate.
Supprimer une ligne
Les deux API permettent de supprimer des lignes. Une ligne supprimée est supprimé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, récupérez d'abord 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 souhaitez 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 de l'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 mise à jour depuis que vous l'avez récupérée ou non, 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 la 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 également choisir de ne supprimer qu'une partie d'une ligne ou d'une colonne. Par exemple, l'instruction suivante supprime la 6e ligne d'une feuille avec l'ID donné (les indices de ligne sont basés sur zéro, avec startIndex inclusif et endIndex exclusif):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
Vous pouvez récupérer l'sheetId d'une feuille à l'aide de la méthode spreadsheet.get.
Récupérer les données des cellules
La version 3 de l'API Sheets 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 en tant que bloc unique. 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 cellule à partir d'une feuille (y compris plusieurs plages disjointes). La version 3 de l'API Sheets ne peut renvoyer le contenu des cellules qu'en tant que valeurs d'entrée (comme le ferait un utilisateur au clavier) et/ou les sorties de la formule (si elles sont numériques). La version 4 de l'API Sheets accorde un accès complet aux valeurs, aux formules, à la mise en forme, aux liens hypertextes, à la validation des données et à d'autres propriétés.
API v3
Pour déterminer l'URL d'un flux basé sur une cellule pour une feuille de calcul donnée, examinez le flux de la feuille de calcul et recherchez l'URL du flux de cellule dans l'entrée de la feuille de calcul qui vous intéresse.
Pour récupérer un flux basé sur les cellules, envoyez une requête GET à l'URL du flux de cellules à l'aide d'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. Vous pouvez extraire une seule plage spécifique à l'aide des paramètres de requête max-row, min-row, max-col et min-col. Par exemple, la formule 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=4
La version 3 de l'API Sheets renvoie la 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 également un numericValue, par exemple, lorsqu'une formule génère un nombre. Par exemple, une réponse peut inclure des entrées de cellules dont la structure est semblable à celle-ci:
<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 ou les plages d'intérêt, respectivement. Par exemple, la formule 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 souhaitez 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
La version 3 de l'API Sheets vous permet de modifier le contenu d'une cellule 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, recherchez d'abord son entrée 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 que la cellule contienne, 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
Vous pouvez modifier une seule cellule dans la version 4 de l'API Sheets à 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 si elles ne sont pas analysées et prises telles quelles (RAW). Par exemple, le code suivant 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 modifiez plusieurs cellules, utilisez la méthode spreadsheets.values.batchUpdate pour les envoyer dans une seule requête.
Modifier plusieurs cellules via une requête par lot
Les deux API permettent de modifier le contenu de plusieurs cellules à l'aide d'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 des modifications de cellules du lot échouent, l'API Sheets v3 permet aux autres modifications de réussir. Toutefois, l'API Sheets v4 renvoie une erreur si l'une des mises à jour groupées échoue et n'en applique aucune dans ce cas.
API v3
Pour modifier plusieurs cellules, récupérez d'abord 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 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
La version 4 de l'API Sheets permet de modifier les valeurs des cellules par lot à l'aide de la méthode spreadsheets.values.batchUpdate.
Pour modifier plusieurs cellules, envoyez 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 plutôt une plage multicellulaire, les valeurs que vous fournissez doivent correspondre exactement à cette plage. Sinon, l'API renvoie une erreur.