Esta página foi traduzida pela API Cloud Translation.

Redação básica

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

Também é possível escrever valores de células usando a função spreadsheet.batchUpdate , o que pode ser útil se você deseja atualizar simultaneamente a formatação da célula ou outras propriedades que 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 da célula e a célula e a formatação, use o UpdateCellsRequest com um spreadsheet.batchUpdate.

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

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutras. Para saber como implementar gravações em diferentes idiomas usando as bibliotecas cliente da API do Google, consulte Ler e gravar célula de imagem.

Nesses exemplos, o marcador SPREADSHEET_ID indica na qual você deve fornecer o modelo de ID, que pode ser descoberto na URL da planilha. Os intervalos para gravar são especificados usando A1 . Um exemplo de intervalo é Sheet1!A1:D5.

Gravar um único intervalo

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

O corpo da solicitação é um ValueRange objeto que descreve os valores do intervalo a serem gravados. A Campo majorDimension indica que as matrizes são listas de valores organizadas por linhas. Valores atuais no intervalo de destino serão substituídos.

Confira o protocolo da solicitação 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 , como este:

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

A página resultante vai ficar assim:

	A	B	C	D
1	Item	Custo	Armazenado	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	R$ 135,50	7	20/03/2016

Gravar seletivamente em um intervalo

Ao gravar valores em um intervalo, é possível evitar a alteração de alguns valores células definindo os elementos de matriz correspondentes como null. Também é possível para limpar uma célula escrevendo uma string vazia ("") nela.

Começar com uma página que contenha os mesmos dados produzidos pelos requisitos acima exemplo, o seguinte spreadsheets.values.update exemplo de código mostra como gravar os valores no intervalo B1:D4, seletivamente deixando algumas células inalteradas e limpando outras. A Consulta ValueInputOption é obrigatório e determina se os valores gravados são analisados (por exemplo, se uma string é ou não convertida em uma data).

Confira o protocolo da solicitação 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 lista as alterações feitas em cada coluna no intervalo. A a primeira matriz indica que a célula B1 não deve ser alterada (devido à matriz null) ), enquanto B4 deve ser apagado (string vazia). B2 e B3 têm seus valores atualizado. A terceira matriz executa as mesmas operações na coluna D, enquanto a a segunda matriz vazia indica que a coluna C não deve ser alterada.

A resposta consiste em um UpdateValuesResponse como este:

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

A página resultante vai ficar assim:

	A	B	C	D
1	Item	Custo	Armazenado	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

Os "Totais" linha, embora não seja diretamente alterada por esta solicitação, não ser alterado porque suas células contêm fórmulas que dependem das células alteradas.

Gravar em vários intervalos

Começando com uma folha em branco, spreadsheets.values.batchUpdate exemplo de código 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. A solicitação corpo é composto por O objeto ValueInputOption que mostra como interpretar os dados de entrada e uma matriz de ValueRange objetos que correspondem a cada intervalo gravado. A Campo majorDimension determina se as matrizes incluídas são interpretadas como matrizes de colunas ou linhas.

Confira o protocolo da solicitação 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élula atualizadas e uma matriz de UpdateValuesResponse , 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 página resultante vai ficar assim:

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

Gravar valores sem analisar

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

Confira o protocolo da solicitação 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 como este:

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

A página resultante vai ficar assim:

	A	B	C	D	E
1	Dados	123,45	VERDADEIRO	=MÁXIMO(D2:D4)	10
2

Observe que "TRUE" é centralizado e é um valor booleano, enquanto "123,45" está certo justificada por ser um número, e "10" é justificada à esquerda porque é uma fio. A fórmula não é analisada e também aparece como uma string.

Anexar valores

Comece com uma planilha como a da tabela abaixo:

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

O seguinte spreadsheets.values.append exemplo de código mostra como adicionar duas novas linhas de valores a partir da linha 3. A Consulta ValueInputOption é obrigatório e determina se os valores gravados são analisados (por exemplo, se uma string é ou não convertida em uma data).

Confira o protocolo da solicitação 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 como este:

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

A página resultante vai ficar assim:

	A	B	C	D
1	Item	Custo	Armazenado	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