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 des cellules à l'aide de la méthode spreadsheets.get, mais il est généralement plus facile d'utiliser spreadsheets.values.get ou spreadsheets.values.batchGet.
Ces exemples sont présentés sous la forme de requêtes HTTP afin de ne pas tenir compte du langage. Pour savoir comment implémenter la lecture dans différents langages à l'aide des bibliothèques clientes des API Google, consultez Lire et écrire les valeurs des cellules.
Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez fournir l'ID de feuille de calcul, que vous pouvez trouver à 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. Exemple de plage : Sheet1!A1:D5.
Données source
Pour ces exemples, supposons que la feuille de calcul en cours de lecture contient les données sources suivantes dans sa première feuille ("Sheet1"). Les chaînes de la première ligne sont des étiquettes correspondant aux colonnes individuelles. Pour voir des exemples de lecture à partir d'autres feuilles de votre feuille de calcul, consultez la section Notation A1.
| A | B | C | D | |
| 1 | Article | 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
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 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 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 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 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: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 renvoie dans la réponse, mais utilise des options d'affichage 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 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?
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 renvoie dans la réponse. Le 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 d'un tableau d'objets ValueRange correspondant à chaque plage demandée, répertorié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 de Sheets1!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 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 d'un tableau d'objets ValueRange correspondant à chaque plage demandée, répertorié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": [
[...],
[...]
]
}
]
}