Autenticação e Configuração
A integração com o Google Sheets usa autenticação OAuth 2.0 por meio do Google Cloud Platform com a Sheets API ativada. Os agentes podem ler, escrever e manipular dados de planilhas programaticamente, permitindo fluxos de trabalho poderosos de automação de dados. Suporta contas pessoais do Google e contas empresariais do Google Workspace com planilhas compartilhadas.Escopos de API Necessários
- spreadsheets: Acesso completo para criar, ler, atualizar e excluir planilhas.
- spreadsheets.readonly: Acesso somente leitura para recuperação e análise de dados.
- drive: Acesso para listar e gerenciar planilhas no Google Drive.
- drive.file: Acesso apenas a arquivos criados ou abertos pelo aplicativo.
Operações Disponíveis
Com todas as permissões necessárias configuradas, o toolkit permite as seguintes operações:Operações de Leitura
- Ler Intervalo: Recuperar valores de células de um intervalo especificado (ex.: “Sheet1!A1:D10”). Suporta notação A1 e intervalos nomeados.
- Ler Múltiplos Intervalos: Leitura em lote de múltiplos intervalos não contíguos em uma única requisição.
- Obter Valor da Célula: Recuperar o valor de uma célula específica.
- Obter Linha: Ler a linha inteira pelo número da linha.
- Obter Coluna: Ler a coluna inteira pela letra da coluna.
- Encontrar Célula: Pesquisar um valor específico e retornar sua localização.
Operações de Escrita
- Escrever Intervalo: Atualizar valores em um intervalo especificado com dados de matriz 2D. Suporta entrada bruta ou formato inserido pelo usuário.
- Adicionar Linha: Adicionar nova(s) linha(s) ao final da planilha sem sobrescrever dados existentes.
- Inserir Linha: Inserir novas linhas em posições específicas, deslocando as linhas existentes para baixo.
- Atualizar Célula: Modificar o valor de uma célula com fórmula ou dados estáticos.
- Limpar Intervalo: Excluir conteúdo de um intervalo especificado preservando a formatação.
- Excluir Linha/Coluna: Remover linhas ou colunas inteiras da planilha.
Gerenciamento de Planilhas
- Criar Planilha: Criar nova Google Sheet com título personalizado e estrutura inicial de planilha.
- Copiar Planilha: Duplicar planilha existente com todos os dados e formatação.
- Obter Metadados da Planilha: Recuperar nomes das planilhas, dimensões, intervalos protegidos e propriedades.
- Atualizar Propriedades da Planilha: Modificar título, localidade, fuso horário e formato padrão.
Operações de Planilha
- Adicionar Planilha: Criar nova planilha (aba) dentro de uma planilha existente.
- Excluir Planilha: Remover planilha da planilha.
- Renomear Planilha: Alterar o nome/título da planilha.
- Copiar Planilha: Duplicar planilha na mesma planilha ou em outra planilha.
- Ocultar/Exibir Planilha: Controlar a visibilidade da planilha.
- Reordenar Planilhas: Alterar a ordem das abas na planilha.
Operações de Formatação
- Atualização em Lote: Aplicar múltiplas alterações de formatação em uma única chamada de API (cores, fontes, bordas, alinhamento).
- Definir Formato da Célula: Aplicar formato numérico, moeda, data, porcentagem ou formatos personalizados.
- Mesclar Células: Combinar múltiplas células em uma única célula.
- Desmesclar Células: Dividir células previamente mescladas.
- Definir Largura da Coluna: Ajustar larguras das colunas em pixels ou redimensionar automaticamente.
- Definir Altura da Linha: Modificar alturas das linhas para melhor layout.
- Congelar Linhas/Colunas: Bloquear linhas ou colunas de cabeçalho para navegação mais fácil.
Operações Avançadas
- Ordenar Intervalo: Ordenar dados por coluna(s) em ordem crescente ou decrescente.
- Filtrar Dados: Aplicar critérios de filtro para exibir subconjunto de dados.
- Criar Tabela Dinâmica: Gerar tabelas dinâmicas para análise de dados.
- Adicionar Gráfico: Inserir gráficos (barras, linhas, pizza, dispersão) com base em intervalos de dados.
- Criar Intervalo Nomeado: Definir intervalos nomeados para referência mais fácil.
- Validação de Dados: Definir listas suspensas, intervalos numéricos ou regras de validação personalizadas.
- Formatação Condicional: Aplicar formatação de células baseada em regras.
Opções de Configuração
- Opção de Entrada de Valores: Escolher entre BRUTO (preserva a entrada exata) ou INSERIDO_PELO_USUÁRIO (analisa como se digitado).
- Opção de Renderização de Valores: Controlar como os valores são retornados (VALOR_FORMATADO, VALOR_NÃO_FORMATADO, FÓRMULA).
- ID da Planilha Padrão: Definir a planilha padrão para operações para evitar a especificação repetida do ID.
- Opção de Renderização de Data/Hora: Escolher número serial ou string formatada para datas/horas.
- Dimensão: Especificar se as operações se aplicam a LINHAS ou COLUNAS.
Casos de Uso
- Relatórios Automatizados: Consultar banco de dados, processar resultados com Python, escrever relatórios formatados no Sheets com gráficos.
- Automação de Entrada de Dados: Extrair dados de e-mails, documentos ou formulários e preencher linhas da planilha.
- Dashboards em Tempo Real: Atualizar continuamente planilhas de métricas que alimentam dashboards de stakeholders.
- Gerenciamento de Inventário: Sincronizar dados de produtos entre sistemas ERP e planilhas colaborativas do Sheets.
- Acompanhamento de Orçamento: Agregar dados de despesas de múltiplas fontes em planilhas de orçamento consolidadas.
- Processamento de Respostas de Pesquisas: Coletar respostas de formulários, analisar com Python e escrever insights em planilhas de resumo.
- Relatórios de Status de Projetos: Puxar dados de tarefas do Jira/Asana, formatar e publicar em planilhas acessíveis aos stakeholders.
- Visualização de Pipeline de Vendas: Exportar dados de CRM para o Sheets com campos calculados e formatação condicional.
Melhores Práticas
- Usar ID da Planilha: Sempre referenciar pelo ID da planilha (da URL) em vez do nome para estabilidade.
- Operações em Lote: Combinar múltiplas atualizações em uma única chamada batchUpdate para melhorar o desempenho.
- Armazenar Metadados em Cache: Armazenar informações da estrutura da planilha para minimizar chamadas de API de metadados.
- Intervalos Nomeados: Usar intervalos nomeados para regiões de dados importantes para tornar o código mais maintainável.
- Adicionar vs Inserir: Usar adicionar para novos dados; é mais rápido e seguro que encontrar a última linha.
- Ler Grandes Conjuntos de Dados: Para planilhas >10.000 linhas, ler em blocos para evitar timeout e problemas de memória.
- Tratamento de Fórmulas: Ao escrever fórmulas, usar a opção de entrada de valor BRUTO e prefixar com ”=”.
Dicas de Desempenho
- Minimizar chamadas de API agrupando operações e lendo intervalos maiores de uma vez.
- Usar opções de renderização de valores apropriadas - VALOR_NÃO_FORMATADO é mais rápido quando a formatação não é necessária.
- Evitar operações excessivas de formatação, que são intensivas em recursos.
- Para grandes conjuntos de dados, considerar usar IMPORTRANGE no Sheets em vez de ler repetidamente via API.
Problemas Comuns e Soluções
- Permissão Negada: Verificar se a planilha está compartilhada com a service account do agente ou se o usuário concedeu acesso.
- Intervalo Inválido: Verificar a sintaxe da notação A1 (ex.: “Sheet1!A1:B10”). Incluir o nome da planilha para arquivos com múltiplas planilhas.
- Limite de Taxa Excedido: Implementar backoff exponencial. Considere usar operações em lote para reduzir o número de chamadas.
- Incompatibilidade de Tipo de Dados: Garantir que os tipos de dados correspondam ao formato esperado (números como números, não strings).