Écriture de base

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 le formatage 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 fois 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 la méthode 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érents langages à l'aide des bibliothèques clientes des API Google, consultez Lire et écrire des valeurs de cellule.

Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez indiquer l'ID de la feuille de calcul, qui peut être trouvé dans l'URL de la feuille de calcul. Les plages à écrire sont spécifiées à l'aide de la notation A1. Par exemple, 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 ou non).

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 de 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 ressemble à ceci:

É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 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. 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 ou non).

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 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 ressemble à ceci:

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 Sheet1!B1:D2. Les valeurs existantes de 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 des cellules 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:

É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 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 la 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 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:

Notez que "TRUE" est centré et qu'il s'agit d'une valeur booléenne, tandis que "123.45" est aligné à droite, car il s'agit d'un nombre, et que "10" est aligné à 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 avec une feuille semblable au tableau ci-dessous:

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 ou non).

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: