Além dos dados de valor contidos em suas células, um planilha inclui muitos outros tipos de dados, como:
- Dimensões
- Formatos e bordas de células
- Intervalos nomeados
- Intervalos protegidos
- Formatação condicional
Esses são alguns dos muitos tipos de dados que controlam a aparência e
operação de uma planilha. Com o método spreadsheets.batchUpdate
,
atualizar qualquer um desses detalhes da planilha. As alterações são agrupadas em um lote,
se uma solicitação não for bem-sucedida, nenhuma das outras (possivelmente dependente)
alterações são gravadas.
Esta página descreve os conceitos básicos de uso do
spreadsheets.batchUpdate
. Para ler e gravar dados de valores de células, use o
spreadsheets.values
recurso descrito em Ler e gravar valores de célula.
Categorias de operação
As operações específicas compatíveis com spreadsheets.batchUpdate
podem ser agrupadas
nas seguintes categorias amplas:
Categoria | Descrição |
---|---|
Adicionar (e Duplicar) | Adicionar novos objetos (às vezes baseados em objetos antigos, como em Solicitações duplicadas). |
Atualizar (e Definir) | Atualizar certas propriedades de um objeto, normalmente deixando as propriedades antigas inalteradas (enquanto uma solicitação Set substitui os dados anteriores). |
Excluir | Remover objetos. |
Essas categorias são usadas na próxima seção para descrever o comportamento de operações específicas.
Operações de atualização em lote
O método spreadsheets.batchUpdate
pega um ou mais
Solicitação
objetos, cada um especificando um único tipo de solicitação a ser executada. Existem
para muitos tipos diferentes de solicitações. Aqui está um detalhamento dos tipos de solicitações,
agrupadas em diferentes categorias.
Há também algumas solicitações adicionais que imitam ações do usuário para manipulação dados:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
Limites
Para saber mais sobre os limites de células e linhas no Planilhas Google, consulte Arquivos que você pode armazenar em Google Drive.
Máscaras de campo
Muitas das "atualizações" solicitações exigem máscaras de campo. Os valores separados por vírgula
de campos para atualizar apenas determinados campos em um objeto, deixando a
outros campos inalterados. Uma máscara de campo de *
é tratada como um
curinga e é uma forma abreviada de especificar todos os campos de uma mensagem (o que significa
um campo poderá voltar ao estado padrão se você não especificar um valor para ele em
da solicitação).
Para mais informações sobre máscaras de campo, consulte Usar campo
máscaras.
O exemplo a seguir usa o
UpdateSpreadsheetPropertiesRequest
para atualizar apenas o título de uma planilha:
Solicitação:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
Corpo da solicitação:
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}
Substitua TITLE pelo novo título da planilha.
Respostas
Ao atualizar uma planilha, alguns tipos de solicitação podem retornar respostas. Esses em uma matriz, com cada resposta ocupando o mesmo índice que o solicitação correspondente. Algumas solicitações não têm respostas, e para aquelas a resposta estiver vazia.
Normalmente, "adicionar" as solicitações têm respostas que retornam informações como o ID do objeto adicionado. Para acessar a lista de respostas compatíveis, consulte Respostas.
Exemplo
O exemplo de código abaixo executa essas ações:
- Atualiza o título da planilha usando a variável
title
. - Encontra e substitui valores de células na planilha usando
find
e Variáveisreplacement
.