Migrer à partir de l'API Sheets v3

Si vous disposez d'applications existantes basées sur l'API Google Sheets v3, vous pouvez migrer vers l'API Google Sheets v4. La version v4 est basée sur JSON, dispose d'une interface plus facile à utiliser et ajoute de nombreuses fonctionnalités qui ne sont pas possibles dans la version v3.

Cette page fournit un mappage 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 des propriétés des feuilles, 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

Dans la version 3 de l'API, les feuilles d'une feuille de calcul spécifique sont désignées par le terme "feuilles de calcul". Il s'agit d'un synonyme du terme "sheets" utilisé par la version 4 de l'API.

Les API exigent souvent que vous spécifiiez un ID de feuille de calcul de la feuille de calcul avec laquelle vous travaillez. Elles nécessitent aussi souvent l'identifiant de la feuille manipulée. Ces valeurs apparaissent soit dans l'URL du point de terminaison de l'API, 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 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 champs d'application que vous spécifiez dans votre application déterminent les autorisations demandées.

API v3

La version 3 de l'API Sheets 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 portée.

API v4

L'API Sheets v4 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 champs d'application en lecture seule si l'application n'a pas besoin de modifier les feuilles ou les propriétés des feuilles d'un utilisateur. Utilisez les habilitations Sheets plutôt que 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" et peut donc être consultée 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

La version 4 de la nouvelle API Sheets ne fait pas l'objet d'une 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 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 feuilles de calcul, les 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 sous-ensemble plus petit 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 feuille de calcul limitent la quantité de données renvoyées 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 donnée:

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 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 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, et d'ajouter des plages nommées. Par exemple, le code suivant permet de créer une feuille de calcul et de lui donner le nom "NewTitle":

POST https://sheets.googleapis.com/v4/spreadsheets
{
 "properties": {"title": "NewTitle"}
}

Répertorier 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 feuille de calcul est:

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 afin d'utiliser le champ d'application drive.file avec le sélecteur Google pour la sélection de feuilles de calcul.

Dans les cas où il est nécessaire de répertorier les feuilles de calcul, celle-ci peut être répliquée 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 restricted.

Récupérer les métadonnées de la 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 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 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 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 à la suivante, 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 peut être utilisée pour acquérir des propriétés de feuille 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 de feuille et les informations de 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 de nouvelles 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 de nouvelles 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 feuille pour la nouvelle feuille. Toutes les propriétés sont facultatives. Si vous fournissez un titre utilisé pour une feuille existante, vous ne parvenez pas à le faire.

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 mettre à jour les titres et la taille des feuilles, tandis que l'API Sheets v4 le permet également, mais peut également être utilisée pour mettre à jour d'autres propriétés de feuille. Notez que la réduction de la taille d'une feuille peut entraîner la suppression sans avertissement 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 feuilles de calcul, puis recherchez l'entrée 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, exécutez 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 les répertorier toutes). Par exemple, le code suivant indique que le titre et les propriétés de taille de la feuille doivent être mis à jour 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 le sheetId d'une feuille, utilisez la méthode spreadsheets.get de la feuille de calcul.

Supprimer une feuille

Chaque 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 à l'URL edit de l'entrée cible de la feuille de calcul.

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

API v4

Pour supprimer une feuille, exécutez une requête DeleteSheet dans la méthode spreadsheets.batchUpdate. Le corps de la requête POST ne doit contenir que le 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 l'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 fournies par l'API Sheets v3 pour accéder aux données dans les cellules d'une feuille de calcul (l'autre étant le flux de cellules). Il est conçu pour prendre en charge les opérations courantes de feuille de calcul (lecture ligne par ligne, ajout de lignes, tri). Toutefois, il émet certaines hypothèses qui le rendent inadapté à certaines tâches. Plus précisément, le flux de listes suppose que les lignes vides sont des arrêts 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 à la ligne. À la place, 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 des listes pour une feuille de calcul donnée, récupérez le flux de la feuille de calcul et recherchez son URL dans l'entrée 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 (obligatoire) de la feuille. Par exemple, voici une entrée à 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 affichées 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 via 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<175

API v4

Avec l'API Sheets v4, vous pouvez récupérer les lignes 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 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 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. Il n'est pas possible de trier par colonne 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.

L'API Sheets v4 n'a 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 au besoin 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 de l'article dans l'entrée 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 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 la dernière table 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 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 listes afin de localiser l'entrée correspondant à la ligne à 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 en utilisant 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 fait 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 à la place une plage à plusieurs cellules, les valeurs que vous fournissez doivent entrer 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 à l'aide de la méthode spreadsheet.values.batchUpdate. Cette méthode est plus efficace si vous effectuez des mises à jour de plusieurs lignes ou cellules.

En outre, la version 4 de l'API Sheets 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 un élément spreadsheets.batchUpdate.

Supprimer une ligne

Les deux API prennent en charge la suppression de lignes. Une ligne supprimée est retirée de la feuille de calcul, puis les lignes en dessous sont repoussées vers le haut.

API v3

Pour supprimer une ligne, récupérez d'abord la ligne à supprimer 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 l'URL 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 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 même si quelqu'un d'autre l'a mise à jour depuis que vous l'avez récupérée, utilisez l'attribut "If-Match:" : * et n'incluez pas l'ETag. Dans ce cas, il n'est pas nécessaire 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, et 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 associée à l'ID donné (les index de ligne sont basés sur zéro, l'index startIndex étant inclus 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 le sheetId d'une feuille à 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 l'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 dans un seul bloc. Les plages disjointes doivent être extraites 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 à partir d'une feuille (y compris plusieurs plages disjointes). La version 3 de l'API Sheets ne peut renvoyer le contenu des cellules que sous forme de valeurs d'entrée (comme le ferait un utilisateur sur un clavier) et/ou de sorties de formule (si numérique). 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 son URL 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 cellulaire à 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 d'un numéro 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, 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=4

L'API Sheets v3 renvoie la valeur inputValue des cellules récupérées, c'est-à-dire la valeur qu'un utilisateur devrait saisir autrement dans l'interface utilisateur de Google Sheets pour manipuler la cellule. inputValue peut être une valeur littérale ou une formule. L'API renvoie également parfois un numericValue ; par exemple, lorsqu'une formule génère un nombre. Par exemple, une réponse peut inclure des entrées de cellules ayant une structure semblable à la suivante:

<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, respectivement pour la ou les plages d'intérêt. Par exemple, ce qui suit renvoie les cellules de la colonne D de "Sheet2", en commençant par la ligne 2, dans l'ordre principal de la colonne, et en renvoyant les formules telles qu'elles ont été saisies (les cellules vides de 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 requête 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.

L'API Sheets v4, en revanche, 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 correspondante 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 avec l'entrée de cellule mise à jour comme corps de la requête. Par exemple, la cellule D2 (R2C4) suivante est mise à jour 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

La modification d'une seule cellule dans l'API Sheets v4 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 avaient été saisies dans l'interface utilisateur Sheets (USER_ENTERED), ou si elles n'étaient 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 en 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 une requête par lot fait référence ne doivent pas nécessairement se trouver dans une plage contingue.

Si une ou plusieurs modifications de 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, 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, avec un corps de requête décrivant les cellules que vous souhaitez mettre à jour, ainsi que le nouveau contenu de la cellule. La structure de la requête POST et du corps de la requête est 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 au sein du lot. Le champ "batch:operation" doit indiquer "update" pour les modifications de cellules. gs:cell identifie la cellule par ligne et numéro de colonne, et fournit les nouvelles données à insérer à cet endroit. 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 de modifier par lots les valeurs des cellules via la méthode spreadsheets.values.batchUpdate.

Vous pouvez modifier plusieurs cellules en émettant 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 supérieure gauche. Si vous spécifiez une plage à plusieurs cellules, les valeurs que vous fournissez doivent correspondre exactement à cette plage. Sinon, l'API renvoie une erreur.