Si vous disposez d'applications existantes basées sur l'API Google Sheets v3, vous pouvez migrer vers l'API Google Sheets version 4. La version v4 est basée sur JSON, dispose d'une interface plus facile à utiliser et ajoute une quantité importante de fonctionnalités qui ne sont pas possibles dans la version v3.
Cette page fournit 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 en grande partie sur la collection spreadsheets.values, qui fournit des fonctionnalités de lecture et d'écriture directes des cellules. D'autres aspects, tels que l'ajout de feuilles ou la mise à jour des propriétés des feuilles, sont gérés par la collection sheets. 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
Dans la version 3 de l'API, les feuilles d'une feuille de calcul spécifique sont appelées "feuilles de calcul". Cela revient au terme "feuilles de calcul" utilisé par la version 4 de l'API.
Les API vous demandent souvent de spécifier un ID de feuille de calcul correspondant à la feuille de calcul sur laquelle vous travaillez. Ils ont également souvent besoin de l'ID de la feuille manipulée. Ces valeurs apparaissent soit dans l'URL du point de terminaison de l'API, sous forme de 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 à la feuille de calcul et à l'ID de feuille de calcul. Lorsque vous utilisez les méthodes décrites sur cette page, remplacez les identifiants réels à ces emplacements.
L'API v3 attribue également un ID aux lignes récupérées à l'aide de son flux de liste. 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 niveaux d'accès que vous spécifiez dans votre application déterminent les autorisations demandées.
API v3
L'API Sheets v3 fonctionne avec un seul champ d'application d'autorisation:
https://spreadsheets.google.com/feeds
qui est un alias pour
https://www.googleapis.com/auth/spreadsheets
Vous pouvez utiliser l'un ou l'autre format de champ d'application.
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 les champs d'application 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 les champs d'application des feuilles de calcul plutôt que ceux de 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
L'API Sheets v3 exprime la visibilité directement dans ses points de terminaison. Une feuille de calcul public a été publiée sur le Web. L'API peut donc y accéder 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 API Sheets v4, il n'y a pas de déclaration explicite de visibilité. Les appels d'API sont effectués à l'aide des 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 de ces données ou un sous-ensemble fixe défini dans l'API). L'API Sheets v4 n'utilise pas la projection, mais vous permet de mieux contrôler les données renvoyées.
API v3
Seuls deux paramètres de projection sont possibles dans la version 3 de l'API Sheets. La projection full renvoie toutes les informations disponibles, tandis que basic renvoie un sous-ensemble de données plus petit et fixe (pour les feuilles de calcul, les flux de listes et les flux 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 plus petit sous-ensemble de données 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 semblables au paramètre de visibilité basic de l'API Sheets v3.
Les méthodes de la collection de feuille de calcul limitent la quantité de données qu'elles renvoient via l'utilisation 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 des feuilles de calcul. À la place, vous pouvez utiliser la méthode Files.create de l'API Drive. Cela nécessite que l'application déclare 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 nécessite que l'application fournisse le champ d'application https://www.googleapis.com/auth/drive.
Comme alternative équivalente, l'API Sheets v4 fournit une méthode spreadsheets.create, qui permet également d'ajouter des feuilles, de définir les propriétés de la feuille de calcul et de la feuille de calcul, et d'ajouter des plages nommées. Par exemple, ce qui suit 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 par l'utilisateur authentifié. Le point de terminaison du flux de feuilles de calcul est:
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 afin d'utiliser le champ d'application drive.file avec le sélecteur Google pour la sélection des feuilles de calcul.
S'il est nécessaire de répertorier des feuilles de calcul, vous pouvez le répliquer via 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 répertorier toutes les feuilles de calcul d'un utilisateur nécessite un champ d'application limité.
Récupérer les métadonnées d'une feuille
L'API Sheets v3 fournit un flux permettant d'accéder aux métadonnées de feuille contenues dans une feuille de calcul donnée (les données des lignes et des cellules sont accessibles via un flux distinct). Les métadonnées incluent des informations telles que les titres des feuilles et des informations sur la taille.
La méthode spreadsheets.get de l'API Sheets v4 permet d'accéder à ces informations, et bien plus encore.
API v3
Le flux de feuilles de calcul est accessible à partir du point de terminaison de l'API suivant (à l'aide d'un en-tête d'autorisation approprié):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
La structure de la réponse à cette requête est 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 des propriétés de feuille de calcul 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 empêcher l'inclusion des 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 de taille des feuilles 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
},
...
},
...
},
...
],
...
}Insérer une feuille dans une feuille de calcul
Les deux API vous permettent d'ajouter des feuilles à une feuille de calcul existante.
API v3
L'API Sheets v3 permet d'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 effectuant 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 devez pas fournir un titre 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 feuille de calcul
L'API Sheets v3 vous permet de mettre à jour les titres et la taille des feuilles ; l'API Sheets v4 le permet également, mais peut également être utilisée pour mettre à jour d'autres propriétés de feuille de calcul. Notez que la réduction de la taille d'une feuille peut entraîner la suppression sans avertissement préalable des données des cellules recadrées.
API v3
Pour modifier le titre ou la taille d'une feuille de calcul, commencez par récupérer le flux de la feuille de calcul, puis recherchez l'entrée souhaitée dans la feuille de calcul, qui contient une URL edit.
Mettez à jour les métadonnées de la feuille de calcul et envoyez-les dans le 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 lister explicitement ces propriétés (si vous souhaitez mettre à jour toutes les propriétés, utilisez fields:"*" comme raccourci pour toutes les répertorier). Par exemple, le code suivant indique que le titre et les propriétés de taille de la feuille doivent être mis à jour pour la feuille avec 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 la valeur sheetId d'une feuille, utilisez la méthode spreadsheets.get de la feuille de calcul.
Supprimer une feuille
Chacune de ces API peut 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 la feuille de calcul, puis envoyez une requête DELETE sur l'URL edit de l'entrée de 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 l'élément sheetId pour que la feuille soit supprimée. Exemple :
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}
Pour récupérer la propriété sheetId d'une feuille individuelle, utilisez la méthode spreadsheets.get.
Récupérer les données de ligne
Le flux de lignes sous forme de liste est l'une des deux méthodes fournies par l'API Sheets v3 pour accéder aux données contenues dans les cellules d'une feuille de calcul (l'autre étant le flux de cellules). Le flux de lignes est destiné à prendre en charge les opérations courantes sur les feuilles de calcul (lecture ligne par ligne, ajout de lignes, tri), mais repose sur certaines hypothèses qui le rendent inadapté à certaines tâches. Plus précisément, le flux de listes suppose que les lignes vides correspondent à des terminaisons de flux et que des en-têtes obligatoires sont présents dans la première ligne d'une feuille de calcul.
En revanche, l'API Sheets v4 n'utilise pas de méthodes d'accès spécifiques aux lignes. À la place, les données des cellules de 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 de cellules disjoints.
API v3
Pour déterminer l'URL d'un flux basé sur des listes 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 qui vous intéresse.
Pour récupérer un flux basé sur des listes, envoyez une requête GET à l'URL du flux de listes, à 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 de ligne unique:
<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 apparaissent dans l'ordre des lignes. L'API Sheets v3 fournit des paramètres de requête permettant de modifier cet ordre.
Ordre inverse:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Classer selon 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 à l'aide d'une requête structurée (référencée par des 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 "Feuille1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
La structure de la réponse à cette requête est 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 finales 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 n'a pas d'équivalent pour les paramètres de requête d'ordre des lignes fournis par l'API Sheets v3. L'ordre inverse est simple : traitez simplement le tableau values renvoyé dans l'ordre inverse. L'ordre par colonne n'est pas disponible pour les lectures, mais il est possible de trier les données de la feuille (à l'aide d'une requête SortRange) puis de les lire.
Actuellement, l'API Sheets v4 ne dispose pas d'équivalent direct pour les requêtes structurées de l'API Sheets v3. Cependant, 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 des listes 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 feuille de calcul qui vous intéresse.
Pour ajouter une ligne de données, envoyez une requête POST à l'URL du post, à 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 l'API Sheets v4, 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 feuille "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 une mise en forme spécifiques à l'aide des requêtes AppendCells dans une feuille 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 liste afin de localiser l'entrée correspondant à la ligne que vous souhaitez mettre à jour. Mettez à jour le contenu de cette entrée si nécessaire. Assurez-vous que la valeur de l'ID de 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 en tant que corps de 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 l'API Sheets v4, vous pouvez modifier une ligne à l'aide de la notation A1 et envoyer une requête spreadsheets.values.update pour l'écraser. 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 plutôt une plage à plusieurs cellules, les valeurs que vous fournissez doivent être comprises dans cette plage. Dans le cas contraire, l'API renvoie une erreur.
L'exemple de requête et de corps de requête suivants ajoutent 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 à l'aide de la méthode spreadsheet.values.batchUpdate. Elle est plus efficace 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 des cellules et la mise en forme des cellules à l'aide des requêtes UpdateCells ou RepeatCell dans une requête 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, tandis que les lignes inférieures sont déplacées vers le haut.
API v3
Pour supprimer une ligne, commencez par la récupérer dans le 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
Pour 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 ou non mise à jour 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 la version 4 de l'API Sheets 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, ce qui suit supprime la sixième ligne d'une feuille de calcul avec l'ID donné (les index de ligne sont basés sur zéro, avec startIndex inclusive et endIndex exclus):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}
L'sheetId d'une feuille peut être récupérée à 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 un 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éfinies 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 permet de récupérer n'importe quel ensemble de données de cellule d'une feuille (y compris plusieurs plages disjointes). L'API Sheets v3 ne peut renvoyer le contenu des cellules sous forme de valeurs d'entrée (tel qu'il est saisi par un utilisateur sur un clavier) et/ou les sorties de formules (si numériques). L'API Sheets v4 accorde un accès complet 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 dans l'entrée 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 des numéros de ligne et de colonne. Vous pouvez récupérer une seule plage spécifique à l'aide des paramètres de requête max-row, min-row, max-col et min-col. Par exemple, le code suivant récupère toutes les cellules de la colonne 4 (D), à partir de la ligne 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4
L'API Sheets v3 renvoie la valeur inputValue des cellules récupérées, c'est-à-dire la valeur qu'un utilisateur saisirait autrement dans l'interface utilisateur de Google Sheets pour manipuler la cellule. L'élément inputValue peut être une valeur littérale ou une formule. L'API renvoie également parfois un numericValue, par exemple lorsqu'une formule donne un nombre. Par exemple, une réponse peut inclure des entrées de cellule d'une structure 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 qui vous intéressent, respectivement. Par exemple, la requête suivante renvoie les cellules de la colonne D de "Feuille2", à partir de la ligne 2, dans l'ordre de la colonne principale et 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 structure de la réponse à cette demande est semblable à celle-ci:
{
"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, l'API Sheets v4 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 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 souhaité pour la cellule, puis envoyez une requête PUT à l'URL de modification en utilisant 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 l'API Sheets v4, la modification d'une seule cellule peut être effectuée à 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 de Sheets (USER_ENTERED) ou si elles ne sont pas analysées et prises telles quelles (RAW). Par exemple, la cellule D2 est mise à jour 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 émettre dans 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 mentionnées par une requête par lot ne doivent pas nécessairement se trouver dans une plage contingue.
Si une ou plusieurs modifications apportées à des cellules dans le 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'applique aucune d'entre elles 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, avec un corps de requête décrivant les cellules que vous souhaitez mettre à jour et le nouveau contenu des cellules. La structure de la requête POST et du corps de la requête se présente comme suit:
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 la requête de manière unique dans le lot.
Pour les modifications de cellules, le champ batch:operation doit être défini sur update. gs:cell identifie la cellule par ligne et par numéro de colonne, et fournit les nouvelles données à y insérer. id contient l'URL complète de la cellule à mettre à jour.
link doit avoir 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 d'effectuer une modification groupée des valeurs des cellules via la méthode spreadsheets.values.batchUpdate.
Vous pouvez modifier plusieurs cellules en envoyant 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 en tant que coordonnée supérieure gauche. Si vous spécifiez plutôt une plage à plusieurs cellules, les valeurs que vous fournissez doivent correspondre exactement à cette plage. Dans le cas contraire, l'API renvoie une erreur.