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 Sheets.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em relação ao idioma. 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 o 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 Google 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 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, a formatação, as 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
        }
      },
      ...
  ],
}