Lecture de base

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

Ces exemples sont présentés sous la forme de requêtes HTTP et neutres. Pour découvrir comment implémenter la lecture dans différentes langues à l'aide de l'API sur les bibliothèques clientes de l'API, consultez l'article Lire et écrire la cellule valeurs.

Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous indiquerait l'ID de la feuille de calcul, accessible via l'URL de la feuille de calcul. Les plages de lecture sont spécifié au format A1 dans la requête URL. Exemple de plage : Sheet1!A1:D5.

Données source

Pour ces exemples, supposons que la feuille de calcul en cours de lecture dispose de la source suivante dans sa première feuille ("Feuille1"). Les chaînes de la première ligne sont des étiquettes pour les colonnes individuelles. Pour voir des exemples de lecture à partir d'autres feuilles dans votre feuille de calcul, consultez la section Notation A1.

	A	B	C	D
1	Élément	Coût	En stock	Date d'expédition
2	Roue	20,50 $	4	01/03/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

Les éléments suivants : spreadsheets.values.get exemple de code montre comment lire les valeurs de la plage Sheet1!A1:D5 et renvoie dans la réponse. Les lignes et colonnes de fin vides 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 qui décrit les valeurs de la plage. La 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 regroupée par colonne

Les éléments suivants : spreadsheets.values.get exemple de code montre comment lire les valeurs de la plage Sheet1!A1:D3 et renvoie dans la réponse, mais regroupés par colonne. Les lignes et colonnes vides sont 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 qui décrit les valeurs de la plage. La 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

Les éléments suivants : spreadsheets.values.get exemple de code montre comment lire les valeurs de la plage Sheet1!A1:D5 et renvoie dans la réponse, mais il utilise les options d'affichage pour gérer la façon dont ces informations est renvoyé. La Paramètre ValueRenderOption de FORMULA indique que les formules doivent être renvoyées au lieu du la valeur calculée, DateTimeRenderOption du paramètre 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 sont 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 qui décrit les valeurs de la plage. La 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

Les éléments suivants : spreadsheets.values.batchGet exemple de code montre comment lire les valeurs des plages Sheet1!B:B et Sheet1!D:D, et les renvoie dans la réponse. La Paramètre ValueRenderOption de UNFORMATTED_VALUE indique que les valeurs sont calculées, mais pas formatées dans la réponse. Les lignes et colonnes de fin vides 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 feuille de calcul. et un tableau de ValueRange objets correspondant à chaque plage demandée, répertoriés dans l'ordre dans lequel ils ont été demandée. La 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

Les éléments suivants : spreadsheets.values.batchGet exemple de code montre comment lire les valeurs des plages dans Sheets Sheet1!A1:D5, Products!D1:D100 et Sales!E4:F6 et les renvoie dans la réponse. La Paramètre ValueRenderOption de UNFORMATTED_VALUE indique que les valeurs sont calculées, mais pas formatées dans la réponse. Les lignes et colonnes de fin vides 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 feuille de calcul. et un tableau de ValueRange objets correspondant à chaque plage demandée, répertoriés dans l'ordre dans lequel ils ont été demandée. La 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": [
        [...],
        [...]
      ]
    }
  ]
}