L'API Google Sheets vous permet d'écrire des valeurs et des formules dans des cellules, des plages, des ensembles de plages et des feuilles entières. Les exemples de cette page montrent comment réaliser certaines opérations d'écriture courantes avec la ressource spreadsheets.values de l'API Sheets.
Notez qu'il est également possible d'écrire des valeurs de cellule à l'aide de la méthode spreadsheet.batchUpdate, ce qui peut être utile si vous souhaitez mettre à jour simultanément la mise en forme des cellules ou d'autres propriétés que la ressource spreadsheets.values n'affecte pas. Par exemple, si vous souhaitez copier une plage de cellules d'une feuille à une autre tout en écrasant la formule et la mise en forme de la cellule, vous pouvez utiliser la méthode UpdateCellsRequest avec un spreadsheet.batchUpdate.
Toutefois, pour les écritures de valeurs simples, il est plus facile d'utiliser la méthode spreadsheets.values.update ou spreadsheets.values.batchUpdate.
Ces exemples sont présentés sous la forme de requêtes HTTP afin de ne pas tenir compte du langage. Pour découvrir comment implémenter des écritures 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 l'emplacement où vous devez fournir l'ID de la feuille de calcul, que vous pouvez trouver à partir de l'URL de la feuille de calcul. Les plages dans lesquelles écrire des données sont spécifiées à l'aide de la notation A1. Exemple de plage : Sheet1!A1:D5.
Écrire une seule plage
À partir d'une nouvelle feuille de calcul vide, l'exemple de code spreadsheets.values.update suivant montre comment écrire les valeurs dans une plage. Le paramètre de requête ValueInputOption est obligatoire et détermine si les valeurs écrites sont analysées (par exemple, si une chaîne est convertie en date).
Le corps de la requête est un objet ValueRange qui décrit les valeurs de plage à écrire. Le champ majorDimension indique que les tableaux sont des listes de valeurs organisées par lignes. Les valeurs existantes dans la plage cible sont écrasées.
Le protocole de requête est présenté ci-dessous.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION
{
"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", "3/20/2016"],
["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
],
}
La réponse se compose d'un objet UpdateValuesResponse, comme celui-ci:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}
La feuille obtenue se présente comme suit:
| 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 |
Écrire de manière sélective dans une plage
Lorsque vous écrivez des valeurs dans une plage, il est possible d'éviter de modifier certaines cellules existantes en définissant les éléments de tableau correspondants sur null. Il est également possible d'effacer une cellule en y écrivant une chaîne vide ("").
En commençant par une feuille contenant les mêmes données produites par l'exemple ci-dessus, l'exemple de code spreadsheets.values.update suivant montre comment écrire les valeurs dans la plage B1:D4, en laissant certaines cellules inchangées et en en effaçant d'autres. Le paramètre de requête ValueInputOption est obligatoire et détermine si les valeurs écrites sont analysées (par exemple, si une chaîne est convertie en date).
Le corps de la requête est un objet ValueRange qui décrit les valeurs de plage à écrire. Le champ majorDimension indique que les tableaux sont des listes de valeurs organisées par colonne.
Le protocole de requête est présenté ci-dessous.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION
{
"range": "Sheet1!B1",
"majorDimension": "COLUMNS",
"values": [
[null,"$1","$2", ""],
[],
[null,"4/1/2016", "4/15/2016", ""]
]
}
Le champ values ici répertorie les modifications apportées à chaque colonne de la plage. Le premier tableau indique que B1 doit rester inchangé (en raison de l'élément de tableau null), tandis que B4 doit être effacé (chaîne vide). Les valeurs de B2 et B3
sont mises à jour. Le troisième tableau effectue les mêmes opérations sur la colonne D, tandis que le deuxième tableau vide indique que la colonne C doit rester inchangée.
La réponse se compose d'un objet UpdateValuesResponse tel que celui-ci:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}
La feuille obtenue se présente comme suit:
| A | B | C | D | |
| 1 | Article | Coût | En stock | Date d'expédition |
| 2 | Roue | 1,00 $ | 4 | 01/04/2016 |
| 3 | Porte | 2 € | 2 | 15/04/2016 |
| 4 | Moteur | 1 | ||
| 5 | Totaux | 3 $ | 7 | 15/04/2016 |
Notez que, même si la ligne "Totaux" n'est pas directement modifiée par cette requête, elle est modifiée, car ses cellules contiennent des formules qui dépendent des cellules modifiées.
Écrire dans plusieurs plages
À partir d'une feuille vierge, l'exemple de code spreadsheets.values.batchUpdate suivant montre comment écrire les valeurs dans les plages Sheet1!A1:A4 et Sheet1!B1:D2. Les valeurs existantes de la plage cible sont remplacées. Le corps de la requête se compose d'un objet ValueInputOption qui indique comment interpréter les données d'entrée et d'un tableau d'objets ValueRange correspondant à chaque plage écrite. Le champ majorDimension détermine si les tableaux inclus sont interprétés comme des tableaux de colonnes ou de lignes.
Le protocole de requête est présenté ci-dessous.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate
{
"valueInputOption": "VALUE_INPUT_OPTION",
"data": [
{
"range": "Sheet1!A1:A4",
"majorDimension": "COLUMNS",
"values": [
["Item", "Wheel", "Door", "Engine"]
]
},
{
"range": "Sheet1!B1:D2",
"majorDimension": "ROWS",
"values": [
["Cost", "Stocked", "Ship Date"],
["$20.50", "4", "3/1/2016"]
]
}
]
}
La réponse se compose d'un objet qui répertorie les statistiques de cellule mises à jour, ainsi que d'un tableau d'objets UpdateValuesResponse, un pour chaque plage mise à jour. Exemple :
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 4,
"totalUpdatedColumns": 4,
"totalUpdatedCells": 10,
"totalUpdatedSheets": 1,
"responses": [
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:A4",
"updatedRows": 4,
"updatedColumns": 1,
"updatedCells": 4,
},
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D2",
"updatedRows": 2,
"updatedColumns": 3,
"updatedCells": 6,
}
],
}
La feuille obtenue se présente comme suit:
| A | B | C | D | |
| 1 | Article | Coût | En stock | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 01/03/2016 |
| 3 | Porte | |||
| 4 | Moteur | |||
| 5 |
Écrire des valeurs sans analyse
À partir d'une feuille vierge, l'exemple de code spreadsheets.values.update suivant montre comment écrire les valeurs dans la plage Sheet1!A1:E1, mais utilise le paramètre de requête RAW ValueInputOption pour empêcher l'analyse des chaînes écrites en tant que formules, valeurs booléennes ou nombres. Ils apparaissent sous forme de chaînes et l'alignement du texte est justifié dans la feuille.
Le corps de la requête est un objet ValueRange qui décrit les valeurs de plage à écrire. Le champ majorDimension indique que les tableaux sont des listes de valeurs organisées par lignes. Les valeurs existantes dans la plage cible sont écrasées.
Le protocole de requête est présenté ci-dessous.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW
{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Data", 123.45, true, "=MAX(D2:D4)", "10"]
],
}
La réponse se compose d'un objet UpdateValuesResponse tel que celui-ci:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}
La feuille obtenue se présente comme suit:
| A | B | C | D | E | |
| 1 | Données | 123,45 | TRUE | =MAX(D2:D4) | 10 |
| 2 |
Notez que "TRUE" est centré et qu'il s'agit d'une valeur booléenne, tandis que "123, 45" est justifié à droite parce qu'il s'agit d'un nombre et "10" est justifié à gauche parce qu'il s'agit d'une chaîne. La formule n'est pas analysée et apparaît également sous forme de chaîne.
Ajouter des valeurs
Commencez avec une feuille semblable au tableau ci-dessous:
| A | B | C | D | |
| 1 | Article | Coût | En stock | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 01/03/2016 |
| 3 |
L'exemple de code spreadsheets.values.append suivant montre comment ajouter deux lignes de valeurs en commençant par la ligne 3. Le paramètre de requête ValueInputOption est obligatoire et détermine si les valeurs écrites sont analysées (par exemple, si une chaîne est convertie en date).
Le corps de la requête est un objet ValueRange qui décrit les valeurs de plage à écrire. Le champ majorDimension indique que les tableaux sont des listes de valeurs organisées par lignes.
Le protocole de requête est présenté ci-dessous.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION
{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
],
}
La réponse se compose d'un objet AppendValuesResponse tel que celui-ci:
{
"spreadsheetId": SPREADSHEET_ID,
"tableRange": "Sheet1!A1:D2",
"updates": {
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A3:D4",
"updatedRows": 2,
"updatedColumns": 4,
"updatedCells": 8,
}
}
La feuille obtenue se présente comme suit:
| 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 |