> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Sheets
> Ler, escrever e manipular dados de planilhas
## 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).