Google Sheets

Visão geral

Google Sheets é uma ferramenta de planilha baseada em nuvem que permite colaboração em tempo real, análise de dados e integração com outros aplicativos do Google Workspace. Com a integração no SquadOS, seus agentes podem criar e editar planilhas, ler e escrever dados, formatar células, gerenciar abas, criar gráficos e automatizar fluxos completos de dados — tudo de forma programática.

• Site oficial: https://sheets.google.com/
• Documentação na Composio: docs.composio.dev/toolkits/googlesheets

Autenticação

Esta ferramenta utiliza OAuth 2.0 (OAUTH2) para conectar.

Você vai precisar autorizar o acesso à sua conta Google. O fluxo OAuth é gerenciado pela Composio — nenhuma credencial manual é necessária.

Campo	Obrigatório	Descrição
Conta Google	Sim	Autorização OAuth 2.0 para acesso ao Google Sheets.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Google Sheets.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde autoriza o acesso (OAuth) à sua conta Google.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Perguntas frequentes

Como configurar credenciais OAuth personalizadas para o Google Sheets?

Consulte o guia passo a passo em Como criar credenciais OAuth2 para Apps Google.

Por que vejo “App is blocked” ao conectar o Google Sheets?

O cliente OAuth está solicitando escopos que o Google ainda não verificou para aquele app. Remova os escopos adicionais da sua configuração de auth, ou crie seu próprio app OAuth e envie os escopos para verificação. Veja Como criar credenciais OAuth2 para Apps Google.

Por que recebo o erro “Google Sheets API has not been used in project”?

Ao usar credenciais OAuth personalizadas, a Google Sheets API precisa estar ativada no projeto do Google Cloud que possui essas credenciais. Ative-a em Google Cloud Console em APIs & Services, aguarde alguns minutos e tente novamente.

Por que recebo “Error 400: invalid_scope”?

Os escopos solicitados são inválidos ou estão formatados incorretamente na URL de autorização. Verifique os valores de escopo na documentação de escopos OAuth do Google.

Por que a tela de consentimento OAuth exibe “Composio” em vez do meu app?

Por padrão, a tela de consentimento usa o app OAuth da Composio. Para exibir o nome e logotipo do seu próprio app, crie seu próprio app OAuth e configure um URL de redirecionamento personalizado. Consulte White-labeling de autenticação.

Por que estou recebendo erros 401 nas chamadas de tool?

O token de acesso do usuário não é mais válido. Causas comuns: o usuário revogou o acesso, alterou senha ou 2FA, uma política do Workspace admin mudou, ou o limite de tokens de atualização do Google (~50 por conta) foi excedido. Reautenticar o usuário normalmente resolve.

Por que estou recebendo “Quota Exhausted” ou “rate limit exhausted”?

O Google impõe cotas por minuto e diárias. Se você estiver usando o app OAuth padrão da Composio, compartilha essa cota com outros usuários, o que pode fazer os limites serem atingidos mais rápido. Use suas próprias credenciais OAuth para obter uma cota dedicada, e adicione backoff exponencial e retentativas para lidar com limites temporários.

Ações disponíveis

Adicionar aba à planilha existente

GOOGLESHEETS_ADD_SHEET

Adiciona uma nova aba a uma planilha. Suporta três tipos de aba: GRID, OBJECT e DATA_SOURCE. Tipos de aba: GRID (padrão) é uma planilha padrão com linhas/colunas; OBJECT contém um gráfico (requer objectSheetConfig com chartSpec); DATA_SOURCE conecta ao BigQuery (requer dataSourceConfig e escopo OAuth bigquery.readonly). Nomes de aba devem ser únicos; use force_unique=true para adicionar sufixo automático se o nome já existir.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
title	string	Não	Nome para a nova aba. Deve ser único na planilha. Exemplo: “Q3 Report”, “Sales Data 2025”. Alias: sheet_name.
properties	object	Não	Propriedades avançadas da aba (dimensões da grade, cor da aba, posição, etc.).
force_unique	boolean	Não	Quando True (padrão), garante que o nome seja único adicionando sufixo numérico (ex.: _2, _3) se o nome já existir.
spreadsheet_id	string	Sim	ID da planilha onde a nova aba será adicionada. É a string alfanumérica longa na URL do Google Sheets.
data_source_config	object	Não	Configuração para criar uma aba DATA_SOURCE conectada ao BigQuery. Requer escopo OAuth adicional: bigquery.readonly.
object_sheet_config	object	Não	Configuração para criar uma aba OBJECT (que contém um gráfico).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Agregar dados de coluna

GOOGLESHEETS_AGGREGATE_COLUMN_DATA

Busca linhas onde uma coluna específica corresponde a um valor e realiza operações matemáticas nos dados de outra coluna.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
operation	string (“sum” | “average” | “count” | “min” | “max” | “percentage”)	Sim	Operação matemática a realizar nos valores da coluna alvo.
sheet_name	string	Sim	Nome da aba específica na planilha. A correspondência é case-insensitive.
search_value	string	Não	Valor exato a buscar na coluna de pesquisa. Se não fornecido, todos os dados da coluna alvo são agregados.
search_column	string	Não	Coluna a pesquisar para filtrar linhas. Pode ser uma letra (ex.: ‘A’) ou nome de coluna do cabeçalho.
target_column	string	Sim	Coluna para agregar os dados. Pode ser uma letra (ex.: ‘C’) ou nome de coluna do cabeçalho.
case_sensitive	boolean	Não	Se a pesquisa deve ser case-sensitive.
has_header_row	boolean	Não	Se a primeira linha contém cabeçalhos de coluna.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.
percentage_total	number	Não	Para a operação percentage, o valor total para calcular o percentual. Se não fornecido, usa a soma de todos os valores.
additional_filters	array	Não	Condições extras de coluna=valor aplicadas com lógica AND. Exemplo: [{"column": "Region", "value": "APAC"}].

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Adicionar dimensão

GOOGLESHEETS_APPEND_DIMENSION

Adiciona novas linhas ou colunas a uma aba, aumentando seu tamanho. Use quando precisar acrescentar linhas ou colunas vazias a uma aba existente.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
length	integer	Sim	Número de linhas ou colunas a adicionar.
sheet_id	integer	Sim	ID numérico da aba (não o nome). Encontrado na URL como parâmetro ‘gid’.
dimension	string (“ROWS” | “COLUMNS”)	Sim	Especifica se devem ser adicionadas linhas ou colunas.
spreadsheet_id	string	Sim	ID da planilha.
response_ranges	array	Não	Limita os intervalos da planilha incluídos na resposta.
response_include_grid_data	boolean	Não	True se os dados da grade devem ser incluídos na resposta.
include_spreadsheet_in_response	boolean	Não	True se a planilha atualizada deve ser incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Redimensionar linhas ou colunas automaticamente

GOOGLESHEETS_AUTO_RESIZE_DIMENSIONS

Ajusta automaticamente as larguras de colunas ou alturas de linhas para caber no conteúdo, usando batchUpdate.autoResizeDimensions. Use após escrever dados para ajustar o layout.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	ID numérico da aba a redimensionar. sheet_id ou sheet_name deve ser fornecido.
dimension	string (“ROWS” | “COLUMNS”)	Sim	Dimensão a redimensionar automaticamente.
end_index	integer	Sim	Índice final (base zero, exclusivo) do intervalo de dimensão a redimensionar.
sheet_name	string	Não	Nome da aba a redimensionar. Se ambos forem fornecidos, sheet_name tem precedência.
start_index	integer	Sim	Índice inicial (base zero, inclusivo) do intervalo de dimensão a redimensionar.
spreadsheet_id	string	Sim	ID da planilha.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Limpar valores por filtro de dados em lote

GOOGLESHEETS_BATCH_CLEAR_VALUES_BY_DATA_FILTER

Limpa um ou mais intervalos de valores de uma planilha usando filtros de dados. Apenas valores são removidos — outras propriedades da célula (formatação, validação de dados, etc.) são mantidas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
dataFilters	array	Sim	Os DataFilters usados para determinar quais intervalos limpar.
spreadsheetId	string	Sim	ID da planilha a atualizar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter dados da planilha em lote

GOOGLESHEETS_BATCH_GET

Recupera dados de intervalos de células especificados em uma planilha do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ranges	array	Não	Lista de intervalos de células em notação A1 para recuperar dados. Se omitido, todos os dados da primeira aba são retornados.
majorDimension	string (“DIMENSION_UNSPECIFIED” | “ROWS” | “COLUMNS”)	Não	Dimensão principal para organizar os dados nos resultados.
spreadsheet_id	string	Sim	Identificador único da planilha. Aceita ID direto ou URL completa do Google Sheets.
valueRenderOption	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores devem ser renderizados na saída.
dateTimeRenderOption	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas devem ser renderizadas na saída.
empty_strings_filtered	boolean	Não	Indica se strings vazias foram filtradas da resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar planilha em lote (Descontinuada)

GOOGLESHEETS_BATCH_UPDATE

DESCONTINUADA: Use GOOGLESHEETS_VALUES_UPDATE em vez desta. Escreve valores em UM intervalo de uma planilha do Google. Para atualizar MÚLTIPLOS intervalos, faça chamadas SEPARADAS para cada intervalo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
values	array	Sim	Array 2D de valores de células onde cada array interno representa uma linha.
sheet_name	string	Sim	Nome da aba específica na planilha a atualizar.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.
value_input_option	string (“RAW” | “USER_ENTERED”)	Não	Como os dados de entrada devem ser interpretados.
first_cell_location	string	Não	Célula inicial para o intervalo de atualização em notação A1 sem prefixo de aba (ex.: ‘A1’, ‘B5’). Se omitido, os valores são adicionados como novas linhas no final.
include_values_in_response	boolean	Não	Se True, a resposta inclui os valores atualizados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar valores por filtro de dados em lote

GOOGLESHEETS_BATCH_UPDATE_VALUES_BY_DATA_FILTER

Atualiza valores em intervalos correspondentes a filtros de dados. Use quando precisar atualizar dados específicos com base em critérios em vez de intervalos de células fixos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
data	array	Sim	Os novos valores a aplicar à planilha. Pode ser uma string JSON ou uma lista de objetos DataFilterValueRange.
spreadsheetId	string	Sim	ID da planilha a atualizar.
valueInputOption	string (“INPUT_VALUE_OPTION_UNSPECIFIED” | “RAW” | “USER_ENTERED”)	Sim	Como os dados de entrada devem ser interpretados.
includeValuesInResponse	boolean	Não	Se a resposta deve incluir os valores das células atualizadas.
responseValueRenderOption	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores na resposta devem ser renderizados.
responseDateTimeRenderOption	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas na resposta devem ser renderizadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Limpar filtro básico

GOOGLESHEETS_CLEAR_BASIC_FILTER

Remove o filtro básico de uma aba. Use quando precisar remover um filtro básico existente de uma aba específica.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Sim	ID da aba da qual o filtro básico deve ser removido.
spreadsheet_id	string	Sim	ID da planilha.
response_ranges	array	Não	Limita os intervalos incluídos na resposta.
response_include_grid_data	boolean	Não	True se os dados da grade devem ser retornados na resposta.
include_spreadsheet_in_response	boolean	Não	Determina se a planilha atualizada deve ser incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Limpar valores da planilha

GOOGLESHEETS_CLEAR_VALUES

Limpa o conteúdo das células (preservando formatação e notas) de um intervalo especificado em notação A1.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
range	string	Sim	Intervalo em notação A1 para limpar os valores (ex.: ‘Sheet1!A1:B2’, ‘A1:D5’).
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar gráfico no Google Sheets

GOOGLESHEETS_CREATE_CHART

Cria um gráfico em uma planilha usando o intervalo de dados e o tipo de gráfico especificados. Use chart_type + data_range para um gráfico simples, ou forneça um chart_spec completo para suporte a todos os tipos de gráfico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
title	string	Não	Título opcional do gráfico.
sheet_id	integer	Sim	ID numérico da aba onde o gráfico será criado. Use ‘Obter informações da planilha’ para recuperar IDs de abas válidos.
subtitle	string	Não	Subtítulo opcional do gráfico.
chart_spec	object	Não	Objeto ChartSpec completo para suporte a todos os tipos de gráfico e opções avançadas.
chart_type	string (“BAR” | “LINE” | “AREA” | “COLUMN” | “SCATTER” | “COMBO” | “STEPPED_AREA” | “PIE” | “HISTOGRAM” | “BUBBLE” | “CANDLESTICK” | “TREEMAP” | “WATERFALL” | “ORG” | “SCORECARD”)	Sim	Tipo de gráfico a criar.
data_range	string	Sim	Intervalo contíguo único de dados para o gráfico em notação A1 (ex.: ‘A1:C10’).
x_axis_title	string	Não	Título opcional para o eixo X.
y_axis_title	string	Não	Título opcional para o eixo Y.
background_red	number	Não	Componente vermelho da cor de fundo do gráfico (0.0–1.0).
spreadsheet_id	string	Sim	ID da planilha onde o gráfico será criado.
background_blue	number	Não	Componente azul da cor de fundo do gráfico (0.0–1.0).
legend_position	string	Não	Posição da legenda do gráfico. Opções: BOTTOM_LEGEND, TOP_LEGEND, LEFT_LEGEND, RIGHT_LEGEND, NO_LEGEND.
background_green	number	Não	Componente verde da cor de fundo do gráfico (0.0–1.0).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar uma planilha do Google

GOOGLESHEETS_CREATE_GOOGLE_SHEET1

Cria uma nova planilha do Google no Google Drive. Se um título for fornecido, a planilha será criada com esse nome. Opcionalmente cria a planilha em uma pasta específica usando folder_id ou folder_name.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
title	string	Não	Título para a nova planilha. Se omitido, o Google cria com um nome padrão.
folder_id	string	Não	ID da pasta do Google Drive onde a planilha deve ser criada. Tem precedência sobre folder_name.
folder_name	string	Não	Nome da pasta do Google Drive. Se múltiplas pastas corresponderem, você receberá uma lista para escolher.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar coluna na planilha

GOOGLESHEETS_CREATE_SPREADSHEET_COLUMN

Cria uma nova coluna em uma planilha do Google. Especifique a aba alvo usando sheet_id (numérico) ou sheet_name (texto).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	Identificador numérico da aba. Padrão: 0 (primeira aba) se nenhum dos dois for fornecido.
sheet_name	string	Não	Nome da aba onde a coluna será adicionada. Se ambos forem fornecidos, sheet_id tem precedência.
insert_index	integer	Não	Índice base zero onde a nova coluna será inserida.
spreadsheet_id	string	Sim	Identificador único da planilha.
response_ranges	array	Não	Limita os intervalos incluídos na resposta.
inherit_from_before	boolean	Não	Se True, a nova coluna herda propriedades da coluna imediatamente à esquerda.
response_include_grid_data	boolean	Não	Se True, dados da grade serão incluídos na resposta.
include_spreadsheet_in_response	boolean	Não	Se True, a planilha atualizada será incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar linha na planilha

GOOGLESHEETS_CREATE_SPREADSHEET_ROW

Insere uma nova linha vazia em uma aba específica em um índice determinado, opcionalmente herdando a formatação da linha acima.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	Identificador numérico da aba. sheet_id ou sheet_name deve ser fornecido.
sheet_name	string	Não	Nome da aba. Se ambos forem fornecidos, sheet_id tem precedência.
insert_index	integer	Não	Índice base zero onde a nova linha deve ser inserida.
spreadsheet_id	string	Sim	Identificador único da planilha.
response_ranges	array	Não	Limita os intervalos incluídos na resposta. Use notação A1.
inherit_from_before	boolean	Não	Se True, a nova linha herda formatação da linha imediatamente acima.
response_include_grid_data	boolean	Não	Se True, dados da grade serão incluídos na resposta.
include_spreadsheet_in_response	boolean	Não	Se True, a planilha atualizada será incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir gráfico do Google Sheets

GOOGLESHEETS_DELETE_CHART

Exclui um gráfico existente de uma planilha. Esta ação é irreversível — o gráfico não pode ser recuperado após a exclusão. Os dados da fonte (células com dados) permanecem inalterados; apenas a visualização do gráfico é removida.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
chart_id	integer	Sim	Identificador numérico único do gráfico a excluir (também conhecido como objectId ou chartId).
spreadsheet_id	string	Sim	ID da planilha que contém o gráfico a excluir.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir dimensão (linhas/colunas)

GOOGLESHEETS_DELETE_DIMENSION

Remove linhas ou colunas especificadas de uma aba em uma planilha do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	ID numérico único da aba. Use GOOGLESHEETS_GET_SPREADSHEET_INFO para encontrar o ID.
dimension	string (“ROWS” | “COLUMNS”)	Não	Dimensão a excluir (ROWS ou COLUMNS).
end_index	integer	Não	Índice final (base zero, exclusivo) do intervalo a excluir.
sheet_name	string	Não	Nome da aba. sheet_id ou sheet_name deve ser fornecido.
start_index	integer	Não	Índice inicial (base zero, inclusivo) do intervalo a excluir.
spreadsheet_id	string	Sim	ID da planilha.
response_ranges	array	Não	Limita os intervalos incluídos na resposta.
delete_dimension_request	object	Não	Detalhes do objeto de requisição para excluir dimensão.
response_include_grid_data	boolean	Não	True se dados da grade devem ser retornados.
include_spreadsheet_in_response	boolean	Não	Determina se a resposta deve incluir a planilha atualizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir aba

GOOGLESHEETS_DELETE_SHEET

Remove uma aba (worksheet) de uma planilha. Uma planilha deve conter pelo menos uma aba, portanto a última aba não pode ser excluída.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheetId	integer	Sim	ID da aba a excluir. A planilha deve ter pelo menos uma aba restante.
spreadsheetId	string	Sim	ID da planilha da qual a aba será excluída.
responseRanges	array	Não	Limita os intervalos retornados quando includeSpreadsheetInResponse é True.
responseIncludeGridData	boolean	Não	True se os dados da grade devem ser retornados na resposta.
includeSpreadsheetInResponse	boolean	Não	Determina se a planilha atualizada deve ser retornada na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Executar SQL na planilha

GOOGLESHEETS_EXECUTE_SQL

DESCONTINUADA: Use ações diretas do Google Sheets em vez desta. Executa consultas SQL contra tabelas do Google Sheets. Suporta operações SELECT, INSERT, UPDATE, DELETE e cláusulas WITH (CTEs).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sql	string	Sim	Consulta SQL completa a executar. Deve começar com SELECT, INSERT, UPDATE, DELETE ou WITH.
dry_run	boolean	Não	Visualiza as alterações sem aplicá-las (para operações de escrita).
delete_method	string (“clear” | “remove_rows”)	Não	Para operações DELETE: ‘clear’ preserva a estrutura de linhas, ‘remove_rows’ desloca os dados para cima.
spreadsheet_id	string	Sim	ID alfanumérico único da planilha, extraído da URL.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Localizar e substituir na planilha

GOOGLESHEETS_FIND_REPLACE

Localiza e substitui texto em uma planilha do Google. Casos de uso comuns: corrigir células com #ERRO!, atualizar valores, realizar substituições em massa de texto.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
find	string	Sim	O texto a localizar. Pode ser uma string literal ou padrão de expressão regular.
range	string	Não	String de intervalo em notação A1 para pesquisar. Mutuamente exclusivo com sheetId e allSheets.
replace	string	Sim	O texto para substituir as ocorrências encontradas.
sheetId	integer	Não	ID numérico da aba para pesquisar a aba inteira. Mutuamente exclusivo com sheetName, range e allSheets.
allSheets	boolean	Não	Se deve pesquisar em todas as abas da planilha.
matchCase	boolean	Não	Se a pesquisa deve ser case-sensitive.
sheetName	string	Não	Nome da aba a pesquisar.
endRowIndex	integer	Não	Linha final (base zero, exclusiva) do intervalo. Usado apenas com rangeSheetId.
rangeSheetId	integer	Não	ID numérico da aba para pesquisa baseada em GridRange. Necessário ao usar o parâmetro range com notação A1.
searchByRegex	boolean	Não	Se o texto de busca deve ser tratado como expressão regular.
spreadsheetId	string	Sim	ID da planilha a atualizar.
startRowIndex	integer	Não	Linha inicial (base zero, inclusiva) do intervalo.
endColumnIndex	integer	Não	Coluna final (base zero, exclusiva) do intervalo. Coluna A = 0.
includeFormulas	boolean	Não	Se células com fórmulas devem ser incluídas na pesquisa.
matchEntireCell	boolean	Não	Se deve corresponder apenas células que contêm o termo inteiro.
startColumnIndex	integer	Não	Coluna inicial (base zero, inclusiva) do intervalo. Coluna A = 0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Localizar worksheet por título (Descontinuada)

GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE

DESCONTINUADA: Use GetSpreadsheetInfo em vez desta. Localiza uma worksheet pelo título exato, case-sensitive, dentro de uma planilha do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets na URL.
worksheet_title	string	Sim	Título exato e case-sensitive da worksheet (nome da aba) a localizar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Formatar célula

GOOGLESHEETS_FORMAT_CELL

Aplica formatação de texto e fundo a um intervalo especificado em uma worksheet do Google Sheets.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
red	number	Não	Componente vermelho da cor de fundo (0.0–1.0).
blue	number	Não	Componente azul da cor de fundo (0.0–1.0).
bold	boolean	Não	Aplicar formatação negrito.
green	number	Não	Componente verde da cor de fundo (0.0–1.0).
range	string	Não	OPÇÃO 1: Intervalo de células em notação A1 (recomendado). Forneça este campo OU os quatro campos de índice abaixo, não ambos.
italic	boolean	Não	Aplicar formatação itálico.
fontSize	integer	Não	Tamanho da fonte em pontos.
underline	boolean	Não	Aplicar sublinhado.
sheet_name	string	Não	Nome da worksheet (ex.: ‘Sheet1’). Forneça este campo OU worksheet_id, não ambos.
worksheet_id	integer	Não	Identificador da worksheet. Padrão: 0 (primeira aba).
end_row_index	integer	Não	OPÇÃO 2: Índice base zero da linha APÓS a última linha (exclusivo).
strikethrough	boolean	Não	Aplicar tachado.
wrap_strategy	string (“OVERFLOW_CELL” | “LEGACY_WRAP” | “CLIP” | “WRAP”)	Não	Como o texto é quebrado dentro das células.
spreadsheet_id	string	Sim	Identificador da planilha do Google Sheets.
start_row_index	integer	Não	OPÇÃO 2: Índice base zero da linha (linha 1 = índice 0).
end_column_index	integer	Não	OPÇÃO 2: Índice base zero da coluna APÓS a última coluna (exclusivo).
start_column_index	integer	Não	OPÇÃO 2: Índice base zero da coluna (A = 0, B = 1, F = 5).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter valores da planilha em lote (Descontinuada)

GOOGLESHEETS_GET_BATCH_VALUES

DESCONTINUADA: Use GOOGLESHEETS_BATCH_GET em vez desta. Retorna um ou mais intervalos de valores de uma planilha em uma única requisição.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ranges	array	Sim	Intervalos em notação A1 ou R1C1 para recuperar valores.
spreadsheet_id	string	Sim	ID da planilha.
major_dimension	string (“DIMENSION_UNSPECIFIED” | “ROWS” | “COLUMNS”)	Não	Dimensão principal dos resultados.
value_render_option	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores devem ser renderizados.
date_time_render_option	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas devem ser representadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter regras de formatação condicional

GOOGLESHEETS_GET_CONDITIONAL_FORMAT_RULES

Lista as regras de formatação condicional de cada aba (ou de uma aba selecionada) em uma forma normalizada e fácil de editar.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	Filtro opcional: retorna regras apenas da aba com este sheetId numérico exato.
sheet_title	string	Não	Filtro opcional: retorna regras apenas da aba com este título exato.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.
exclude_tables_in_banded_ranges	boolean	Não	True se tabelas devem ser excluídas dos intervalos com faixas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter regras de validação de dados

GOOGLESHEETS_GET_DATA_VALIDATION_RULES

Extrai regras de validação de dados de uma planilha do Google Sheets. Use para entender listas dropdown, valores permitidos, fórmulas personalizadas ou outras restrições de validação para células.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ranges	array	Não	Lista opcional de intervalos A1 para escanear. Se omitido, toda(s) a(s) aba(s) será(ão) escaneada(s).
sheetId	integer	Não	ID opcional da aba para filtrar. Se omitido, todas as abas serão escaneadas.
sheetTitle	string	Não	Título opcional da aba para filtrar.
includeEmpty	boolean	Não	Se True, inclui células sem regras de validação. Padrão: False.
spreadsheetId	string	Sim	ID da planilha.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter nomes das abas

GOOGLESHEETS_GET_SHEET_NAMES

Lista todos os nomes de worksheets de uma planilha especificada, útil para descobrir abas antes de operações subsequentes.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
exclude_hidden	boolean	Não	Quando True, abas ocultas serão excluídas dos resultados.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter planilha por filtro de dados

GOOGLESHEETS_GET_SPREADSHEET_BY_DATA_FILTER

Retorna a planilha no ID fornecido, filtrada pelos filtros de dados especificados. Use para recuperar subconjuntos específicos de dados com base em critérios como notação A1, metadados de desenvolvedor ou intervalos de grade.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
dataFilters	array	Não	Os DataFilters usados para selecionar quais intervalos recuperar. Se vazio, retorna metadados completos da planilha.
spreadsheetId	string	Sim	ID da planilha.
includeGridData	boolean	Não	True se os dados da grade devem ser retornados.
excludeTablesInBandedRanges	boolean	Não	True se tabelas devem ser excluídas dos intervalos com faixas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter informações da planilha

GOOGLESHEETS_GET_SPREADSHEET_INFO

Recupera metadados de uma planilha do Google usando seu ID. Por padrão, retorna informações essenciais (ID, título, propriedades das abas). Use o parâmetro fields para metadados abrangentes ou campos específicos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Máscara de campo especificando quais campos retornar. Se não especificado, uma máscara padrão com campos comuns é aplicada. Use ’*’ para todos os metadados.
ranges	array	Não	Intervalos opcionais para recuperar da planilha em notação A1.
spreadsheet_id	string	Não	ID da planilha ou URL completa do Google Sheets. O ID é extraído automaticamente de URLs.
include_grid_data	boolean	Não	Se True, os dados da grade serão retornados.
exclude_tables_in_banded_ranges	boolean	Não	Se True, tabelas dentro de intervalos com faixas serão omitidas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter esquema da tabela

GOOGLESHEETS_GET_TABLE_SCHEMA

DESCONTINUADA: Use GOOGLESHEETS_GET_SHEET_NAMES e GOOGLESHEETS_GET_SPREADSHEET_INFO em vez desta. Obtém o esquema de uma tabela em uma planilha do Google, inferindo nomes de colunas, tipos e restrições por análise estatística de dados de amostra.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_name	string	Não	Nome da aba/tab se o table_name for ambíguo entre múltiplas abas.
table_name	string	Sim	Nome da tabela da resposta de LIST_TABLES ou nome visível da aba do Google Sheets. Use ‘auto’ para analisar a maior tabela.
sample_size	integer	Não	Número de linhas a amostrar para inferência de tipo.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Inserir dimensão no Google Sheet

GOOGLESHEETS_INSERT_DIMENSION

Insere novas linhas ou colunas em uma aba em um local especificado. Use quando precisar adicionar linhas ou colunas vazias dentro de uma aba do Google existente.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
spreadsheet_id	string	Sim	ID da planilha a atualizar.
response_ranges	array	Não	Limita os intervalos incluídos na resposta.
insert_dimension	object	Sim	Detalhes da requisição de inserção de dimensão.
response_include_grid_data	boolean	Não	True se dados da grade devem ser incluídos na resposta.
include_spreadsheet_in_response	boolean	Não	True se a planilha atualizada deve ser incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar gráficos no Google Sheets

GOOGLESHEETS_LIST_CHARTS

Lista todos os gráficos em uma planilha do Google Sheets em todas as abas, retornando chart_id, metadados da aba, tipo de gráfico, título e posição.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
chart_id	integer	Não	Filtro opcional por ID numérico do gráfico.
sheet_id	integer	Não	Filtro opcional por ID numérico da aba.
include_spec	boolean	Não	Quando True, inclui o dicionário ChartSpec completo para cada gráfico. Padrão: False.
spreadsheet_id	string	Sim	ID da planilha ou URL completa do Google Sheets.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar tabelas na planilha

GOOGLESHEETS_LIST_TABLES

DESCONTINUADA: Use GOOGLESHEETS_GET_SHEET_NAMES para descoberta de abas e GOOGLESHEETS_GET_SPREADSHEET_INFO para metadados completos. Lista todas as tabelas em uma planilha do Google, detectando padrões de dados por análise heurística.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
min_rows	integer	Não	Número mínimo de linhas de dados para considerar uma tabela válida.
min_columns	integer	Não	Número mínimo de colunas para considerar uma tabela válida.
min_confidence	number	Não	Pontuação mínima de confiança (0.0–1.0) para considerar uma tabela válida.
spreadsheet_id	string	Sim	ID real da planilha do Google (não um placeholder ou nome da planilha).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Buscar linha na planilha

GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW

Localiza a primeira linha em uma planilha do Google onde o conteúdo inteiro de uma célula corresponde exatamente à string de consulta, pesquisando dentro de um intervalo em notação A1 especificado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
query	string	Sim	Valor de texto exato a localizar; corresponde ao conteúdo inteiro de uma célula.
range	string	Não	Intervalo em notação A1 para pesquisar. Nomes de abas com espaços devem estar entre aspas simples.
case_sensitive	boolean	Não	Se True, a pesquisa é case-sensitive.
spreadsheet_id	string	Sim	Identificador da planilha do Google Sheets a pesquisar.
value_render_option	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores das células são renderizados nos dados da linha retornada.
normalize_whitespace	boolean	Não	Se True, remove espaços iniciais e finais dos valores de célula antes de comparar.
date_time_render_option	string	Não	Como datas e horas são representadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Mover ou redimensionar gráfico no Google Sheets

GOOGLESHEETS_MOVE_CHART

Move ou redimensiona um gráfico existente em uma planilha do Google Sheets. Suporta três modos de posicionamento: mover para uma nova aba, mover para uma aba existente ou reposicionar via coordenadas pixel.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
chart_id	integer	Sim	Identificador numérico único do gráfico a mover.
new_sheet	boolean	Não	Defina como True para mover o gráfico para uma nova aba. Mutuamente exclusivo com target_sheet_id e anchor_sheet_id.
width_pixels	integer	Não	Largura do gráfico em pixels. Válido apenas com anchor_sheet_id.
height_pixels	integer	Não	Altura do gráfico em pixels. Válido apenas com anchor_sheet_id.
spreadsheet_id	string	Sim	ID da planilha que contém o gráfico a mover.
anchor_sheet_id	integer	Não	ID numérico da aba onde ancorar o gráfico ao reposicionar por coordenadas.
offset_x_pixels	integer	Não	Deslocamento horizontal em pixels a partir da célula âncora.
offset_y_pixels	integer	Não	Deslocamento vertical em pixels a partir da célula âncora.
target_sheet_id	integer	Não	ID numérico de uma aba existente para mover o gráfico.
anchor_row_index	integer	Não	Índice base zero da linha da célula âncora para posicionamento via overlay.
anchor_column_index	integer	Não	Índice base zero da coluna da célula âncora para posicionamento via overlay.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Modificar regras de formatação condicional

GOOGLESHEETS_MUTATE_CONDITIONAL_FORMAT_RULES

Adiciona, atualiza, exclui ou reordena regras de formatação condicional em uma aba do Google Sheets. Suporta quatro operações: ADD (criar nova regra), UPDATE (substituir regra existente), DELETE (remover regra), MOVE (reordenar regras).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
rule	object	Não	Especificação da regra de formatação condicional.
index	integer	Não	Índice base zero para a operação. Obrigatório para UPDATE, DELETE, MOVE.
sheet_id	integer	Sim	Identificador numérico único da aba a modificar. Use GOOGLESHEETS_GET_SPREADSHEET_INFO para recuperar os valores de sheetId.
new_index	integer	Não	Índice de destino para a operação MOVE. Obrigatório quando a operação é MOVE.
operation	string (“ADD” | “UPDATE” | “DELETE” | “MOVE”)	Sim	Tipo de operação.
spreadsheet_id	string	Sim	ID da planilha que contém a aba a modificar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Consultar tabela da planilha

GOOGLESHEETS_QUERY_TABLE

DESCONTINUADA: Use GOOGLESHEETS_VALUES_GET / GOOGLESHEETS_BATCH_GET para leituras e GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW para busca/filtro de linhas. Executa consultas SELECT tipo SQL contra tabelas do Google Sheets. Suporta cláusulas WHERE, ORDER BY e LIMIT.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sql	string	Sim	Consulta SQL SELECT. O nome da tabela é o nome da aba/tab do Google Sheets. Use nomes de tabela entre aspas duplas se contiverem espaços ou forem numéricos.
spreadsheet_id	string	Sim	Identificador único de um arquivo nativo do Google Sheets.
include_formulas	boolean	Não	Se deve retornar o texto de fórmula em vez dos valores calculados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisar metadados do desenvolvedor

GOOGLESHEETS_SEARCH_DEVELOPER_METADATA

Pesquisa metadados do desenvolvedor em uma planilha com base em filtros.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
dataFilters	array	Sim	Os filtros de dados que descrevem os critérios para determinar quais entradas de DeveloperMetadata retornar.
spreadsheetId	string	Sim	ID da planilha para recuperar metadados.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisar planilhas

GOOGLESHEETS_SEARCH_SPREADSHEETS

Pesquisa planilhas do Google usando vários filtros incluindo nome, conteúdo, intervalos de datas e mais.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
query	string	Não	Consulta de pesquisa para filtrar planilhas. Para pesquisas avançadas, use a sintaxe de consulta do Google Drive. Deixe vazio para obter todas as planilhas.
order_by	string	Não	Ordem de classificação (lista separada por vírgulas). Campos válidos: createdTime, modifiedTime, name, etc.
page_token	string	Não	Token para recuperar a próxima página de resultados.
max_results	integer	Não	Número máximo de planilhas a retornar (1–1000). Padrão: 10.
search_type	string (“name” | “content” | “both”)	Não	Como pesquisar: ‘name’ pesquisa nomes de arquivos, ‘content’ usa busca em texto completo, ‘both’ pesquisa ambos.
starred_only	boolean	Não	Se deve retornar apenas planilhas marcadas com estrela.
created_after	string	Não	Retorna planilhas criadas após esta data em formato RFC 3339.
modified_after	string	Não	Retorna planilhas modificadas após esta data em formato RFC 3339.
shared_with_me	boolean	Não	Se deve retornar apenas planilhas compartilhadas com o usuário atual.
include_trashed	boolean	Não	Se deve incluir planilhas na lixeira.
include_shared_drives	boolean	Não	Se deve incluir planilhas de drives compartilhados. Padrão: True.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Definir filtro básico

GOOGLESHEETS_SET_BASIC_FILTER

Define um filtro básico em uma aba de uma planilha do Google. Use para filtrar ou ordenar dados dentro de um intervalo específico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
filter	object	Sim	O filtro a definir.
spreadsheetId	string	Sim	ID da planilha.
responseRanges	array	Não	Limita os intervalos incluídos na resposta.
responseIncludeGridData	boolean	Não	True se os dados da grade devem ser retornados.
includeSpreadsheetInResponse	boolean	Não	Determina se a planilha atualizada aparece na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Definir regra de validação de dados

GOOGLESHEETS_SET_DATA_VALIDATION_RULE

Define ou remove regras de validação de dados (incluindo dropdowns) em um intervalo no Google Sheets.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
mode	string (“SET” | “CLEAR”)	Sim	Modo de operação: ‘SET’ aplica uma regra de validação ao intervalo, ‘CLEAR’ remove qualquer validação existente.
strict	boolean	Não	Se deve rejeitar dados inválidos (True) ou mostrar um aviso (False). Padrão: True.
values	array	Não	Lista de valores permitidos para dropdown. Obrigatório quando validation_type='ONE_OF_LIST'.
formula	string	Não	Fórmula personalizada para validação. Obrigatório quando validation_type='CUSTOM_FORMULA'. Deve avaliar para TRUE/FALSE.
sheet_id	integer	Sim	ID numérico único da aba onde a regra de validação será aplicada.
end_row_index	integer	Sim	Índice de linha final (base zero, exclusivo) para o intervalo de validação.
input_message	string	Não	Mensagem opcional exibida ao usuário ao selecionar a célula.
show_custom_ui	boolean	Não	Se deve mostrar uma UI dropdown para validação baseada em lista.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.
source_range_a1	string	Não	Intervalo fonte em notação A1 para valores dropdown. Obrigatório quando validation_type='ONE_OF_RANGE'.
start_row_index	integer	Sim	Índice de linha inicial (base zero, inclusivo) para o intervalo de validação.
validation_type	string	Não	Tipo de regra de validação. Obrigatório quando mode='SET'.
condition_values	array	Não	Lista genérica de valores de condição para tipos de validação que exigem valores específicos.
end_column_index	integer	Sim	Índice de coluna final (base zero, exclusivo) para o intervalo de validação.
start_column_index	integer	Sim	Índice de coluna inicial (base zero, inclusivo) para o intervalo de validação.
filtered_rows_included	boolean	Não	Se a validação deve se aplicar a linhas ocultas por filtros.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar aba a partir de JSON

GOOGLESHEETS_SHEET_FROM_JSON

DESCONTINUADA: Use GOOGLESHEETS_CREATE_GOOGLE_SHEET1 + GOOGLESHEETS_UPDATE_VALUES_BATCH em vez desta. Cria uma nova planilha do Google e popula sua primeira worksheet a partir de sheet_json.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
title	string	Sim	Título desejado para a nova planilha do Google.
sheet_json	array	Sim	Lista de dicionários representando as linhas da aba. As chaves do primeiro item formam a linha de cabeçalho.
sheet_name	string	Sim	Nome para a primeira worksheet dentro da nova planilha.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Copiar aba para outra planilha

GOOGLESHEETS_SPREADSHEETS_SHEETS_COPY_TO

Copia uma única aba de uma planilha para outra planilha.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Sim	ID da aba a copiar.
spreadsheet_id	string	Sim	ID da planilha que contém a aba a copiar.
destination_spreadsheet_id	string	Sim	ID da planilha de destino para onde a aba será copiada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Acrescentar valores à planilha

GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND

Acrescenta valores a uma planilha. Use quando precisar adicionar novos dados ao final de uma tabela existente em uma aba do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
range	string	Sim	Intervalo em notação A1 usado para localizar uma tabela lógica. Novas linhas são acrescentadas após a última linha dessa tabela.
values	array	Sim	Array 2D de valores a acrescentar. Normalmente, cada lista interna é uma LINHA (majorDimension=ROWS).
spreadsheetId	string	Sim	ID da planilha (tipicamente 44 caracteres).
majorDimension	string (“ROWS” | “COLUMNS”)	Não	Como interpretar o array 2D de valores. Use ROWS para dados por linha (mais comum).
insertDataOption	string (“OVERWRITE” | “INSERT_ROWS”)	Não	Como os dados de entrada devem ser inseridos.
valueInputOption	string (“RAW” | “USER_ENTERED”)	Sim	Como os dados de entrada devem ser interpretados.
includeValuesInResponse	boolean	Não	Se a resposta deve incluir os valores acrescentados.
responseValueRenderOption	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores na resposta devem ser renderizados.
responseDateTimeRenderOption	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas na resposta devem ser renderizadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Limpar valores da planilha em lote

GOOGLESHEETS_SPREADSHEETS_VALUES_BATCH_CLEAR

Limpa um ou mais intervalos de valores de uma planilha. Use quando precisar remover dados de células ou intervalos específicos mantendo a formatação intacta.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ranges	array	Sim	Os intervalos a limpar em notação A1. Exemplos válidos: ‘Sheet1!A1:B2’, ‘A1:Z100’, ‘Sheet1’.
spreadsheet_id	string	Sim	ID da planilha a atualizar. Aceita ID diretamente ou URL completa do Google Sheets.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter valores da planilha em lote por filtro de dados

GOOGLESHEETS_SPREADSHEETS_VALUES_BATCH_GET_BY_DATA_FILTER

Retorna um ou mais intervalos de valores de uma planilha que correspondem aos filtros de dados especificados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
dataFilters	array	Sim	Array de objetos de filtro de dados para corresponder a intervalos de valores. Cada filtro pode especificar ‘a1Range’ ou ‘gridRange’.
spreadsheetId	string	Sim	ID da planilha para recuperar dados.
majorDimension	string (“ROWS” | “COLUMNS”)	Não	Dimensão principal que os resultados devem usar.
valueRenderOption	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores devem ser representados na saída.
dateTimeRenderOption	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas devem ser representadas na saída.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar gráfico no Google Sheets

GOOGLESHEETS_UPDATE_CHART

Atualiza a especificação de um gráfico existente em uma planilha do Google Sheets. Use para modificar propriedades como título, tipo de gráfico, intervalos de dados, cores ou eixos. Esta ação não altera a posição ou tamanho do gráfico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
chart_id	integer	Sim	Identificador numérico único do gráfico a atualizar.
chart_spec	object	Sim	O objeto ChartSpec completo que define a especificação atualizada do gráfico.
spreadsheet_id	string	Sim	ID da planilha que contém o gráfico a atualizar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar propriedades de dimensão (ocultar/exibir e redimensionar)

GOOGLESHEETS_UPDATE_DIMENSION_PROPERTIES

Oculta/exibe linhas ou colunas e define alturas de linhas ou larguras de colunas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
sheet_id	integer	Não	ID numérico da aba. sheet_id ou sheet_name deve ser fornecido.
dimension	string (“ROWS” | “COLUMNS”)	Sim	Se deve atualizar linhas ou colunas.
end_index	integer	Sim	Índice final (base zero, exclusivo) do intervalo de dimensão a atualizar.
pixel_size	integer	Não	Altura (para linhas) ou largura (para colunas) em pixels.
sheet_name	string	Não	Nome da aba. Se fornecido, é resolvido para o sheet_id numérico.
start_index	integer	Sim	Índice inicial (base zero, inclusivo) do intervalo de dimensão a atualizar.
hidden_by_user	boolean	Não	Se deve ocultar (True) ou exibir (False) as linhas/colunas especificadas.
spreadsheet_id	string	Sim	ID da planilha a atualizar.
response_ranges	array	Não	Limita os intervalos incluídos na resposta.
response_include_grid_data	boolean	Não	Se os dados da grade devem ser incluídos na resposta.
include_spreadsheet_in_response	boolean	Não	Se a planilha atualizada deve ser incluída na resposta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar propriedades da aba

GOOGLESHEETS_UPDATE_SHEET_PROPERTIES

Atualiza propriedades de uma aba (worksheet) dentro de uma planilha do Google, como título, índice, visibilidade, cor da aba ou propriedades da grade.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
spreadsheetId	string	Sim	ID da planilha que contém a aba a atualizar.
responseRanges	array	Não	Limita os intervalos incluídos na resposta.
updateSheetProperties	object	Sim	Detalhes das propriedades da aba a atualizar.
responseIncludeGridData	boolean	Não	True se os dados da grade devem ser retornados na resposta.
includeSpreadsheetInResponse	boolean	Não	Determina se a resposta deve incluir a planilha completa atualizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar propriedades da planilha

GOOGLESHEETS_UPDATE_SPREADSHEET_PROPERTIES

Atualiza propriedades no nível da planilha como título, locale, fuso horário ou configurações de recálculo automático. NOTA: Para atualizar propriedades de abas individuais, use GOOGLESHEETS_UPDATE_SHEET_PROPERTIES.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Sim	Máscara de campo especificando quais propriedades atualizar (separadas por vírgulas). Use ’*’ para atualizar todas as propriedades.
properties	object	Sim	Propriedades no nível da planilha a atualizar (ex.: título, locale, timeZone, autoRecalc).
spreadsheetId	string	Sim	ID da planilha a atualizar.
responseRanges	array	Não	Limita os intervalos incluídos na resposta.
responseIncludeGridData	boolean	Não	Determina se os dados da grade devem ser incluídos na resposta.
includeSpreadsheetInResponse	boolean	Não	Determina se a resposta deve incluir a planilha completa atualizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar valores da planilha em lote

GOOGLESHEETS_UPDATE_VALUES_BATCH

Define valores em um ou mais intervalos de uma planilha. Use quando precisar atualizar múltiplos intervalos em uma única operação para melhor desempenho.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
data	array	Sim	Os novos valores a aplicar à planilha. Cada ValueRange especifica um intervalo e os valores a escrever.
spreadsheet_id	string	Sim	ID da planilha a atualizar.
valueInputOption	string (“INPUT_VALUE_OPTION_UNSPECIFIED” | “RAW” | “USER_ENTERED”)	Sim	Como os dados de entrada devem ser interpretados.
includeValuesInResponse	boolean	Não	Se a resposta deve incluir os valores das células atualizadas.
responseValueRenderOption	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores na resposta devem ser renderizados.
responseDateTimeRenderOption	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas na resposta devem ser renderizadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Inserir ou atualizar linhas (Upsert)

GOOGLESHEETS_UPSERT_ROWS

Realiza upsert de linhas — atualiza linhas existentes por chave, acrescenta novas. Gerencia mapeamento de colunas e atualizações parciais automaticamente. Casos de uso: sincronização de CRM (corresponder ID do Lead), importação de transações (corresponder ID da Transação), atualização de estoque (corresponder SKU).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
rows	array	Sim	Array 2D de linhas de dados para upsert. Se headers NÃO for fornecido, a PRIMEIRA linha é tratada como cabeçalhos de coluna.
headers	array	Não	Lista de nomes de colunas para os dados. Serão correspondidos aos cabeçalhos da aba. Colunas não existentes serão adicionadas automaticamente.
keyColumn	string	Não	O NOME da coluna (texto do cabeçalho) a usar como identificador único para correspondência de linhas.
sheetName	string	Sim	Nome da aba dentro da planilha.
strictMode	boolean	Não	Quando True (padrão), retorna erro se uma linha tiver mais valores que cabeçalhos. Quando False, valores extras são truncados silenciosamente.
tableStart	string	Não	Célula onde a tabela começa (onde os cabeçalhos estão). Padrão: ‘A1’.
spreadsheetId	string	Sim	ID da planilha.
key_column_index	string	Não	Índice base zero da coluna a usar como identificador único. Alternativa a keyColumn.
normalization_message	string	Não	Campo interno para rastrear normalização de entrada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter valores da planilha

GOOGLESHEETS_VALUES_GET

Retorna um intervalo de valores de uma planilha. Use quando precisar ler dados de células ou intervalos específicos em uma aba do Google.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
range	string	Sim	Intervalo em notação A1 ou R1C1. Se o nome da aba contiver espaços ou caracteres especiais, envolva-o em aspas simples.
end_row	integer	Não	Número de linha base 1 para parar de ler (inclusivo). Use com start_row para paginação.
start_row	integer	Não	Número de linha base 1 para começar a ler (inclusivo). Use com end_row para paginação.
spreadsheet_id	string	Sim	Identificador único da planilha.
major_dimension	string (“DIMENSION_UNSPECIFIED” | “ROWS” | “COLUMNS”)	Não	Dimensão principal dos resultados.
value_render_option	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores devem ser renderizados na saída.
date_time_render_option	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas devem ser representadas na saída.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar valores da planilha

GOOGLESHEETS_VALUES_UPDATE

Define valores em um intervalo de uma planilha do Google. Use quando precisar atualizar ou sobrescrever valores de células existentes em um intervalo específico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
range	string	Sim	Intervalo em notação A1 para atualizar valores (ex.: ‘Sheet1!A1:C2’, ‘A1:D5’).
values	array	Sim	Os dados a escrever. É um array de arrays; o array externo representa todos os dados e cada array interno representa uma dimensão principal.
spreadsheet_id	string	Sim	Identificador único da planilha do Google Sheets.
major_dimension	string (“ROWS” | “COLUMNS”)	Não	Dimensão principal dos valores. ROWS (padrão): cada array interno é uma linha.
auto_expand_sheet	boolean	Não	Se True (padrão), expande automaticamente as dimensões da aba quando o intervalo alvo excede os limites da grade.
value_input_option	string (“RAW” | “USER_ENTERED”)	Sim	Como os dados de entrada devem ser interpretados.
include_values_in_response	boolean	Não	Se a resposta deve incluir os valores das células atualizadas.
response_value_render_option	string (“FORMATTED_VALUE” | “UNFORMATTED_VALUE” | “FORMULA”)	Não	Como os valores na resposta devem ser renderizados.
response_datetime_render_option	string (“SERIAL_NUMBER” | “FORMATTED_STRING”)	Não	Como datas e horas na resposta devem ser renderizadas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.