Opérations Sheets

L'API Google Sheets vous permet de créer, effacer, copier et supprimer des feuilles, ainsi que de contrôler leurs propriétés. Les exemples de cette page montrent comment réaliser certaines opérations Sheets courantes avec l'API Sheets.

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 implémenter une mise à jour groupée dans différents langages à l'aide des bibliothèques clientes de l'API Google, consultez Mettre à jour des feuilles de calcul.

Dans ces exemples, les espaces réservés SPREADSHEET_ID et SHEET_ID indiquent où vous devez fournir ces ID. L'ID de la feuille de calcul se trouve dans son URL. Vous pouvez obtenir l'ID de la feuille à l'aide de la méthode spreadsheets.get. Ces plages sont spécifiées au format A1. Exemple de plage : Feuille1!A1:D5.

Ajouter une feuille

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser AddSheetRequest pour ajouter une feuille à une feuille de calcul, tout en définissant le titre, la taille de la grille et la couleur des onglets.

La réponse consiste en un AddSheetResponse, qui contient un objet avec les propriétés de la feuille créée (comme son SHEET_ID).

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

Effacer une feuille contenant toutes les valeurs tout en conservant les formats

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser UpdateCellsRequest pour supprimer toutes les valeurs d'une feuille sans modifier la mise en forme.

Spécifier le champ userEnteredValue sans valeur correspondante est interprété comme une instruction permettant d'effacer des valeurs dans la plage. Ce paramètre peut également être utilisé avec d'autres champs. Par exemple, remplacer la valeur fields par userEnteredFormat supprime de la feuille toute la mise en forme acceptée par l'API Sheets, mais conserve les valeurs des cellules telles quelles.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Copier une feuille d'une feuille de calcul dans une autre

L'exemple de code spreadsheet.sheets.copyTo suivant montre comment copier une feuille spécifiée par SHEET_ID d'une feuille de calcul à une autre.

La variable TARGET_SPREADSHEET_ID dans le corps de la requête spécifie la feuille de calcul de destination. La copie conserve toutes les valeurs, la mise en forme, les formules et les autres propriétés de l'original. Le titre de la feuille copiée est défini sur "Copie de [titre de la feuille d'origine]".

La réponse consiste en un objet SheetProperties décrivant les propriétés de la feuille créée.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo
{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

Supprimer une feuille

L'exemple de code spreadsheets.batchUpdate suivant montre comment utiliser DeleteSheetRequest pour supprimer une feuille spécifiée par SHEET_ID.

Le protocole de requête est illustré ci-dessous.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

Lire les données de la feuille

L'exemple de code spreadsheets.get suivant montre comment obtenir des informations sur une propriété sheet à partir d'une feuille de calcul spécifiée par SHEET_ID et SPREADSHEET_ID. Cette méthode est souvent utilisée pour déterminer les métadonnées des feuilles d'une feuille de calcul spécifique afin que des opérations supplémentaires puissent cibler ces feuilles. Le paramètre de requête fields spécifie que seules les données de propriété de la feuille doivent être renvoyées (par opposition aux données de valeur des cellules ou à celles liées à l'ensemble de la feuille de calcul).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

La réponse consiste en une ressource Spreadsheet, qui contient un objet Sheet avec des éléments SheetProperties. Si un champ de réponse donné est défini sur la valeur par défaut, il est omis de la réponse.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}