Operações de página

Com a API Google Sheets, você pode criar, limpar, copiar e excluir páginas, além de controlar as propriedades delas. Os exemplos nesta página ilustram como é possível realizar algumas operações comuns do Planilhas com a API Sheets.

Esses exemplos são apresentados na forma de solicitações HTTP para a linguagem neutra. Para saber como implementar uma atualização em lote em linguagens diferentes usando as bibliotecas de cliente das APIs do Google, consulte Atualizar planilhas.

Nesses exemplos, os marcadores SPREADSHEET_ID e SHEET_ID indicam onde você fornece esses IDs. Você pode encontrar o ID da planilha no URL da planilha. Consiga o ID da planilha usando o método spreadsheets.get. Os intervalos são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.

Adicionar uma página

O exemplo de código spreadsheets.batchUpdate a seguir 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 a cor da guia.

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

O protocolo da solicitação é mostrado 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 exemplo de código spreadsheets.batchUpdate a seguir mostra como usar a UpdateCellsRequest para remover todos os valores de uma página sem alterar a formatação.

A especificação do campo userEnteredValue sem um valor correspondente é interpretada como uma instrução para limpar valores no intervalo. Essa configuração também pode ser usada com outros campos. Por exemplo, alterar o valor fields para userEnteredFormat remove toda a formatação compatível com a API Sheets, mas deixa os valores das células inalterados.

O protocolo da solicitação é mostrado 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

Veja no exemplo de código spreadsheet.sheets.copyTo a seguir 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 a 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 é definido como "Cópia de [título da página original]".

A resposta consiste em um objeto 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 exemplo de código spreadsheets.batchUpdate a seguir mostra como usar a DeleteSheetRequest para excluir uma página especificada por SHEET_ID.

O protocolo da solicitação é mostrado abaixo.

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

Ler dados da planilha

O exemplo de código spreadsheets.get a seguir mostra como receber informações da propriedade da planilha de uma planilha, especificada por SHEET_ID e SPREADSHEET_ID. Esse método é frequentemente usado para determinar os metadados de páginas dentro de uma planilha específica. Portanto, operações adicionais podem segmentar essas páginas. O parâmetro de consulta fields especifica que apenas os dados de propriedade da página precisam ser retornados, e não os dados de valores de células ou dados relacionados à planilha inteira.

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

A resposta consiste em um recurso Spreadsheet, que contém um objeto Sheet com elementos SheetProperties. 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
        }
      },
      ...
  ],
}