Pipeline ETL

Zoho Integration Worker | JavaScript

Worker de sincronización de datos que extrae Zoho registros del creador, normaliza payloads y publica conjuntos de datos de informes estructurados

Contexto del problema, stack y tipo de sistema

Este worker resuelve un problema práctico de integración de datos: los registros operativos en Zoho Creator necesitan una extracción, normalización y sincronización confiables para los flujos de informes. El proyecto implementa una pipeline de integración de APIs con Node.js con mapeo estructurado y escrituras de datos seguras.

Alcance técnico

  • Stack: JavaScript, Node.js, API de Zoho Creator, Google Sheets API, GitHub Actions
  • Tipo de sistema: ETL pipeline, sistema de integración de APIs, sistema de automatización
  • Palabras clave en contexto: APIs con Node.js, automatización Zoho Deluge, automatización de backend

Los proyectos relacionados incluyen Google Auth Worker, Omie Integration Worker y SIGE Integration Worker. Ver páginas temáticas: Desarrollador Zoho Deluge y Proyectos de integración de APIs.

Documentación completa del proyecto

Zoho Integration Worker

Código fuente Portafolio Autor

Un servicio de trabajo Node.js que sincroniza datos de las aplicaciones Zoho Creator con Google Sheets para informes y análisis comerciales.

Descripción general

Este worker proporciona sincronización de datos automatizada entre las aplicaciones Zoho Creator y Google Sheets, lo que permite un flujo de datos fluido para las operaciones comerciales y las necesidades de generación de informes.

Arquitectura del sistema

graph TB
    A[Worker Google Auth] -->|Dispatch Event| B[Worker Zoho Integration]
    B --> C[API de Zoho Creator]
    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

Características

  • Zoho Integración del creador: Obtiene datos de Zoho aplicaciones e informes del creador
  • Sincronización de hojas de cálculo de Google: escribe datos procesados en Google Sheets
  • Mapeo de datos flexible: Admite asignación de campos personalizados mediante configuración JSON
  • Filtrado basado en fechas: Filtra registros según criterios de fecha específicos
  • Generación de informes: Admite sincronización de informes estándar y personalizada
  • Manejo seguro de datos: Toda la información confidencial está debidamente enmascarada y protegida

Arquitectura Técnica

Componentes

  • Cliente da API Zoho: Autentica y recupera datos del Zoho Creator
  • Integración de Google Sheets: escribe datos procesados en Google Sheets
  • Motor de procesamiento de datos: Asigna y transforma datos Zoho para compatibilidad con hojas de cálculo
  • Sincronización de informes: Maneja datos de informes estándar y personalizados
  • Registro seguro: Registra todas las operaciones con enmascaramiento de datos confidenciales

Flujo de datos

  1. Autenticación: Utiliza OAuth2 tokens de Google Auth Worker
  2. Obtención de datos: Recupera registros de Zoho Creator a través de API
  3. Procesamiento de datos: Asigna campos Zoho a columnas de hoja de cálculo usando la configuración JSON
  4. Filtrado de fechas: Filtra registros según los requisitos comerciales (por ejemplo, los datos de ayer)
  5. Actualización de hoja: agrega o sobrescribe datos en Google Sheets
  6. Informes de estado: Informa el estado de ejecución al sistema de monitoreo

Implementación de seguridad

Arquitectura de seguridad multicapa

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]

Funciones de seguridad

  • Seguridad OAuth: Utiliza autenticación OAuth2 tanto para Google como para APIs de Zoho
  • Seguridad de tokens: Los tokens OAuth se reciben de forma segura a través del envío del repositorio.
  • Enmascaramiento de datos: Toda la información confidencial está enmascarada en registros
  • Variables de entorno: Credenciales almacenadas de forma segura como variables de entorno
  • Permisos mínimos: Los flujos de trabajo GitHub Actions utilizan los permisos mínimos requeridos
  • Enmascaramiento secreto explícito: Todos los secretos están enmascarados explícitamente en los flujos de trabajo GitHub Actions usando ::add-mask::
  • Registro seguro: Personalizado secureLog La función garantiza que no se expongan datos confidenciales en los registros.
  • Prevención de inyección de fórmula en hoja de cálculo: Personalizado sanitize La función evita que se inyecten fórmulas maliciosas en Google Sheets

Seguridad del flujo de datos

sequenceDiagram
    participant Auth as Worker Google Auth
    participant GH as GitHub Actions
    participant Zoho as API de Zoho Creator
    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

Configuración

Variables de entorno requeridas

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 Secretos

Se deben configurar los siguientes secretos en el repositorio GitHub:

  • GOOGLE_TOKEN: OAuth token de acceso (proporcionado por Google Auth Worker)
  • ZOHO_CLIENT_ID: Zoho OAuth ID de cliente
  • ZOHO_CLIENT_SECRET: Zoho OAuth secreto del cliente
  • ZOHO_REFRESH_TOKEN: Zoho OAuth token de actualización
  • ZOHO_ACCOUNT_OWNER: Zoho identificador del propietario de la cuenta
  • ZOHO_APP_LINK_NAME: Zoho nombre del enlace de la aplicación
  • ZOHO_REPORT_LINK_NAME: Zoho nombre del enlace del informe
  • SPREADSHEET_ID: ID de hoja de cálculo de Google Sheets
  • SHEET_NAME: nombre de la hoja de destino dentro de la hoja de cálculo
  • COLUMN_MAPPING: Configuración JSON para mapeo de campos

Uso

Sincronización de datos estándar

El worker principal sincroniza los datos de Zoho Creator con Google Sheets:

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

Sincronización de informes

El worker de informes maneja la sincronización de datos de informes personalizados:

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

Configuración de mapeo de campos

el COLUMN_MAPPING La variable de entorno debe contener un objeto JSON que asigne campos Zoho a columnas de la hoja de cálculo:

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

Procesamiento de datos

El worker procesa los datos Zoho con la siguiente lógica:

  1. Autenticación: Se autentica con Zoho usando OAuth2
  2. Obtención de datos: Recupera registros de la aplicación y el informe Zoho especificados
  3. Filtrado de fechas: Filtra registros según los requisitos comerciales
  4. Mapeo de campo: Asigna campos Zoho a columnas de hoja de cálculo
  5. Transformación de datos: Maneja tipos de campos complejos (búsquedas, selección múltiple, etc.)
  6. Procesamiento por lotes: Envía datos en lotes para evitar límites de API

Funciones avanzadas

Manejo de campo complejo

El worker admite varios tipos de campos Zoho:

  • Campos de búsqueda: Extrae automáticamente los valores de visualización
  • Campos de selección múltiple: une múltiples valores con comas
  • Campos de fecha/hora: Formateado correctamente para compatibilidad con hojas de cálculo.
  • Campos de fórmula: Manejado como campos de datos regulares

Sincronización de informes

El worker de informes proporciona funciones adicionales:

  • Datos paginados: Maneja grandes conjuntos de datos con paginación
  • Informes personalizados: Admite informes personalizados Zoho
  • Sobrescritura de datos: Utiliza el método PUT para sobrescribir los datos existentes
  • Configuración flexible: Configuración separada para configuraciones específicas del informe

Funciones de optimización

  • Procesamiento por lotes: Usos append para la inserción de datos para minimizar el consumo de cuota de Google Sheets API
  • Control de paginación: Implementa paginación inteligente que rompe el ciclo si no se encuentran nuevos registros
  • Limitación de tasa: Incluye retrasos para respetar los límites de tarifas de API
  • Filtrado de fechas eficiente: Filtra datos en el nivla API para reducir la transferencia de datos.

Monitoreo y observabilidad

  • Registros de ejecución: Registro seguro con datos confidenciales enmascarados
  • Seguimiento de estado: Integración con el monitor de operaciones en la nube para el seguimiento del tiempo de actividad
  • Informe de errores: Manejo de errores estructurado con mensajes de error seguros
  • Métricas de rendimiento: Seguimiento de paginación y sincronización incorporado

Solución de problemas

Problemas comunes

  1. Errores de autenticación: Verifique las credenciales de OAuth tanto para Google como para Zoho
  2. API Límites de tarifa: El worker incluye retrasos para evitar la limitación de tarifas
  3. Mapeo de campo: Asegúrese de que COLUMN_MAPPING JSON esté formateado correctamente
  4. Filtrado de fechas: Verifique que los criterios de fecha coincidan con los requisitos comerciales
  5. Permisos de hoja: Verificar los permisos de Google Sheets API

Registros

Todos los registros de ejecución se procesan mediante funciones de registro seguras que:

  • Enmascarar información confidencial
  • Incluir marcas de tiempo y niveles de registro
  • Reportar al sistema de monitoreo

Puntos de integración

  • Google Auth Worker: Recibe OAuth tokens
  • API de Zoho Creator: Obtiene datos de aplicaciones e informes
  • Google Sheets API: escribe datos procesados
  • Monitor de operaciones en la nube: Estado de ejecución de informes

Licencia

Este proyecto tiene la licencia MIT (consulte la notas de licencia en el repositorio para más detalles.

Cumplimiento de seguridad

Esta implementación sigue las mejores prácticas de seguridad:

  • [OK] Arquitectura de confianza cero: Sin secretos ni credenciales codificados
  • [OK] Defensa en profundidad: Múltiples capas de controles de seguridad
  • [OK] Principio de privilegio mínimo: Permisos mínimos y tokens de corta duración.
  • [OK] Seguro por diseño: Seguridad integrada en la arquitectura desde cero
  • [OK] Repositorio público seguro: No se exponen datos confidenciales ni siquiera en repositorios públicos
  • [OK] Validación de entrada: Todos los datos externos están validados y desinfectados
  • [OK] Codificación de salida: Previene ataques de inyección en Google Sheets
  • [OK] Seguridad de APIs: Comunicación segura con Zoho y Google APIs

Contribuyendo

  1. Bifurcar el repositorio
  2. Crear una rama de características
  3. Haz tus cambios
  4. Agregue pruebas para sus cambios
  5. Enviar una solicitud de extracción

Soporte

Para soporte y preguntas, comuníquese con el equipo de desarrollo.

Autor

Patrick Araujo - Ingeniero Informático
GitHub: https://github.com/PkLavc

Portafolio: https://pklavc.com/projects/

Zoho Integration Worker - Pipeline segura de sincronización ETL desde Zoho Creator a Google Sheets.

GitHub Sponsors

Stack tecnológico

JavaScript
GitHub Actions
Google Sheets
Zoho Creator
Node.js

Proyectos backend relacionados e integraciones de APIs

Explore implementaciones vinculadas en las colecciones de automatización backend con Python, flujos de trabajo de APIs con Node.js y sistemas de integración de APIs.

Ver el código fuente

Abrir en GitHub