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 certaines opérations d'écriture courantes peuvent être effectuées 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 les méthodes spreadsheets.values.update ou spreadsheets.values.batchUpdate.
Ces exemples sont présentés sous la forme de requêtes HTTP pour être neutres en ce qui concerne le langage. Pour découvrir comment mettre en œuvre l'écriture dans différents langages à l'aide des bibliothèques clientes de l'API Google, consultez Lire et écrire des valeurs de cellules.
Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez fournir l'ID de la feuille de calcul, qui peut être trouvé à partir de l'URL de la feuille de calcul. Les plages dans lesquelles écrire sont spécifiées à l'aide de la notation A1. Un exemple de plage est Feuille1!A1:D5.
Écrire une seule plage
À partir 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 ou non 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 de la plage cible sont écrasées.
Le protocole de requête est illustré 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 consiste en 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 | 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 telles quelles et en 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 ou non 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 illustré 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 répertorie ici les modifications apportées à chaque colonne de la plage. Le premier tableau indique que B1 ne doit pas être modifié (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 ne doit pas être modifiée.
La réponse consiste en un objet UpdateValuesResponse comme 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 | 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
À 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 Feuille1!B1:D2. Les valeurs existantes de la plage cible sont remplacées. Le corps de la requête est constitué 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 illustré 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 mises à jour des cellules 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 se présente comme suit:
| A | B | C | D | |
| 1 | Article | Coût | Stocké | Date d'expédition |
| 2 | Roue | 20,50 $ | 4 | 01/03/2016 |
| 3 | Porte | |||
| 4 | Moteur | |||
| 5 |
Écrire des valeurs sans les analyser
En commençant par 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 les chaînes écrites d'être analysées en tant que formules, valeurs booléennes ou nombres. Elles 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 de la plage cible sont écrasées.
Le protocole de requête est illustré 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 consiste en un objet UpdateValuesResponse comme 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 est une valeur booléenne, alors 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 par une feuille semblable à celle du tableau ci-dessous:
| A | B | C | D | |
| 1 | Article | Coût | 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 ou non 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 illustré 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 consiste en un objet AppendValuesResponse comme 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 | 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 |