Les feuilles de calcul peuvent comporter plusieurs feuilles, chaque feuille ayant un nombre illimité de lignes
ou colonnes. Une cellule est un emplacement au niveau
d'une ligne et d'une colonne particulière, et peut contenir une valeur de données. La
L'API Google Sheets fournit
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
, vous devez utiliser la fonction
spreadsheets.batchUpdate
décrite dans l'article Mettre à jour des feuilles de calcul.
Méthodes
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
batchGet
et batchUpdate
(respectivement), car cela améliore
l'efficacité.
Vous trouverez des exemples de chacune de ces méthodes sur la page Basic lecture et Basic de rédaction des exemples de pages. Pour voir tous les exemples, reportez-vous à 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 du paramètre A1
pour la plage. Spécifier la plage sans l'ID de la feuille (A1:B2
)
signifie que la requête s'exécute sur la première feuille de la feuille de calcul. Pour plus
plus d'informations sur les ID de feuille de calcul et la notation A1, consultez la page API Google Sheets
Présentation.
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 les opérations de lecture, consultez la section Lecture de base.
Lire une seule plage
Pour lire une seule plage de valeurs d'une feuille de calcul, utilisez un
spreadsheets.values.get
requête:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
La réponse à cette requête est renvoyée sous forme de
ValueRange
.
Lire plusieurs plages
Pour lire des plages de valeurs multiples et discontinues à partir d'une feuille de calcul, utilisez un
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 forme de
BatchGetValuesResponse
contenant le spreadsheetId
et une liste
ValueRange
d'objets.
Écriture
Pour écrire dans une feuille, vous avez besoin de l'ID de la feuille de calcul, de la plage de cellules dans A1 et les données que vous souhaitez écrire dans un corps de requête approprié . Pour plus d'informations sur les ID des feuilles de calcul et la notation A1, voir Présentation de l'API Google Sheets
Pour les mises à jour, vous devez indiquer
Paramètre ValueInputOption
.
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. Commandes ValueInputOption
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
pas, 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, et non la formule : "=1+2" dans la cellule. (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. Il est également possible de déduire des formats : "100, 15 €" devient un nombre avec une mise en forme monétaire. |
Les méthodes de mise à jour unique et par lot sont décrites ci-dessous. Pour obtenir des exemples les opérations d'écriture, consultez la section Écriture de base.
Écrire dans une seule plage
Pour écrire des données dans une seule plage, utilisez un
spreadsheets.values.update
requête:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour doit être un
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 chaîne ("").
Écrire plusieurs plages
Si vous souhaitez écrire plusieurs plages discontinues, vous pouvez utiliser une méthode
spreadsheets.values.batchUpdate
requête:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour par lot doit être un
BatchUpdateValuesRequest
qui contient un ValueInputOption
et une liste
ValueRange
(un pour chaque plage écrite). Chaque objet ValueRange
spécifie sa propre
range
, majorDimension
et données d'entrée.
Ajouter des valeurs
Pour ajouter des données après un tableau de données dans une feuille, utilisez un
spreadsheets.values.append
requête:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Le corps de la requête de mise à jour doit être un
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 un "tableau" dans un rayon de
de cette plage. Les valeurs sont ajoutées à la ligne suivante du tableau, en commençant par
première colonne du tableau. 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
commencer à B7
pour toutes les entrées range
suivantes:
Sheet1
, car il examinera toutes les données de la feuille et déterminera que celle qui se trouve àB4:D6
est la dernière.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
(même s'il 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 de remplacer les données existantes après une
table ou insérer de nouvelles lignes pour les nouvelles données. Par défaut, l'entrée écrase les données
après le tableau. Pour écrire les nouvelles données dans de nouvelles lignes, utilisez la méthode
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