Orígenes Singer

Descripción

Un origen Singer permite a PlaidCloud extraer datos de un amplio catálogo de aplicaciones SaaS, API y bases de datos (como Stripe, GitHub, Slack y BigQuery) mediante taps de Singer. Cada tap es un conector para un origen; usted elige el tap al crear la conexión, y PlaidCloud muestra los campos de configuración que ese tap necesita.

Usar un origen Singer tiene dos partes:

1. Una conexión de origen Singer contiene la elección del tap y su configuración (token de API, ID de cuenta, fecha de inicio, etc.).
2. Un paso de flujo de trabajo Import Singer Source detecta los flujos disponibles del tap, le permite elegir cuáles importar y dónde se carga cada uno, y ejecuta la extracción.

Nota

PlaidCloud incluye un catálogo seleccionado de taps con licencias permisivas. Los campos de configuración exactos varían de un tap a otro: el formulario de la conexión se genera a partir del tap que seleccione.

Una conexión de origen Singer contiene el tap y su configuración; el paso Import Singer Source detecta los flujos del tap y carga en tablas del proyecto los que usted elige.

Antes de comenzar

Necesitará las credenciales del sistema de origen (por ejemplo, un token de acceso personal de GitHub o una clave de API de Stripe), así como el proyecto y el flujo de trabajo donde desea que se carguen los datos.

Crear una conexión de origen Singer

1. Abra Tools > Connections.
2. Haga clic en Nueva conexión y elija Origen Singer.
3. Asigne a la conexión un Nombre (por ejemplo, GitHub (prod)).
4. Elija un Tap en la lista desplegable. El formulario que aparece debajo se reconstruye para mostrar los campos de ese tap. Consulte Orígenes Singer para ver el catálogo completo y un enlace a la documentación de configuración de cada origen.
5. Complete los campos de configuración del tap y haga clic en Crear.

Tipos de campos de configuración

Los campos dependen del tap, y cada uno se presenta de acuerdo con el valor que el tap espera:

• Texto: un valor de una sola línea (por ejemplo, un ID de cuenta o una fecha de inicio).

• Contraseña: un secreto, como un token de API o una clave. Los secretos son de solo escritura: no se muestran al editar la conexión, y dejar uno en blanco al guardar conserva el valor almacenado.

• Número: un entero o decimal (por ejemplo, un puerto o un tamaño de página).

• Lista: una entrada por línea (por ejemplo, una lista de repositorios o de ID de proyecto).

• JSON: un valor estructurado introducido como JSON, que se usa cuando un tap espera un objeto o una matriz de objetos. Por ejemplo, las definiciones de archivos de un tap de CSV:

  [
    { "entity": "orders", "path": "/data/orders.csv", "keys": ["id"] }
  ]

• Casilla de verificación: una opción de activado o desactivado.

Los campos obligatorios están marcados, y el formulario los valida (incluido que los campos JSON y numéricos estén bien formados) antes de guardar.

Importar flujos a un flujo de trabajo

1. Abra el flujo de trabajo y vaya a la pestaña Analyze Steps.
2. Agregue un paso y elija Importar: origen Singer como tipo. El editor se abre con una pestaña Origen y una pestaña Flujos.
3. En la pestaña Origen:
   • Elija la Conexión (su conexión de origen Singer).
   • Elija un Modo de sincronización: Tabla completa (reemplaza en cada ejecución), Incremental (anexa datos nuevos) o Upsert (combinar por clave).
   • Haga clic en Detectar flujos. La detección se ejecuta en el ejecutor y puede tardar hasta unos tres minutos la primera vez; el estado muestra cuántos flujos se encontraron.
4. En la pestaña Flujos, verá una fila por cada flujo detectado. Para cada flujo que desee:
   • Abra su panel Flujo y marque Importar este flujo.
   • Elija una Tabla de destino donde se cargarán los datos del flujo.
   • Si el modo de sincronización es Upsert, establezca las Columnas clave del flujo, un nombre de columna por línea. El campo toma de forma predeterminada la clave primaria declarada del tap; anúlela para combinar por otras columnas. Todo flujo importado necesita al menos una columna clave cuando el modo es Upsert.
5. Guarde el paso y ejecútelo como parte del flujo de trabajo (o por sí solo).

Precaución

Los flujos que seleccione son el conjunto guardado. Para cambiar qué flujos se importan, haga clic de nuevo en Detectar flujos: los flujos que reaparecen conservan la tabla de destino y la selección que ya estableció.

Modos de sincronización

• Tabla completa (reemplaza en cada ejecución) vuelve a extraer todo el flujo en cada ejecución y reemplaza la tabla de destino. Úselo con orígenes pequeños o que se actualizan por completo.
• Incremental (anexa datos nuevos) extrae solo las filas nuevas desde la última ejecución y las anexa, reanudando desde donde terminó la ejecución anterior. Funciona solo con flujos que el tap puede sincronizar de forma incremental, es decir, los que exponen una clave de replicación (como una marca de tiempo de actualización o un ID incremental). Si elige incremental y un flujo seleccionado no tiene clave de replicación, el paso le pide que cambie ese flujo a tabla completa o que lo deseleccione.
• Upsert (combinar por clave) vuelve a extraer todo el flujo en cada ejecución y luego lo combina con el destino por las Columnas clave del flujo: las filas cuya clave coincide con una fila existente se actualizan en su lugar, y las filas con una clave nueva se insertan. Las filas existentes que no están en esta ejecución se conservan. Úselo para mantener una tabla sincronizada con un origen cuyos registros cambian con el tiempo, sin los duplicados que crearía una anexión ni la reconstrucción completa que haría un reemplazo. La tabla de destino se crea en la primera ejecución, por lo que el primer upsert inserta todas las filas.

Nota

El avance incremental se registra por paso. La primera ejecución incremental extrae todo; las posteriores toman solo las filas nuevas.

Nota

Upsert vuelve a extraer el flujo completo en cada ejecución (no usa una clave de replicación), por lo que resulta adecuado para orígenes donde se actualizan filas existentes y desea una fila por clave. Establezca las Columnas clave de cada flujo en la pestaña Flujos; de forma predeterminada son la clave primaria declarada del tap.

Precaución

Elija columnas clave que estén siempre presentes. Upsert hace coincidir las filas por el valor exacto de la clave, y una clave vacía (nula) nunca coincide con otra, por lo que las filas con clave nula siempre se insertan en lugar de combinarse y pueden acumularse a lo largo de las ejecuciones.

Cómo se manejan las credenciales

El paso almacena una referencia a la conexión, no una copia de sus credenciales. Cada ejecución lee las credenciales actuales de la conexión en el momento de ejecutarse. Así, cuando rota un token o una clave, la actualiza una vez en la conexión y todos los pasos que la usan toman el nuevo valor en su siguiente ejecución: no hay nada que actualizar en cada paso.

La extracción se ejecuta en un trabajo aislado que recibe únicamente la configuración propia del tap; no tiene acceso a otras conexiones ni a los servicios internos de PlaidCloud.

Temas relacionados

• Catálogo de orígenes Singer: todos los orígenes disponibles y su documentación de configuración
• Referencia del paso Import Singer Source
• Conexiones