Pular para conteúdo

Google Sheets

As ações abaixo refletem exatamente as funções para controle de planilhas do Google Sheets.

Observação importante: os retornos das actions viram variáveis de estado do robô; use o nome exato da chave retornada precedida de $. Por exemplo, se uma ação retorna {'updated_range': 'Sheet1!A2:C3'}, você acessa com $updated_range no fluxo.

Somente métodos anotados com @decorators.robotaction estão documentados aqui.

Depois de começar a usar essas ações, é importante ter uma conta de serviço e compartilhar sua planilha com a conta de serviço.

Ative a API do Planilhas Google e crie uma conta de serviço

Para usar as ações do Planilhas Google, primeiro você precisa criar uma conta de serviço.

  1. Acesse o console do Google GCP e selecione o projeto em que deseja ativar a API do Planilhas Google e criar a conta de serviço.

  2. Acesse o gerenciamento da API do Planilhas Google e ative o uso da API. Tela de gerenciamento da API do Planilhas Google quando a API está inativa

  3. Clique em Credenciais. Tela principal do Google Sheet API Management

  4. Clique em Criar credenciais e depois em Conta de serviço. Menu para criar uma nova conta de serviço

  5. Dê um nome à sua nova Conta de Serviço e preencha todas as informações solicitadas e clique em CONCLUÍDO. Detalhes da conta de serviço

  6. As próximas duas etapas são necessárias apenas se você quiser um controle mais preciso sobre as concessões e acessos desta Conta de Serviço. Se você não precisar, basta clicar em CONCLUÍDO nessas etapas. Configurações de concessões e acessos

  7. Após a criação da Conta de Serviço, na tela Credenciais, clique na Conta de Serviço criada. Credenciais com nova conta de serviço criada

  8. Adicione uma nova chave a esta Conta de serviço, clicando em ADICIONAR CHAVE e depois em Criar nova chave. Adicionar chave

  9. Selecione a opção JSON para criar, clique em CREATE e aguarde o download do arquivo JSON. Seleção do tipo de chave

  10. Agora você compartilha sua planilha do Google com sua Conta de serviço. Não se esqueça de dar privilégios para editar a planilha se quiser que Marvin o faça.

Compartilhe a planilha com a conta de serviço

  1. Em seu Planilhas Google, clique em Compartilhar. Compartilhe sua planilha

  2. Em Adicionar pessoas e grupos, insira o endereço da sua Conta de serviço. Adicione o endereço da sua conta de serviço

  3. Verifique se os privilégios corretos são concedidos à Conta de Serviço. Se você deseja que o Marvin altere, exclua ou insira novos dados em sua planilha, você deve definir como Editor. Definir privilégios corretos para a conta de serviço

Ações

google.sheets.append

Se você definir cell_range como A1, Marvin evita sobrescrever dados existentes e anexa o novo conteúdo na primeira linha em branco após A1, sempre inserindo novos dados após a última linha da planilha.

Anexa valores ao final do intervalo indicado (usa spreadsheet.current_sheet + cell_range).

Parâmetros:
  • spreadsheet — objeto retornado por google.sheets.open.
  • cell_range — célula inicial ou intervalo (ex.: A1 ou A1:C1).
  • line_values (opcional) — lista representando uma linha (ex.: ['Col1','Col2']).
  • grid_values (opcional) — lista de listas para múltiplas linhas.
  • value_input_option (opcional, default 'RAW') — RAW ou USER_ENTERED.
Retornar:
  • updated_range — string com o intervalo atualizado (A1 notation).
  • first_col — letra da primeira coluna do bloco atualizado.
  • first_row — número da primeira linha do bloco atualizado.
  • last_col — letra da última coluna do bloco atualizado.
  • last_row — número da última linha do bloco atualizado.
Exceções:
  • InvalidParameters — se line_values e grid_values não forem informados.
  • GoogleSheetsException — erro ao chamar a API do Google Sheets.

Exemplo:

google.sheets.append($spreadsheet, "A1", line_values=["Nome","Email"])
updated_range = $updated_range
first_row = $first_row

google.sheets.delete_rows

Remove linhas entre start e end (inclusive). Se end for omitido, apenas start é removido.

Parâmetros:
  • spreadsheet — objeto retornado por google.sheets.open.
  • start — número (1-based) da primeira linha a remover.
  • end (opcional) — número da última linha a remover.
Retornar:
  • Esta ação retorna um dicionário vazio (nenhuma variável de estado é criada).
Exceções:
  • GoogleSheetsException — erro ao executar a operação na API.

Exemplo:

google.sheets.delete_rows($spreadsheet, 5, 7)
# sem variáveis retornadas

google.sheets.get_cell

Lê valores do intervalo informado e retorna values com coordenadas do bloco.

Parâmetros:
  • spreadsheet — objeto retornado por google.sheets.open.
  • cell_range — intervalo A1 (ex.: B2:C4).
  • value_render_option (opcional, default 'FORMATTED_VALUE') — FORMATTED_VALUE, UNFORMATTED_VALUE ou FORMULA.
Retornar:
  • values — matriz (linhas × colunas) com os valores retornados pela API.
  • first_col — letra da primeira coluna do bloco retornado.
  • first_row — número da primeira linha do bloco retornado.
  • last_col — letra da última coluna do bloco retornado.
  • last_row — número da última linha do bloco retornado.
Exceções:
  • GoogleSheetsException — erro na chamada à API.

Exemplo:

google.sheets.get_cell($spreadsheet, "B2:C4")
values = $values

google.sheets.open

Cria uma conexão com a planilha e retorna o objeto Spreadsheet usado pelas demais ações.

Para usar qualquer integração Google, é necessário ter uma conta de serviço GCP em arquivo JSON. Para criar a credencial, siga Ative a API do Planilhas Google e crie uma conta de serviço.

Parâmetros:

Tela do Planilhas Google e destaque onde obter as informações

  • spreadsheet_id — ID da planilha (extraído da URL).
  • current_sheet — nome da aba (sheet) que será usada por padrão.
  • service_account_path — caminho do asset JSON da Service Account.
Retornar:
  • spreadsheet — objeto Spreadsheet retornado pela ação.
Exceções:
  • GoogleSheetsException — erro ao obter informações da planilha ou autenticação.

Exemplo:

google.sheets.open("1_aF0LP...", "Plan1", "assets/service-account.json")
spreadsheet = $spreadsheet

google.sheets.update

Atualiza (substitui) os valores no intervalo informado.

Parâmetros:
  • spreadsheet — objeto retornado por google.sheets.open.
  • cell_range — intervalo a ser atualizado (ex.: A1:C3).
  • line_values (opcional) — lista representando uma linha.
  • grid_values (opcional) — lista de listas para múltiplas linhas.
  • value_input_option (opcional, default 'RAW') — determina como os dados de entrada devem ser interpretados. Valores:
Valor Descrição
RAW Os valores inseridos pelo usuário não serão analisados e serão armazenados como estão
USER_ENTERED Os valores serão analisados como se o usuário os digitasse na interface. Os números permanecem como números, mas strings podem ser convertidas em números, datas etc., seguindo as mesmas regras aplicadas ao inserir texto numa célula pela interface do Planilhas Google
Retornar:
  • updated_range
  • first_col_updated
  • first_line_updated # chave legada (deprecated) — corresponde a first_row_updated
  • first_row_updated
  • last_col_updated
  • last_line_updated # chave legada (deprecated) — corresponde a last_row_updated
  • last_row_updated
Exceções:
  • InvalidParameters — se line_values e grid_values não forem informados.
  • GoogleSheetsException — erro na API.

Exemplo:

google.sheets.update($spreadsheet, "A2:C2", line_values=["x","y","z"])
updated_range = $updated_range