Lecture de base

L'API Google Sheets vous permet de lire les valeurs de cellules, de plages, d'ensembles de plages et de 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 méthode spreadsheets.get, mais généralement, spreadsheets.values.get ou spreadsheets.values.batchGet est plus simple.

Ces exemples sont présentés sous la forme de requêtes HTTP pour être neutres en termes de langue. 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 cellule.

Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez indiquer l'identifiant 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, Feuille1!A1:D5.

Données source

Pour ces exemples, supposons que la feuille de calcul lue contient les données sources 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 affiché ici.

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

La réponse se compose d'un objet ValueRange qui décrit les valeurs de la plage. Le champ majorDimension 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 groupé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 affiché ici.

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

La réponse se compose d'un objet ValueRange qui décrit les valeurs de la plage. Le champ majorDimension 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 manière dont ces informations sont renvoyées. Le paramètre ValueRenderOption de FORMULA indique que les formules doivent être renvoyées au lieu de la valeur calculée, et le paramètre DateTimeRenderOption 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 affiché 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 objet ValueRange qui décrit les valeurs de la plage. Le champ majorDimension 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, puis les renvoyer dans la réponse. Le paramètre ValueRenderOption 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 affiché 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 consiste en un objet avec l'ID de la feuille de calcul et un tableau d'objets ValueRange correspondant à chaque plage demandée, listés dans l'ordre dans lequel ils ont été demandés. Le champ majorDimension 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, puis les renvoyer dans la réponse. Le paramètre ValueRenderOption 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 affiché 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 consiste en un objet avec l'ID de la feuille de calcul et un tableau d'objets ValueRange correspondant à chaque plage demandée, listés dans l'ordre dans lequel ils ont été demandés. Le champ majorDimension 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": [
        [...],
        [...]
      ]
    }
  ]
}