Migrer à partir de l'API Sheets v3

Si vous disposez d'applications basées sur l'API Google Sheets v3, vous pouvez migrer vers API Google Sheets version 4. La version 4 est basée sur JSON et offre une interface et ajoute une quantité importante de fonctionnalités qu'il est impossible dans la version 3.

Cette page fournit une correspondance entre les anciennes commandes de l'API Sheets v3 et leurs des opérations équivalentes dans la version 4 de l'API Sheets. La cartographie se concentre en grande partie sur spreadsheets.values , qui fournit une fonctionnalité directe de lecture et d'écriture 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 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". L'équivalent du terme "feuilles de calcul" utilisés par l'API v4.

Les API vous demandent souvent de spécifier un ID de feuille de calcul. de la feuille de calcul sur laquelle vous travaillez. De plus, ils ont souvent besoin de l'identifiant feuille en cours de manipulation. Ces valeurs apparaissent soit dans le cadre du point de terminaison de l'API, URL, en tant que paramètres de requête ou dans le corps d'une requête. Sur cette page, espaces réservés spreadsheetId et sheetId se référer respectivement à la feuille de calcul et à l’ID 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 list feed; 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 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 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 habilitations en lecture seule si votre application n'a pas besoin d'apporter de modifications les feuilles ou les propriétés de la feuille d'un utilisateur. Utilisez des champs d'application de feuilles de calcul plutôt que 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 la disponibilité d'une feuille de calcul donnée.

API v3

L'API Sheets v3 exprime la visibilité directement dans ses points de terminaison. public La feuille de calcul a été "Publiée sur le Web". Il est donc possible d'y accéder API sans autorisation, alors qu'une feuille de calcul private nécessite l'authentification unique. La visibilité est spécifiée dans le point de terminaison après la 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 ne comporte pas autorisation d'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ée par un appel d'API donné (soit l'intégralité de l'appel, soit un sous-ensemble fixe) définies dans l'API. L'API Sheets v4 n'utilise pas la projection. Il s'agit plutôt vous permet de mieux contrôler les données qui sont renvoyées.

API v3

Seuls deux paramètres de projection sont possibles dans la version 3 de l'API Sheets. full projection renvoie toutes les informations disponibles, tandis que basic renvoie une sous-ensemble de données fixe et plus petit (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 intéressant 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 valeurs fixes semblables au paramètre de visibilité basic de l'API Sheets v3. Méthodes de la feuille de calcul la collecte de données limitent la quantité de données qu'ils renvoient grâce à l'utilisation 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

La version 3 de l'API Sheets ne permet pas de créer des feuilles de calcul. la méthode Files.create de l'API Drive peut être utilisée pour créer des feuilles de calcul. Pour ce faire, pour déclarer le champ d'application https://www.googleapis.com/auth/drive.

API v4

La méthode Files.create de l'API Drive permet peut également être utilisé avec l'API Sheets v4. Toutefois, l'application doit fournir le champ d'application https://www.googleapis.com/auth/drive.

Comme alternative, l'API Sheets v4 fournit une spreadsheets.create , qui permet également d'ajouter des feuilles, de définir la feuille de calcul et la feuille des propriétés et ajouter des plages nommées. Par exemple, la requête suivante crée 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 une liste de tous les feuilles de calcul accessibles par l'utilisateur authentifié. Flux de feuilles de calcul point de terminaison:

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 migrer votre application pour qu'elle utilise le champ d'application drive.file avec Outil de sélection Google pour la sélection d'une feuille de calcul.

S'il est nécessaire de lister les feuilles de calcul, il est possible de les dupliquer via la méthode Files.list de l'API Drive, en utilisant une requête mimeType:

GET https://www.googleapis.com/drive/v3/files
             ?q=mimeType='application/vnd.google-apps.spreadsheet'

Répertorier toutes les feuilles de calcul d'un utilisateur à l'aide de la méthode files.list de l'API Drive nécessite un champ d'application restreint.

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 des feuilles 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 comprennent des informations telles que les titres des feuilles et les informations de taille.

L'API Sheets v4 spreadsheets.get 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 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 : 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 peut être utilisée pour acquérir des propriétés de feuille et d'autres métadonnées. que celle disponible avec l'API Sheets v3. Si vous n'utilisez si vous voulez lire les propriétés de la feuille, définissez la 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

Spreadsheet La réponse contient un tableau de Sheet Objets ; les titres des feuilles et les informations sur la taille se trouvent spécifiquement dans les 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 de nouvelles feuilles de calcul à une feuille de calcul en faisant la requête POST suivante (authentifiée). Vous pouvez spécifier la taille 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 créant une AddSheet requête dans spreadsheets.batchUpdate . Dans le corps de la requête, vous pouvez spécifier les propriétés de la feuille la nouvelle feuille ; toutes les propriétés sont facultatives. Vous ne devez pas fournir une qui est 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 de calcul. API Sheets v4 permet aussi d'effectuer cette opération, mais il peut aussi être utilisé pour mettre à jour d'autres propriétés de la feuille. Notez que la réduction de la taille d'une feuille peut entraîner l'affichage des données dans les cellules recadrées supprimées sans avertissement préalable.

API v3

Pour modifier le titre ou la taille d'une feuille de calcul, commencez par récupérer les flux de feuille de calcul et rechercher l'entrée souhaitée dans la feuille de calcul, qui contient une URL edit. Mettre à jour les métadonnées de la feuille de calcul et les envoyer 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, créez une updateSheetProperties dans le champ spreadsheets.batchUpdate . Le corps de la requête POST doit contenir les propriétés à modifié, et que 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 lister). Pour Dans l'exemple suivant, le titre et la taille de la feuille doivent être mises à 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 les sheetId d'une feuille, utilisez la feuille de calcul spreadsheets.get.

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 les flux de feuille de calcul, puis envoyez une requête DELETE sur 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, créez un DeleteSheet dans le champ spreadsheets.batchUpdate . Le corps de la requête POST ne doit contenir que l'élément sheetId pour le paramètre 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 Feuille de calcul spreadsheets.get .

Récupérer les données de ligne

Le flux de lignes de liste est l'une des deux méthodes fournies par la version 3 de l'API Sheets pour accéder aux données contenues dans les cellules d'une feuille de calcul (l'autre étant le flux de cellules) ; La Le flux de lignes est conçu pour prendre en charge les opérations courantes sur les feuilles de calcul (lecture ligne par ligne, l'ajout de lignes ou le tri), mais fait certaines hypothèses qui la rendent inadaptée pour certaines tâches. Plus précisément, le flux de liste part du principe que les lignes vides sont et que des en-têtes obligatoires sont présents dans la première ligne feuille.

En revanche, la version 4 de l'API Sheets n'utilise pas de méthodes d'accès spécifique à la ligne. Les données des cellules de la feuille sont accessibles en référençant plages obligatoires au format A1. La 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 feuille de calcul et Recherchez l'URL du flux de liste dans l'entrée qui vous intéresse dans la feuille de calcul.

Pour récupérer un flux basé sur une liste, envoyez une requête GET à l'URL du flux sous forme 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 indiqués dans la ligne d'en-tête (obligatoire) de la feuille. Par exemple, ici est 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 structure (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, les lignes peuvent être récupérées par plage à l'aide des spreadsheets.values.get ou spreadsheets.values.batchGet méthodes. 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 l'intégralité des lignes, des colonnes ou des feuilles.

La version 4 de l'API Sheets ne propose pas d'équivalent pour la requête d'ordre des lignes fournis par l'API Sheets v3. L'ordre inverse est simple ; simplement traiter le tableau values renvoyé dans l'ordre inverse. La valeur Trier par colonne n'est pas pris en charge en lecture, mais il est possible de trier les données de la feuille (à l'aide de une SortRange) puis la 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 les besoins dans votre application.

Ajouter une ligne de données

Vous pouvez ajouter une ligne de données à une feuille à l'aide de l'une ou l'autre des API.

API v3

Pour déterminer l'URL d'un flux basé sur une liste pour une feuille de calcul donnée, récupérez le flux de feuille de calcul et recherchez l'URL du post dans l'entrée qui vous intéresse dans la feuille de calcul.

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 des spreadsheets.values.append . L'exemple suivant écrit une nouvelle ligne de données en dessous de la dernière tableau dans "Feuille1" d'une feuille de calcul. 

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

De plus, l'API Sheets v4 vous permet également d'ajouter des cellules avec des et la mise en forme à l'aide des 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 localiser l'entrée correspondant à la ligne que vous souhaitez mettre à jour. Mettez à jour le contenu de cette entrée selon les besoins. Assurez-vous que la valeur de l'ID dans l'entrée que vous utilisez correspond à l'identifiant de l'entrée existante.

Une fois l'entrée mise à jour, envoyez une requête PUT avec l'entrée en tant que à 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 des La notation A1 de la ligne à modifier modifier et émettre un 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 déduit les cellules à mettre à jour en fonction fournies avec la requête. Si vous spécifiez à la place une plage à plusieurs cellules, vous devez indiquer des valeurs comprises dans cette plage. Si ce n'est pas le cas, l'API renvoie .

Dans l'exemple suivant, la requête et le corps de la requête ajoutent des données à la section quatrième ligne de « Feuille1 » :

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 spreadsheet.values.batchUpdate . il est plus efficace d'utiliser cette méthode si vous effectuez plusieurs de lignes ou de cellules.

De plus, l'API Sheets v4 vous permet également de modifier les propriétés des cellules et formatage des cellules à l'aide du UpdateCells ou RepeatCell dans une spreadsheets.batchUpdate.

Supprimer une ligne

Les deux API permettent de supprimer des lignes. Une ligne supprimée est retirée de la feuille de calcul et les lignes inférieures sont déplacées vers le haut.

API v3

Pour supprimer une ligne, commencez par la récupérer à partir de la list feed, Envoyez ensuite 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é, ajoutez 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 en examinant l'attribut gd:etag de l'élément d'entrée.

Si vous souhaitez supprimer la ligne, que quelqu'un d'autre ait mis à jour ou non depuis que vous l'avez récupérée, utilisez If-Match: * et n'incluez pas l'ETag. Dans ce cas, vous n'avez pas besoin de récupérer la ligne avant de la supprimer.

API v4

La suppression de lignes avec la version 4 de l'API Sheets est gérée par une méthode spreadsheet.batchUpdate. , à l'aide d'un élément DeleteDimension requête. Cette demande peut aussi servir à supprimer des colonnes. et choisir de ne supprimer qu'une partie d'une ligne ou d'une colonne. Par exemple, Ce qui suit supprime la 6e ligne d'une feuille avec l'ID donné (les index de ligne sont basées sur zéro, avec la propriété startIndex inclusive et endIndex exclusive):

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 un feuille de calcul. Pour un accès en lecture, le flux de cellules peut fournir l'intégralité de la feuille contenu 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 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 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 qu'en tant que des valeurs d'entrée (telles qu'un utilisateur peut les saisir sur un clavier) et/ou les sorties de la formule (si numérique) ; l'API Sheets v4 accorde un accès complet aux valeurs, formules, la mise en forme, les hyperliens, 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, consultez le flux de feuilles de calcul puis recherchez l'URL du flux de cellules dans l'entrée qui vous intéresse dans la feuille de calcul.

Pour récupérer un flux basé sur des 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. L'extraction d'une seule valeur la plage d'adresses IP en utilisant max-row, min-row, max-col et min-col paramètres de requête. Par exemple, la requête suivante 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 : qu'un utilisateur saisirait normalement dans l'utilisateur Google Sheets pour manipuler la cellule. inputValue peut être une valeur littérale ou une formule. Parfois, l'API renvoie également un numericValue. Exemple : lorsqu'une formule génère un nombre. Par exemple, une réponse peut inclure des valeurs d'entrées similaires à la structure 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 d'une cellule en appelant une spreadsheets.values.get ou spreadsheets.values.batchGet pour la ou les plages d'intérêt, respectivement. Par exemple, Le code suivant renvoie les cellules de la colonne D de "Sheet2", à partir de la ligne 2, dans l'ordre de priorité de la colonne et renvoyant les formules telles qu'elles ont été saisies (à 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 spreadsheet.get est requise.

Modifier une cellule

L'API Sheets v3 vous permet de modifier le contenu des cellules en envoyant une commande PUT pour le flux de cellules avec l'entrée de cellule modifiée comme corps de la requête.

L'API Sheets v4, quant à elle, offre 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 la flux cellulaire. L'entrée contient une URL de modification. Mettre à jour l'entrée pour refléter le contenu que vous souhaitez ajouter à 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

Dans la version 4 de l'API Sheets, vous pouvez modifier une seule cellule à l'aide de la commande 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 le UI de Sheets (USER_ENTERED), ou laissée non analysée et prise en l'état (RAW) Pour 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 spreadsheets.values.batchUpdate pour les émettre en une seule requête.

Modifier plusieurs cellules à l'aide d'une requête par lot

Les deux API permettent de modifier le contenu de plusieurs cellules avec une seule requête (par lot). Les cellules désignées par une requête par lot sont doit 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. Cependant, 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. Envoyer un POST à cette URL, ainsi qu'un corps de requête décrivant les cellules que vous que vous souhaitez mettre à jour et le nouveau contenu de la cellule. Requête POST et corps de la requête présentent 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 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 pour l'insérer. id contient l'URL complète de la cellule à mettre à jour. link doit comporter un attribut href contenant le chemin d'accès complet à l'identifiant de la cellule. Tous ces champs sont obligatoires pour chaque entrée.

API v4

L'API Sheets v4 permet d'éditer en série les valeurs des cellules via les spreadsheets.values.batchUpdate .

Vous pouvez modifier plusieurs cellules en envoyant une requête POST avec la 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 écrite sur la feuille en commençant par cette cellule comme coordonnée en haut à gauche. Si vous spécifiez une plage à plusieurs cellules, les valeurs fournies doivent correspondre cette plage exactement ; Si ce n'est pas le cas, l'API renvoie une erreur.