Redação básica

A API Google Sheets permite gravar valores e fórmulas em células, intervalos, conjuntos de intervalos e planilhas inteiras. Os exemplos nesta página ilustram como algumas operações de gravação comuns podem ser realizadas com o spreadsheets.values recurso da API Sheets.

Também é possível gravar valores de células usando o spreadsheet.batchUpdate método, que pode ser útil se você quiser atualizar simultaneamente a formatação de células ou outras propriedades que o spreadsheets.values recurso não afeta. Por exemplo, se você quiser copiar um intervalo de células de uma planilha para outra, substituindo a fórmula e a formatação da célula, use o UpdateCellsRequest método com um spreadsheet.batchUpdate.

No entanto, para gravações de valores simples, é mais fácil usar o spreadsheets.values.update método ou o spreadsheets.values.batchUpdate método.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em relação ao idioma. Para saber como implementar gravações em diferentes idiomas usando as bibliotecas de cliente das APIs do Google, consulte Ler e gravar valores de células.

Nesses exemplos, o marcador de posição SPREADSHEET_ID indica onde você forneceria o ID da planilha, que pode ser descoberto no URL dela. Os intervalos em que gravar são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.

Gravar um único intervalo

Começando com uma planilha nova e em branco, o exemplo de spreadsheets.values.update código a seguir mostra como gravar os valores em um intervalo. O ValueInputOption parâmetro de consulta é obrigatório e determina se os valores gravados são analisados (por exemplo, se uma string é convertida em uma data).

O corpo da solicitação é um ValueRange objeto que descreve valores de intervalo a serem gravados. O majorDimension campo indica que as matrizes são listas de valores organizados por linhas. Os valores atuais no intervalo de destino são substituídos.

O protocolo de solicitação é mostrado abaixo.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

A resposta consiste em um UpdateValuesResponse objeto, como este:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

A planilha resultante será semelhante a esta:

	A	B	C	D
1	Item	Custo	Estocado	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta	US$ 15	2	15/03/2016
4	Mecanismo	US$ 100	1	20/03/2016
5	Total	US$ 135,5	7	20/03/2016

Gravar seletivamente em um intervalo

Ao gravar valores em um intervalo, é possível evitar a mudança de algumas células atuais definindo os elementos de matriz correspondentes como null. Também é possível limpar uma célula gravando uma string vazia ("") nela.

Começando com uma planilha que contém os mesmos dados produzidos pelo exemplo acima spreadsheets.values.update, o exemplo de código a seguir mostra como gravar os valores no intervalo B1:D4, deixando seletivamente algumas células inalteradas e limpando outras. O ValueInputOption parâmetro de consulta é obrigatório e determina se os valores gravados são analisados (por exemplo, se uma string é convertida em uma data).

O corpo da solicitação é um ValueRange objeto que descreve valores de intervalo a serem gravados. O majorDimension campo indica que as matrizes são listas de valores organizados por coluna.

O protocolo de solicitação é mostrado abaixo.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

O campo values aqui lista as mudanças feitas em cada coluna no intervalo. A primeira matriz indica que B1 deve ser deixado inalterado (devido ao elemento de matriz null), enquanto B4 deve ser limpo (string vazia). Os valores de B2 e B3 são atualizados. A terceira matriz executa as mesmas operações na coluna D, enquanto a segunda matriz vazia indica que a coluna C deve ser deixada inalterada.

A resposta consiste em um UpdateValuesResponse objeto, como este:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

A planilha resultante será semelhante a esta:

	A	B	C	D
1	Item	Custo	Estocado	Data de envio
2	Wheel	US$ 1,00	4	01/04/2016
3	Porta	US$ 2	2	15/04/2016
4	Mecanismo		1
5	Total	US$ 3,00	7	15/04/2016

A linha "Total", embora não seja alterada diretamente por essa solicitação, muda porque as células dela contêm fórmulas que dependem das células alteradas.

Gravar em vários intervalos

Começando com uma planilha em branco, o spreadsheets.values.batchUpdate exemplo de código a seguir mostra como gravar os valores nos intervalos Sheet1!A1:A4 e Sheet1!B1:D2. Os valores atuais no intervalo de destino são substituídos. O corpo da solicitação consiste em um ValueInputOption objeto que mostra como interpretar os dados de entrada e uma matriz de ValueRange objetos correspondentes a cada intervalo gravado. O majorDimension campo determina se as matrizes incluídas são interpretadas como matrizes de colunas ou linhas.

O protocolo de solicitação é mostrado abaixo.

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

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

A resposta consiste em um objeto que lista as estatísticas de células atualizadas e uma matriz de UpdateValuesResponse objetos, um para cada intervalo atualizado. Exemplo:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

A planilha resultante será semelhante a esta:

	A	B	C	D
1	Item	Custo	Estocado	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta
4	Mecanismo
5

Gravar valores sem análise

Começando com uma planilha em branco, o exemplo de código a seguir spreadsheets.values.update mostra como gravar os valores no intervalo Sheet1!A1:E1, mas usa o parâmetro de consulta RAW ValueInputOption para impedir que as strings gravadas sejam analisadas como fórmulas, booleanos ou números. Elas aparecem como strings e o alinhamento de texto é justificado na planilha.

O corpo da solicitação é um ValueRange objeto que descreve valores de intervalo a serem gravados. O majorDimension campo indica que as matrizes são listas de valores organizados por linhas. Os valores atuais no intervalo de destino são substituídos.

O protocolo de solicitação é mostrado abaixo.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

A resposta consiste em um UpdateValuesResponse objeto, como este:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

A planilha resultante será semelhante a esta:

	A	B	C	D	E
1	Dados	123,45	TRUE	=MAX(D2:D4)	10
2

O valor "TRUE" está centralizado e é um valor booleano, enquanto "123,45" está justificado à direita porque é um número, e "10" está justificado à esquerda porque é uma string. A fórmula não é analisada e também aparece como uma string.

Adicionar valores ao final

Comece com uma planilha como a tabela abaixo:

	A	B	C	D
1	Item	Custo	Estocado	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3

O exemplo de código a seguir spreadsheets.values.append mostra como adicionar duas novas linhas de valores começando pela linha 3. O ValueInputOption parâmetro de consulta é obrigatório e determina se os valores gravados são analisados (por exemplo, se uma string é convertida em uma data).

O corpo da solicitação é um ValueRange objeto que descreve valores de intervalo a serem gravados. O majorDimension campo indica que as matrizes são listas de valores organizados por linhas.

O protocolo de solicitação é mostrado abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

A resposta consiste em um AppendValuesResponse objeto, como este:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

A planilha resultante será semelhante a esta:

	A	B	C	D
1	Item	Custo	Estocado	Data de envio
2	Wheel	US$ 20,50	4	01/03/2016
3	Porta	US$ 15	2	15/03/2016
4	Mecanismo	US$ 100	1	20/03/2016
5