Lecture de base

L'API Google Sheets vous permet de lire des valeurs dans des cellules, des plages, des ensembles de plages et des feuilles entières. Les exemples de cette page illustrent certaines opérations de lecture courantes avec la ressource.spreadsheets.values Vous pouvez également lire les valeurs des cellules à l'aide de la spreadsheets.get méthode, mais il est généralement spreadsheets.values.get ou spreadsheets.values.batchGet plus facile.

Ces exemples sont présentés sous forme de requêtes HTTP pour être indépendants du langage. Pour découvrir comment implémenter des lectures dans différents langages à l'aide des bibliothèques clientes de l'API Google, consultez Lire et écrire des valeurs de cellules.

Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez fournir l'ID de la feuille de calcul, que vous pouvez trouver dans l'URL de la feuille de calcul. Les plages à lire sont spécifiées à l'aide de la notation A1 dans l'URL de la requête. Par exemple, Sheet1!A1:D5.

Données source

Pour ces exemples, supposons que la feuille de calcul lue contient les données source suivantes dans sa première feuille ("Sheet1"). Les chaînes de la première ligne sont des libellés pour les colonnes individuelles. Pour voir des exemples de lecture à partir d'autres feuilles de votre feuille de calcul, consultez la section Notation A1.

Lire une seule plage

L'exemple de code spreadsheets.values.get suivant montre comment lire les valeurs de la plage Sheet1!A1:D5 et les renvoyer dans la réponse. Les lignes et colonnes vides de fin sont omises.

Le protocole de requête est présenté ici.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

La réponse se compose d'un ValueRange objet qui décrit les valeurs de la plage. Le majorDimension champ indique que les tableaux sont des listes de valeurs organisées par lignes.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

Lire une seule plage regroupée par colonne

L'exemple de code spreadsheets.values.get suivant montre comment lire les valeurs de la plage Sheet1!A1:D3 et les renvoyer dans la réponse, mais regroupées par colonne. Les lignes et colonnes vides de fin sont omises.

Le protocole de requête est présenté ici.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

La réponse se compose d'un ValueRange objet qui décrit les valeurs de la plage. Le majorDimension champ indique que les tableaux sont des listes de valeurs organisées par colonnes.

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

Lire une seule plage avec des options de rendu

L'exemple de code spreadsheets.values.get suivant montre comment lire les valeurs de la plage Sheet1!A1:D5 et les renvoyer dans la réponse, mais utilise des options de rendu pour gérer la façon dont ces informations sont renvoyées. Le ValueRenderOption paramètre de FORMULA indique que les formules doivent être renvoyées à la place de la valeur calculée, et le DateTimeRenderOption paramètre de SERIAL_NUMBER indique que les dates doivent être renvoyées sous forme de nombres. D'autres paramètres sont également possibles. Les lignes et colonnes vides de fin sont omises.

Le protocole de requête est présenté ici.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

La réponse se compose d'un ValueRange objet qui décrit les valeurs de la plage. Le majorDimension champ indique que les tableaux sont des listes de valeurs organisées par lignes.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "42430"],
    ["Door", "$15", "2", "42444"],
    ["Engine", "$100", "1", "42449"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Lire plusieurs plages

L'exemple de code spreadsheets.values.batchGet suivant montre comment lire les valeurs des plages Sheet1!B:B et Sheet1!D:D et les renvoyer dans la réponse. Le ValueRenderOption paramètre de UNFORMATTED_VALUE indique que les valeurs sont calculées, mais pas mises en forme dans la réponse. Les lignes et colonnes vides de fin sont omises.

Le protocole de requête est présenté ici.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

La réponse à cet appel de méthode se compose d'un objet avec l'ID de la feuille de calcul et d'un tableau d' ValueRange objets correspondant à chaque plage demandée, répertoriés dans l'ordre dans lequel ils ont été demandés. Le majorDimension champ indique que les tableaux sont des listes de valeurs organisées par colonnes. Exemple :

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

Lire plusieurs plages sur plusieurs feuilles

L'exemple de code spreadsheets.values.batchGet suivant montre comment lire les valeurs des plages des feuilles Sheet1!A1:D5, Products!D1:D100 et Sales!E4:F6 et les renvoyer dans la réponse. Le ValueRenderOption paramètre de UNFORMATTED_VALUE indique que les valeurs sont calculées, mais pas mises en forme dans la réponse. Les lignes et colonnes vides de fin sont omises.

Le protocole de requête est présenté ici.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

La réponse à cet appel de méthode se compose d'un objet avec l'ID de la feuille de calcul et d'un tableau d' ValueRange objets correspondant à chaque plage demandée, répertoriés dans l'ordre dans lequel ils ont été demandés. Le majorDimension champ indique que les tableaux sont des listes de valeurs organisées par colonnes. Exemple :

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}