Los conectores comunitarios de Google Data Studio permiten integrar fuentes de datos personalizadas en el entorno de visualización, ampliando su capacidad más allá de las integraciones nativas. Este guía práctica explica cómo construir un conector desde cero, basándose en la estructura oficial del repositorio de código abierto.

Estructura del Proyecto

El repositorio googledatastudio/community-connectors organiza los conectores de forma modular. Cada conector es un paquete idnependiente dentro del directorio connectors/, con su propio entorno y lógica de negocio.

community-connectors/
├── connectors/
│   └── custom-data-source/
│       ├── src/
│       │   ├── data-handler.js       # Lógica de obtención y transformación de datos
│       │   └── auth-manager.js       # Gestión de autenticación y tokens
│       ├── package.json              # Metadatos y scripts de Node.js
│       └── manifest.json             # Configuración del conector para Data Studio
├── test/
│   └── data-handler.test.js          # Pruebas unitarias
├── scripts/
│   └── build.js                      # Proceso de empaquetado
├── README.md
└── CONTRIBUTING.md

Claves de la estructura:

• connectors/: Contiene cada conector como un subproyecto independiente.
• src/: Almacena la lógica principal, dividida en módulos específicos.
• manifest.json: Archivo obligatorio que define metadatos, permisos y parámetros de configuración del conector.
• package.json: Define dependencias, scripts de desarrollo y versión del conector.

Implementación del Conector

El núcleo de cualquier conector es un archivo que exporta una clase que implementa la interfaz requerida por Data Studio. A diferencia de otros frameworks, no se hereda de una clase base explícita, sino que se define un objeto con funciones específicas que el entorno invoca automáticamente.

// src/data-handler.js

const fetchData = async (config) => {
  const { endpoint, apiKey } = config;
  const response = await fetch(`${endpoint}?api_key=${apiKey}`);
  return await response.json();
};

const getSchema = () => ({
  fields: [
    { id: 'date', name: 'Fecha', type: 'DATE' },
    { id: 'revenue', name: 'Ingresos', type: 'NUMBER' },
    { id: 'region', name: 'Región', type: 'TEXT' }
  ],
  primaryKeys: ['date', 'region']
});

const getData = async (request) => {
  const { config, fields } = request;
  const rawData = await fetchData(config);
  
  return rawData.map(row => 
    fields.map(field => ({
      fieldId: field.id,
      value: row[field.id]
    }))
  );
};

const getConfig = () => ({
  config: [
    {
      id: 'endpoint',
      name: 'Endpoint de la API',
      type: 'TEXT',
      helpText: 'URL base para las solicitudes de datos'
    },
    {
      id: 'apiKey',
      name: 'Clave de API',
      type: 'PASSWORD',
      helpText: 'Token de autenticación para acceder a la fuente'
    }
  ]
});

module.exports = {
  getSchema,
  getData,
  getConfig
};

Este archivo define tres funciones esenciales:

• getConfig(): Define los campos de configuración que el usuario debe completar en la interfaz de Data Studio.
• getSchema(): Describe la estructura de los datos (campos, tipos, claves primarias).
• getData(): Recupera y transforma los datos según la solicitud del usuario (filtros, fechas, campos seleccionados).

Configuración y Despliegue

El archivo package.json debe incluir al menos un script para ejecutar el conector localmente durante el desarrollo:

{
  "name": "custom-data-source",
  "version": "1.2.0",
  "main": "src/data-handler.js",
  "scripts": {
    "dev": "node --experimental-modules src/data-handler.js",
    "test": "jest"
  },
  "dependencies": {
    "node-fetch": "^3.3.0"
  },
  "devDependencies": {
    "jest": "^29.5.0"
  }
}

Además, se recomienda incluir un archivo manifest.json para describir metadatos del conector:

{
  "name": "Mi Fuente Personalizada",
  "description": "Conector para datos de una API externa",
  "version": "1.2.0",
  "author": "Equipo de Desarrollo",
  "supportUrl": "https://ejemplo.com/support",
  "iconUrl": "https://ejemplo.com/icon.png",
  "category": "API",
  "requiredScopes": ["https://www.googleapis.com/auth/userinfo.email"]
}

Este manifiesto es crucial para el registro del conector en la galería comunitaria de Data Studio. No se requiere un servidor externo para desarrollo; el conector se prueba localmente mediante la herramienta datastudio-connectors-cli o cargando el archivo ZIP generado directamente en la interfaz de Data Studio.

Las credenciales sensibles (como claves API) nunca deben codificarse en el código. En su lugar, se solicitan al usuario mediante getConfig() y se almacenan de forma segura en la sesión de Data Studio.