Lecture de base

L'API Google Sheets vous permet de lire les valeurs 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 méthode spreadsheets.get, mais spreadsheets.values.get ou spreadsheets.values.batchGet sont généralement plus faciles à utiliser.

Ces exemples sont présentés sous la forme de requêtes HTTP pour être neutres en termes de langue. Pour savoir comment implémenter des lectures dans différentes langues à l'aide des bibliothèques clientes des API Google, consultez Lire et écrire des valeurs de cellules.

Dans ces exemples, le code de substitution SPREADSHEET_ID indique l'emplacement 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, la plage Feuille1!A1:D5.

Données source

Pour ces exemples, supposons que la feuille de calcul lue comporte 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 calcul, consultez Notation A1.

	A	B	C	D
1	Élément	Coût	Stocké	Date d'expédition
2	Roue	20,50 $	4	1/3/2016
3	Porte	15 $	2	15/03/2016
4	Moteur	100 $	1	20/03/2016
5	Totaux	135,5 $	7	20/03/2016

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 la requête est indiqué 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 à la fin sont omises.

Le protocole de la requête est indiqué 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 façon 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 à la fin sont omises.

Le protocole de la requête est indiqué 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, et 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 la requête est indiqué 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'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 "Sheet1!A1:D5", "Products!D1:D100" et "Sales!E4:F6" dans les feuilles de calcul, et 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 la requête est indiqué 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'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": [
        [...],
        [...]
      ]
    }
  ]
}