ETL Pipeline

Zoho Integration Worker | JavaScript

Worker de sincronização de dados que extrai registros do Zoho Creator, normaliza cargas e publica conjuntos de dados de relatórios estruturados

Contexto do problema, stack e tipo de sistema

Este worker resolve um problema prático de integração de dados: os registros operacionais no Zoho Creator precisam de extração, normalização e sincronização confiáveis para fluxos de relatórios. O projeto implementa um pipeline de integração de APIs em Node.js com mapeamento estruturado e gravação segura de dados.

Escopo Técnico

  • Stack: JavaScript, Node.js, Zoho Creator API, Google Sheets API, GitHub Actions
  • Tipo de sistema: ETL pipeline, sistema de integração de APIs, sistema de automação
  • Palavras-chave no contexto: APIs em Node.js, automação Zoho Deluge, automação de backend

Projetos relacionados incluem Google Auth Worker, Omie Integration Worker e SIGE Integration Worker. Veja páginas temáticas: Desenvolvedor Zoho Deluge e Projetos de Integração de APIs.

Documentação completa do projeto

Zoho Integration Worker

Código Fonte Portfólio Autor

Um serviço de trabalho Node.js que sincroniza dados de aplicativos Zoho Creator com o Google Sheets para relatórios e análises de negócios.

Visão geral

Este worker fornece sincronização automatizada de dados entre os aplicativos Zoho Creator e o Google Sheets, permitindo um fluxo de dados contínuo para operações comerciais e necessidades de relatórios.

Arquitetura do sistema

graph TB
    A[Worker Google Auth] -->|Dispatch Event| B[Worker Zoho Integration]
    B --> C[Zoho Creator API]
    B --> D[Google Sheets API]
    C --> E[Application Data]
    C --> F[Report Data]
    D --> G[Target Spreadsheet]
    B --> H[Data Processing Engine]
    H --> I[Field Mapping]
    H --> J[Date Filtering]
    H --> K[Batch Processing]
    
    L[GitHub Secrets] --> B
    M[Environment Variables] --> B
    N[Column Mapping JSON] --> I

Recursos

  • Zoho Integração do Criador: busca dados de aplicativos e relatórios do Zoho Creator
  • Sincronização do Google Sheets: grava dados processados no Google Sheets
  • Mapeamento de dados flexível: Suporta mapeamento de campos personalizados via configuração JSON
  • Filtragem baseada em data: Filtra registros com base em critérios de data específicos
  • Geração de Relatório: Suporta sincronização de relatórios padrão e personalizados
  • Tratamento seguro de dados: Todas as informações confidenciais são devidamente mascaradas e protegidas

Arquitetura Técnica

Componentes

  • Cliente da API Zoho: Autentica e busca dados do Zoho Creator
  • Integração com Google Sheets: grava dados processados no Google Sheets
  • Mecanismo de processamento de dados: mapeia e transforma dados Zoho para compatibilidade com planilhas
  • Sincronização de relatórios: Lida com dados de relatórios padrão e personalizados
  • Registro seguro: Registra todas as operações com mascaramento de dados confidenciais

Fluxo de dados

  1. Autenticação: Usa OAuth2 tokens de Google Auth Worker
  2. Busca de dados: Recupera registros do Zoho Creator via API
  3. Processamento de Dados: mapeia campos Zoho para colunas da planilha usando configuração JSON
  4. Filtragem de data: filtra registros com base nos requisitos de negócios (por exemplo, dados de ontem)
  5. Atualização de planilha: anexa ou substitui dados no Google Sheets
  6. Relatório de status: Reporta o status de execução ao sistema de monitoramento

Implementação de segurança

Arquitetura de segurança multicamadas

graph LR
    A[GitHub Secrets] --> B[Environment Variables]
    B --> C[OAuth Authentication]
    C --> D[API Communication]
    D --> E[Data Processing]
    E --> F[Google Sheets]
    
    G[Masking Functions] --> H[Log Protection]
    I[Sanitization] --> J[Input Validation]
    K[Formula Injection Prevention] --> L[Spreadsheet Security]
    M[Minimal Permissions] --> N[Attack Surface Reduction]

Recursos de segurança

  • OAuth Segurança: usa autenticação OAuth2 para APIs do Google e do Zoho
  • Segurança de token: OAuth tokens são recebidos com segurança por meio de envio de repositório
  • Mascaramento de dados: Todas as informações confidenciais são mascaradas em logs
  • Variáveis de ambiente: credenciais armazenadas com segurança como variáveis de ambiente
  • Permissões mínimas: fluxos de trabalho GitHub Actions usam permissões mínimas necessárias
  • Mascaramento secreto explícito: todos os segredos são explicitamente mascarados em fluxos de trabalho GitHub Actions usando ::add-mask::
  • Registro seguro: Personalizado secureLog função garante que nenhum dado confidencial seja exposto nos logs
  • Prevenção de injeção de fórmula em planilha: Personalizado sanitize função evita que fórmulas maliciosas sejam injetadas no Google Sheets

Segurança do Fluxo de Dados

sequenceDiagram
    participant Auth as Worker Google Auth
    participant GH as GitHub Actions
    participant Zoho as Zoho Creator API
    participant Sheets as Google Sheets
    participant Worker as Worker Zoho Integration
    
    Auth->>GH: Dispatch Event (masked token)
    GH->>Worker: Trigger Workflow
    Worker->>Zoho: Secure Authentication
    Zoho->>Worker: Application Data
    Worker->>Sheets: Processed Data (sanitized)
    Worker->>Sheets: Report Data (sanitized)
    Note over Worker,Sheets: All data is sanitized before writing

Configuração

Variáveis de ambiente necessárias

GOOGLE_TOKEN=oauth_access_token_from_google_auth_worker
ZOHO_CLIENT_ID=your_zoho_client_id
ZOHO_CLIENT_SECRET=your_zoho_client_secret
ZOHO_REFRESH_TOKEN=your_zoho_refresh_token
ZOHO_ACCOUNT_OWNER=your_zoho_account_owner
ZOHO_APP_LINK_NAME=your_zoho_app_link_name
ZOHO_REPORT_LINK_NAME=your_zoho_report_link_name
SPREADSHEET_ID=your_google_spreadsheet_id
SHEET_NAME=your_google_sheet_name
COLUMN_MAPPING=your_field_mapping_json

GitHub Segredos

Os seguintes segredos devem ser configurados no repositório GitHub:

  • GOOGLE_TOKEN: OAuth token de acesso (fornecido por Google Auth Worker)
  • ZOHO_CLIENT_ID: Zoho OAuth ID do cliente
  • ZOHO_CLIENT_SECRET: Zoho OAuth segredo do cliente
  • ZOHO_REFRESH_TOKEN: Zoho OAuth token de atualização
  • ZOHO_ACCOUNT_OWNER: Zoho identificador do proprietário da conta
  • ZOHO_APP_LINK_NAME: Zoho nome do link do aplicativo
  • ZOHO_REPORT_LINK_NAME: Zoho nome do link do relatório
  • SPREADSHEET_ID: ID da planilha do Google Sheets
  • SHEET_NAME: Nome da planilha de destino na planilha
  • COLUMN_MAPPING: configuração JSON para mapeamento de campo

Uso

Sincronização de dados padrão

O worker principal sincroniza dados do Zoho Creator com o Google Sheets:

{
  "event_type": "google_token_ready",
  "client_payload": {
    "token": "oauth_access_token"
  }
}

Sincronização de relatórios

O worker de relatório lida com a sincronização de dados de relatórios personalizados:

{
  "event_type": "report_token_ready",
  "client_payload": {
    "token": "oauth_access_token"
  }
}

Configuração de mapeamento de campo

O COLUMN_MAPPING A variável de ambiente deve conter um objeto JSON mapeando campos Zoho para colunas da planilha:

{
  "column_a": "zoho_field_1",
  "column_b": "zoho_field_2",
  "column_c": "zoho_field_3"
}

Processamento de Dados

O worker processa dados Zoho com a seguinte lógica:

  1. Autenticação: Autentica com Zoho usando OAuth2
  2. Busca de dados: recupera registros do aplicativo e relatório Zoho especificado
  3. Filtragem de data: Filtra registros com base nos requisitos de negócios
  4. Mapeamento de Campo: mapeia campos Zoho para colunas da planilha
  5. Transformação de dados: lida com tipos de campos complexos (pesquisas, seleção múltipla, etc.)
  6. Processamento em lote: Envia dados em lotes para evitar limites de API

Recursos avançados

Tratamento Complexo de Campos

O worker oferece suporte a vários tipos de campo Zoho:

  • Campos de pesquisa: Extrai automaticamente os valores de exibição
  • Campos de seleção múltipla: une vários valores com vírgulas
  • Campos de data/hora: formatado corretamente para compatibilidade com planilhas
  • Campos de Fórmula: Manipulado como campos de dados regulares

Sincronização de relatórios

O worker de relatório fornece funcionalidades adicionais:

  • Dados paginados: Lida com grandes conjuntos de dados com paginação
  • Relatórios personalizados: Suporta relatórios personalizados Zoho
  • Sobregravação de dados: Usa o método PUT para substituir os dados existentes
  • Configuração flexível: Configuração separada para configurações específicas de relatório

Recursos de otimização

  • Processamento em lote: Usos append para inserção de dados para minimizar o consumo de cota do Google Sheets API
  • Controle de paginação: Implementa paginação inteligente que interrompe o loop se nenhum novo registro for encontrado
  • Limitação de taxa: Inclui atrasos para respeitar os limites de taxa API
  • Filtragem eficiente de datas: Filtra dados no nívla API para reduzir a transferência de dados

Monitoramento e Observabilidade

  • Registros de execução: Registro seguro com dados confidenciais mascarados
  • Rastreamento de status: Integração com monitor de operações em nuvem para rastreamento de tempo de atividade
  • Relatório de erros: Tratamento estruturado de erros com mensagens de erro seguras
  • Métricas de desempenho: Tempo integrado e rastreamento de paginação

Solução de problemas

Problemas comuns

  1. Erros de autenticação: verifique as credenciais de OAuth para Google e Zoho
  2. API Limites de taxa: O worker inclui atrasos para evitar limitação de taxa
  3. Mapeamento de Campo: Certifique-se de que COLUMN_MAPPING JSON esteja formatado corretamente
  4. Filtragem de data: Verifique se os critérios de data correspondem aos requisitos de negócios
  5. Permissões de planilha: Verifique as permissões do Google Sheets API

Registros

Todos os logs de execução são processados por meio de funções de log seguras que:

  • Mascarar informações confidenciais
  • Incluir carimbos de data/hora e níveis de log
  • Reportar ao sistema de monitoramento

Pontos de Integração

  • Google Auth Worker: Recebe tokens OAuth
  • Zoho Creator API: busca dados de aplicativos e relatórios
  • Google Sheets API: Grava dados processados
  • Monitor de operações em nuvem: relata o status de execução

Licença

Este projeto está licenciado sob a licença MIT - veja o notas de licença no repositório para obter detalhes.

Conformidade de segurança

Esta implementação segue as práticas recomendadas de segurança:

  • [OK] Arquitetura de confiança zero: Sem segredos ou credenciais codificados
  • [OK] Defesa em profundidade: Múltiplas camadas de controles de segurança
  • [OK] Princípio do Menor Privilégio: Permissões mínimas e tokens de curta duração
  • [OK] Seguro por Design: Segurança integrada na arquitetura desde o início
  • [OK] Repositório Público Seguro: Nenhum dado confidencial exposto mesmo em repositórios públicos
  • [OK] Validação de entrada: Todos os dados externos são validados e higienizados
  • [OK] Codificação de saída: evita ataques de injeção no Google Sheets
  • [OK] API Segurança: Comunicação segura com Zoho e Google APIs

Contribuindo

  1. Bifurque o repositório
  2. Crie uma ramificação de recursos
  3. Faça suas alterações
  4. Adicione testes para suas alterações
  5. Envie uma solicitação pull

Suporte

Para suporte e dúvidas, entre em contato com a equipe de desenvolvimento.

Autor

Patrick Araujo - Engenheiro de Computação
GitHub: https://github.com/PkLavc

Portfólio: https://pklavc.com/projects/

Zoho Integration Worker - Pipeline de sincronização ETL seguro do Zoho Creator para o Google Sheets.

GitHub Sponsors

Stack tecnológica

JavaScript
GitHub Actions
Google Sheets
Zoho Creator
Node.js

Projetos de backend relacionados e integrações de APIs

Explore implementações vinculadas nas coleções de automação backend em Python, fluxos de trabalho de APIs em Node.js e sistemas de integração de APIs.

Veja o código-fonte

Abrir em GitHub