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 illustrent comment effectuer 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 des cellules, 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 pour être neutres en termes de langue. Pour découvrir comment implémenter des écritures dans différentes langues à l'aide des bibliothèques clientes des API Google, consultez Lire et écrire des valeurs de cellules.
Dans ces exemples, l'espace réservé SPREADSHEET_ID indique l'endroit où vous devez fournir l'ID de la feuille de calcul, que vous pouvez trouver dans l'URL de la feuille de calcul. Les plages dans lesquelles écrire sont spécifiées à l'aide de la notation A1. Par exemple, la plage Feuille1!A1:D5.
Écrire une seule plage
En partant d'une nouvelle feuille de calcul vierge, 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 la 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, tel que celui-ci :
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}La feuille obtenue ressemble à ceci :
| A | B | C | D | |
| 1 | Élément | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 1/3/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, vous pouvez é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 partant d'une feuille contenant les mêmes données que celles 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 effaçant d'autres de manière sélective. 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 la 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 liste les modifications apportées à chaque colonne de la plage. Le premier tableau indique que la cellule B1 doit rester inchangée (en raison de l'élément de tableau null), tandis que la cellule B4 doit être effacée (chaîne vide). Les valeurs des cellules 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 ressemble à ceci :
| A | B | C | D | |
| 1 | Élément | Coût | 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 la ligne "Totaux", bien qu'elle ne soit pas directement modifiée par cette requête, change, car ses cellules contiennent des formules qui dépendent des cellules modifiées.
Écrire dans plusieurs plages
En partant 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 dans la plage cible sont écrasées. Le corps de la requête se compose d'un objet ValueInputOption qui montre 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 liste les statistiques de cellule mises à jour et 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 ressemble à ceci :
| A | B | C | D | |
| 1 | Élément | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 1/3/2016 |
| 3 | Porte | |||
| 4 | Moteur | |||
| 5 |
Écrire des valeurs sans les analyser
En partant 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. Elles s'affichent 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 la 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 ressemble à ceci :
| A | B | C | D | E | |
| 1 | Données | 123,45 | TRUE | =MAX(D2:D4) | 10 |
| 2 |
Notez que "TRUE" est centré et est une valeur booléenne, tandis que "123.45" est justifié à droite, car il s'agit d'un nombre, et que "10" est justifié à gauche, car 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 par une feuille de calcul semblable à celle ci-dessous :
| A | B | C | D | |
| 1 | Élément | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 1/3/2016 |
| 3 |
L'exemple de code spreadsheets.values.append suivant montre comment ajouter deux nouvelles lignes de valeurs à partir de 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 la 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 ressemble à ceci :
| A | B | C | D | |
| 1 | Élément | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 1/3/2016 |
| 3 | Porte | 15 $ | 2 | 15/03/2016 |
| 4 | Moteur | 100 $ | 1 | 20/03/2016 |
| 5 |