Operações de página

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

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em relação à linguagem. Para saber como implementar uma atualização em lote em diferentes linguagens usando as bibliotecas de cliente da API Google, consulte Atualizar planilhas.

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

Adicionar uma página

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar o 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 planilha criada (como o SHEET_ID).

O protocolo de 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 planilha de todos os valores, preservando os formatos

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar UpdateCellsRequest para remover todos os valores de uma planilha sem alterar a formatação.

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, mudar o valor de fields para userEnteredFormat remove toda a formatação compatível com a API Sheets da planilha, mas deixa os valores das células inalterados.

O protocolo de 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

O exemplo de código spreadsheet.sheets.copyTo a seguir mostra como copiar uma única planilha especificada por SHEET_ID de uma para outra.

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

A resposta consiste em um objeto SheetProperties que descreve as propriedades da planilha 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 o DeleteSheetRequest para excluir uma página especificada por SHEET_ID.

O protocolo de 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 de propriedades da planilha de uma planilha, especificada por SHEET_ID e SPREADSHEET_ID. Esse método geralmente é usado para determinar os metadados das planilhas em uma planilha específica, para que outras operações possam segmentar essas planilhas. O parâmetro de consulta fields especifica que apenas os dados de propriedade da planilha devem ser retornados, e não os dados de valor da célula ou relacionados a toda a planilha.

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 como 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
        }
      },
      ...
  ],
}