L'API Google Sheets vous permet de lire des valeurs à partir 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 de cellule à l'aide de la méthode spreadsheets.get, mais il est généralement plus simple d'utiliser spreadsheets.values.get ou spreadsheets.values.batchGet.
Ces exemples sont présentés sous la forme de requêtes HTTP pour être neutres en ce qui concerne le 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 feuille de calcul, qui peut être trouvé à partir de l'URL de la feuille de calcul. Les plages de lecture sont spécifiées au format A1 dans l'URL de la requête. Un exemple de plage est Feuille1!A1:D5.
Données source
Pour ces exemples, supposons que la feuille de calcul en cours de lecture contienne les données sources suivantes dans sa première feuille ("Feuille 1"). 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 de votre feuille de calcul, consultez Notation A1.
| A | B | C | D | |
| 1 | Article | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 01/03/2016 |
| 3 | Porte | $15 | 2 | 15/03/2016 |
| 4 | Engine | 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 renvoie dans la réponse. Les lignes et colonnes finales vides 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 consiste en 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 plage unique 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 renvoie dans la réponse, mais regroupées par colonne. Les lignes et colonnes finales vides 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 consiste en 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 renvoie 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 à la place 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 finales vides 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 consiste en 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 renvoie 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 finales vides 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 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 des feuilles Sheet1!A1:D5, Products!D1:D100 et Sales!E4:F6 et les renvoie 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 finales vides 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 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": [
[...],
[...]
]
}
]
}