Operações de página

A API Google Sheets permite que você crie, limpe, copie e exclua planilhas, além de também controlar suas propriedades. Os exemplos nesta página ilustram como é possível realizar algumas operações comuns do Planilhas com o API Sheets.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutras. Para saber como implementar uma atualização em lote em diferentes idiomas usando bibliotecas de clientes da API do Google, consulte Atualizar planilhas.

Nestes exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID indica onde você deve fornecer esses IDs. Você pode encontrar a planilha ID no URL da planilha. Você pode receber o ID da planilha usando o spreadsheets.get. A são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.

Adicionar uma página

O seguinte spreadsheets.batchUpdate um exemplo de código mostra como usar a AddSheetRequest para adicionar uma página a uma planilha, além de definir o título, o tamanho da grade e cor da guia.

A resposta consiste em um AddSheetResponse, que contém um objeto com as propriedades da página criada (como seu SHEET_ID).

Confira o protocolo da solicitação abaixo.

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
          }
        }
      }
    }
  ]
}

Limpar uma página com todos os valores, preservando os formatos

O seguinte spreadsheets.batchUpdate um exemplo de código mostra como usar a UpdateCellsRequest para remover todos os valores de uma planilha, deixando a formatação inalterada.

Especificar o Campo userEnteredValue sem um valor correspondente é interpretado como uma instrução para limpar os valores no intervalo. Essa configuração também pode ser usada com outros campos. Por exemplo: mudando o valor fields para userEnteredFormat remove toda a formatação compatível com a API Sheets da planilha, mas deixa os valores das células inalterados.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Copiar uma página de uma planilha para outra

O seguinte spreadsheet.sheets.copyTo exemplo de código mostra como copiar uma única página especificada por SHEET_ID de uma planilha para outra.

A variável TARGET_SPREADSHEET_ID no corpo da solicitação especifica: planilha de destino. A cópia mantém todos os valores, formatação, fórmulas e outras propriedades do original. O título da página copiada está definido como "Copiar de [título da página original]".

A resposta consiste em um SheetProperties que descreve as propriedades da página criada.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

Excluir uma página

O seguinte spreadsheets.batchUpdate um exemplo de código mostra como usar a DeleteSheetRequest para excluir uma página especificada por SHEET_ID.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

Ler dados da planilha

O seguinte Exemplo de código do spreadsheets.get mostra como receber as informações da propriedade da planilha de uma planilha, especificada por SHEET_ID e SPREADSHEET_ID. Esse método é frequentemente usado para determinar metadados de páginas em uma planilha específica, de modo que operações adicionais podem segmentar essas planilhas. O parâmetro de consulta fields especifica apenas as propriedades da página. dados devem ser retornados (em oposição aos dados de valores de células ou dados relacionados à toda a planilha).

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

A resposta consiste em um Spreadsheet que contém um Objeto Sheet com SheetProperties os elementos. Se um determinado campo de resposta for definido com o valor padrão, ele será omitido da resposta.

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