É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 les opérations d'écriture courantes spreadsheets.values ressource 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 spreadsheets.values ressource n'affecte pas. Par exemple, si vous souhaitez copier une plage de cellules à partir de d'une feuille à une autre tout en écrasant à la fois la formule de la cellule et la cellule vous pouvez utiliser UpdateCellsRequest à l'aide d'un spreadsheet.batchUpdate

Toutefois, pour les écritures de valeurs simples, il est plus facile d'utiliser spreadsheets.values.update ou la spreadsheets.values.batchUpdate .

Ces exemples sont présentés sous la forme de requêtes HTTP et neutres. Pour apprendre à implémenter des écritures dans différents langages à l'aide de les bibliothèques clientes de l'API Google, consultez l'article Lire et écrire la cellule valeurs.

Dans ces exemples, l'espace réservé SPREADSHEET_ID indique où vous devez fournir la feuille de calcul ID, qu'il peut trouver sur la page URL de la feuille de calcul. Les plages dans lesquelles écrire des données sont spécifiées à l'aide de A1 du lecteur d'écran. Exemple de plage : Sheet1!A1:D5.

Écrire une seule plage

En commençant par une nouvelle feuille de calcul vierge, les éléments suivants spreadsheets.values.update exemple montre comment écrire les valeurs dans une plage. La Requête ValueInputOption est requis et détermine si les valeurs écrites sont analysées (par (par exemple, si une chaîne est convertie ou non en date).

Le corps de la requête est ValueRange qui décrit les valeurs de plage à écrire. La Champ majorDimension indique que les tableaux sont des listes de valeurs organisées par lignes. Valeurs existantes de la plage cible sont écrasés.

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 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	Élément	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

Lors de l'écriture de valeurs dans une plage, il est possible d'éviter de modifier certaines cellules en définissant les éléments de tableau correspondants sur null. Il est également possible pour effacer une cellule en y écrivant une chaîne vide ("").

Commençons par une feuille contenant les mêmes données produites par la requête ci-dessus exemple, comme suit : spreadsheets.values.update exemple de code montre comment écrire les valeurs dans la plage B1:D4, de manière sélective en laissant certaines cellules inchangées et en effaçant d'autres. La Requête ValueInputOption est requis et détermine si les valeurs écrites sont analysées (par (par exemple, si une chaîne est convertie ou non en date).

Le corps de la requête est ValueRange qui décrit les valeurs de plage à écrire. La 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. La premier tableau indique que B1 ne doit pas être modifié (en raison de la présence du tableau null ), tandis que B4 doit être effacé (chaîne vide). B2 et B3 ont leurs valeurs mis à jour. Le troisième tableau effectue les mêmes opérations sur la colonne D, tandis que le un deuxième tableau vide indique que la colonne C doit rester inchangée.

La réponse se compose d'un 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	Élément	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 les "Totaux" , bien qu'elle ne soit pas directement modifiée par cette requête, changer parce que ses cellules contiennent des formules qui dépendent des cellules modifiées.

Écrire dans plusieurs plages

En commençant par une feuille vierge, les éléments suivants spreadsheets.values.batchUpdate exemple de code 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. La demande se compose d'un Un objet ValueInputOption qui montre comment interpréter les données d'entrée et un tableau de ValueRange objets correspondant à chaque plage écrite. La 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 est constituée d'un objet qui répertorie les statistiques de cellule mises à jour. et un tableau de 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	Élément	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

En commençant par une feuille vierge, les éléments suivants spreadsheets.values.update exemple de code montre comment écrire les valeurs dans la plage Sheet1!A1:E1, mais utilise la RAW ValueInputOption pour empêcher l'analyse des chaînes écrites comme des formules. des valeurs booléennes ou des 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 ValueRange qui décrit les valeurs de plage à écrire. La Champ majorDimension indique que les tableaux sont des listes de valeurs organisées par lignes. Valeurs existantes de la plage cible sont écrasés.

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 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ée et est une valeur booléenne, alors que "123.45" est correct justifié parce qu'il s'agit d'un nombre, et que « 10 » est justifiée, car il s'agit . 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	Élément	Coût	En stock	Date d'expédition
2	Roue	20,50 $	4	01/03/2016
3

Les éléments suivants : spreadsheets.values.append l'exemple de code montre comment ajouter deux lignes de valeurs en commençant par la ligne 3. La Requête ValueInputOption est requis et détermine si les valeurs écrites sont analysées (par (par exemple, si une chaîne est convertie ou non en date).

Le corps de la requête est ValueRange qui décrit les valeurs de plage à écrire. La 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 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	Élément	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