Les feuilles de calcul peuvent comporter plusieurs feuilles, chacune ayant un nombre illimité de lignes ou de colonnes. Une cellule est un emplacement situé à l'intersection d'une ligne et d'une colonne particulières et peut contenir une valeur de données. L'API Google Sheets fournit la ressource spreadsheets.values
pour permettre la lecture et l'écriture des 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, utilisez la méthode spreadsheets.batchUpdate
décrite dans la section 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 à une 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, reportez-vous à la page de présentation des exemples.
Read
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 pour la plage. Si la plage est spécifiée sans l'ID de feuille (A1:B2
), la requête s'exécute 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 du résultat:
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
.
Il n'y a pas de limite explicite à la quantité de données renvoyées. Les erreurs ne renvoient aucune donnée. Les lignes et colonnes finales vides sont omises.
Les méthodes get au singulier 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 à partir 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 interrompues à 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 en tant qu'objet BatchGetValuesResponse
contenant le spreadsheetId
et une liste d'objets ValueRange
.
Écriture
Pour écrire dans une feuille, vous avez besoin de l'ID de la feuille de calcul, de la plage de cellules dans la 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 individuelles, 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 sous forme de 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 les valeurs booléennes ou les 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, "Mar 1 2016" devient une date, et "=1+2" devient une formule. Les formats peuvent également être déduits, de sorte que "100,15 €" devient un nombre avec mise en forme de la 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
.
Par défaut, ROWS
est utilisé. Si COLUMNS
est spécifié, chaque tableau interne est écrit dans une colonne plutôt que 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 interrompues, 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
, et 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
.
Par défaut, ROWS
est utilisé. Si COLUMNS
est spécifié, chaque tableau interne est écrit dans une colonne plutôt que 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. Prenons l'exemple de 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 tableB4:D6
est la dernière.B4
ouC5:D5
, car ils figurent 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 cela se trouve dans la tableA1:C2
.E4
commencera à écrire àE4
, car il ne se trouve dans aucune table. (A4
commencerait é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 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.