Les feuilles de calcul peuvent comporter plusieurs feuilles, chaque feuille comportant un nombre illimité de lignes ou de colonnes. Une cellule est un emplacement à l'intersection d'une ligne et d'une colonne particulière, et peut contenir une valeur de données. L'API Google Sheets fournit la ressource spreadsheets.values
pour permettre la lecture et l'écriture de valeurs.
Cette page décrit les principes de base de l'utilisation de la ressource spreadsheets.values
. Si vous devez insérer des lignes ou mettre à jour la mise en forme et d'autres propriétés d'une feuille, vous devez utiliser la méthode spreadsheets.batchUpdate
décrite dans Mettre à jour des feuilles de calcul.
Méthodes
La ressource spreadsheets.values
fournit les méthodes suivantes pour lire et écrire des valeurs, chacune pour une tâche spécifique:
Accès à la plage | Lecture | Écriture |
---|---|---|
Plage unique | spreadsheets.values.get |
spreadsheets.values.update |
Plusieurs plages | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Ajouts | spreadsheets.values.append |
En général, il est recommandé de combiner plusieurs lectures ou mises à jour avec les méthodes batchGet
et batchUpdate
(respectivement), car cela améliore l'efficacité.
Vous trouverez des exemples de chacune de ces méthodes sur les pages d'exemples Lecture de base et Écriture de base. Pour voir tous les exemples, consultez la page de présentation des exemples.
Lire
Pour lire les valeurs de données d'une feuille, vous avez besoin de l'ID de la feuille de calcul et de la notation A1 de la plage. Si vous spécifiez la plage sans l'ID de feuille (A1:B2
), la requête sera exécutée sur la première feuille de la feuille de calcul. Pour en savoir plus sur les ID de feuille de calcul et la notation A1, consultez la présentation de l'API Google Sheets.
Plusieurs paramètres de requête facultatifs contrôlent le format de la sortie:
Paramètre de format | Valeur par défaut |
---|---|
majorDimension |
ROWS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Notez que vous ne devez utiliser dateTimeRenderOption
que si valueRenderOption
n'est pas FORMATTED_VALUE
.
Aucune limite explicite ne s'applique à la quantité de données renvoyées. Les erreurs ne renvoient aucune donnée. Les lignes et colonnes de fin vides sont omises.
Les méthodes get singulières et par lot sont décrites ci-dessous. Pour obtenir des exemples d'opérations de lecture de base, consultez la section Lecture de base.
Lire une seule plage
Pour lire une seule plage de valeurs d'une feuille de calcul, utilisez une requête spreadsheets.values.get
:
Apps Script ;
Java
JavaScript
Node.js
PHP
Python
Ruby
La réponse à cette requête est renvoyée en tant qu'objet ValueRange
.
Lire plusieurs plages
Pour lire plusieurs plages de valeurs intermittentes à partir d'une feuille de calcul, utilisez une requête spreadsheets.values.batchGet
qui vous permet de spécifier plusieurs plages à récupérer:
Apps Script ;
Java
JavaScript
Node.js
PHP
Python
Ruby
La réponse à cette requête est renvoyée sous la forme d'un objet BatchGetValuesResponse
contenant le spreadsheetId
et une liste d'objets ValueRange
.
Rédiger
Pour écrire dans une feuille, vous avez besoin de l'ID de la feuille de calcul, de la plage de cellules en notation A1 et des données que vous souhaitez écrire dans un objet de corps de requête approprié. Pour en savoir plus sur les ID de feuille de calcul et la notation A1, consultez la présentation de l'API Google Sheets.
Les mises à jour nécessitent un paramètre ValueInputOption
valide.
Pour les mises à jour uniques, il s'agit d'un paramètre de requête obligatoire. Pour les mises à jour groupées, ce paramètre est obligatoire dans le corps de la requête. ValueInputOption
contrôle la manière dont les données d'entrée doivent être interprétées et si les chaînes d'entrée sont analysées ou non, comme décrit dans le tableau suivant:
ValueInputOption |
Description |
---|---|
RAW |
L'entrée n'est pas analysée et est insérée en tant que chaîne. Par exemple, l'entrée "=1+2" place la chaîne dans la cellule, et non la formule "=1+2". (Les valeurs qui ne sont pas des chaînes, telles que des booléens ou des nombres, sont toujours traitées comme RAW .) |
USER_ENTERED |
L'entrée est analysée exactement comme si elle avait été saisie dans l'interface utilisateur de Sheets. Par exemple, "1er mars 2016" devient une date, et "=1+2" devient une formule. Comme il est également possible d'en déduire des formats, "100,15 €" devient un nombre avec une mise en forme de devise. |
Les méthodes de mise à jour unique et par lot sont décrites ci-dessous. Pour obtenir des exemples d'opérations d'écriture de base, consultez la section Écriture de base.
Écrire dans une seule plage
Pour écrire des données dans une seule plage, utilisez une requête spreadsheets.values.update
:
Apps Script ;
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour doit être un objet ValueRange
, bien que le seul champ obligatoire soit values
. Si range
est spécifié, il doit correspondre à la plage de l'URL. Dans ValueRange
, vous pouvez éventuellement spécifier son majorDimension
.
ROWS
est utilisé par défaut. Si COLUMNS
est spécifié, chaque tableau interne est écrit dans une colonne et non dans une ligne.
Lors de la mise à jour, les valeurs sans données sont ignorées. Pour effacer les données, utilisez une chaîne vide ("").
Écrire plusieurs plages
Si vous souhaitez écrire plusieurs plages discontinues, vous pouvez utiliser une requête spreadsheets.values.batchUpdate
:
Apps Script ;
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour par lot doit être un objet BatchUpdateValuesRequest
, qui contient un ValueInputOption
et une liste d'objets ValueRange
(un pour chaque plage écrite). Chaque objet ValueRange
spécifie ses propres range
et majorDimension
, ainsi que ses propres données d'entrée.
Ajouter des valeurs
Pour ajouter des données après une table de données dans une feuille, utilisez une requête spreadsheets.values.append
:
Apps Script ;
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour doit être un objet ValueRange
, bien que le seul champ obligatoire soit values
. Si range
est spécifié, il doit correspondre à la plage de l'URL. Dans ValueRange
, vous pouvez éventuellement spécifier son majorDimension
.
ROWS
est utilisé par défaut. Si COLUMNS
est spécifié, chaque tableau interne est écrit dans une colonne et non dans une ligne.
La plage d'entrée permet de rechercher des données existantes et de trouver une "table" dans cette plage. Les valeurs sont ajoutées à la ligne suivante de la table, en commençant par la première colonne. Par exemple, considérons Sheet1
qui se présente comme suit:
A | B | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
La feuille contient deux tableaux: A1:C2
et B4:D6
. Les valeurs ajoutées commenceront à B7
pour toutes les entrées range
suivantes:
Sheet1
, car il examinera toutes les données de la feuille et déterminera que la table àB4:D6
est la dernière table.B4
ouC5:D5
, car ils se trouvent tous les deux dans la tableB4:D6
.B2:D4
, car la dernière table de la plage est la tableB4:D6
(bien qu'elle contienne également la tableA1:C2
).A3:G10
, car la dernière table de la plage est la tableB4:D6
(bien qu'elle commence avant et se termine après).
Les entrées range
suivantes ne commencent pas à écrire à B7
:
A1
commencera à écrire àA3
, car il se trouve dans la tableA1:C2
.E4
commencera à écrire àE4
, car il ne se trouve dans aucune table. (A4
commencera également à écrire àA4
pour les mêmes raisons.)
Vous pouvez également choisir d'écraser les données existantes après une table ou d'insérer de nouvelles lignes pour les nouvelles données. Par défaut, l'entrée écrase les données situées après la table. Pour écrire les nouvelles données dans de nouvelles lignes, utilisez InsertDataOption
et spécifiez insertDataOption=INSERT_ROWS
.
Pour en savoir plus sur le nombre maximal de cellules et de lignes dans Sheets, consultez Fichiers pouvant être stockés dans Google Drive.