CLI y API: automatización verificable del laboratorio
La CLI permite consultar objetos y ejecuciones, y lanzar acciones autorizadas desde una terminal. Esta guía utiliza comandos y rutas presentes en su implementación actual. No presenta una especificación OpenAPI completa ni presupone que cualquier ruta interna sea un contrato público estable. Antes de automatizar contra otra versión, consulte su ayuda y las instrucciones distribuidas con el artefacto.
Preparación y autenticación
Abra Developer Tools, seleccione la distribución para su plataforma y compruebe versión, estado de firma y SHA-256. Calcule el hash del archivo descargado y compárelo con el publicado. Un nombre de archivo correcto no sustituye esa comprobación. Instale el paquete siguiendo sus instrucciones y utilice dova --version para identificar el cliente que ejecutará.
Cree una API key personal para el propósito del laboratorio y ejecute dova login --url con la URL autorizada de ese entorno. Por ejemplo:
dova login --url https://dova-lab.example.invalid
El host .invalid es deliberadamente ilustrativo y no ofrece un servicio: sustitúyalo por el host de laboratorio configurado por su organización. La CLI solicita la clave mediante una entrada interactiva. No la escriba en los ejemplos del manual ni la incorpore a una línea de comandos compartida. Compruebe la identidad y el tenant que informa el inicio de sesión antes de continuar.
La CLI conserva configuración de autenticación en el perfil local. Proteja ese perfil y no adjunte su archivo de configuración a incidencias. dova logout elimina la sesión local; la revocación de una API key en el servidor es una acción distinta. Si una clave ya no debe utilizarse en ningún equipo, revóquela desde la interfaz y revise las automatizaciones que dependían de ella.
Primera comprobación de sólo lectura
Estos comandos utilizan un Domain ilustrativo llamado Laboratorio; sustitúyalo por el espacio permitido:
dova status --output json
dova repository list --domain Laboratorio --output json
dova mapping list --name sample --limit 50 --output json
dova workflow list --status published --name sample --output json
dova run list --status failed,cancelled --sort createdAt --descending --output csv
Compare las consultas con Repository, Workflows y Monitor. Una lista vacía puede ser el resultado correcto de un filtro. Los nombres no garantizan unicidad: conserve los identificadores devueltos para las operaciones siguientes. El formato JSON facilita procesar campos explícitos; CSV resulta útil para una revisión tabular autorizada.
Rutas verificadas en el cliente
| Finalidad | Método y ruta usados por la CLI |
|---|---|
| Identidad actual | GET /api/session |
| Domains y Folders | GET /api/etl/domains |
| Mappings | GET /api/etl/mappings |
| Sessions | GET /api/etl/session-definitions |
| Workflows | GET /api/etl/orchestrations |
| Ejecuciones de Workflow | GET /api/etl/workflow-runs |
| Lanzar un Workflow | POST /api/etl/orchestrations/{id}/run |
El cliente envía autenticación Bearer y espera respuestas JSON. No suponga que todas las colecciones usan la misma clave: Workflows se obtiene como orchestrations, mientras que las ejecuciones se obtienen como runs. Para integración directa, confirme el esquema correspondiente y gestione rechazos y respuestas inesperadas; no transforme un error de autenticación en una lista vacía aparentemente válida.
Ejecutar una POC publicada
Las POC local de clientes y regional funcionan sin red. Para repetir sus reglas mediante un servidor, prepare primero definiciones publicadas, permisos y destinos exclusivos del laboratorio. Esta segunda fase sí comunica con el servicio y puede escribir salidas.
Para un Workflow con una fuente de archivo, la forma admitida es:
dova workflow run ID_WORKFLOW --input transform_workflows/inputs/customers.csv --wait --output json
En un Workflow con varias fuentes utilice opciones --source repetidas, con la forma TASK_ID:SOURCE_NODE_ID=FILE. Por ejemplo, reemplace ID_TAREA por el identificador real de la tarea que consume la Session:
dova workflow run ID_WORKFLOW --source ID_TAREA:source_txt=transform_workflows/inputs/transactions.txt --source ID_TAREA:source_xlsx=transform_workflows/inputs/customers.xlsx --wait --output json
No combine --input y --source. El cliente también admite --var CLAVE=VALOR y --param CLAVE=VALOR; sus valores deben corresponder al contrato del Workflow. Evite incluir secretos. Registre el identificador del intento, revise su estado final y compare el CSV generado con el oráculo. Que la terminal termine no basta para aceptar la calidad del resultado.
Espera, recuperación y cierre
--wait consulta la ejecución hasta un estado terminal. Existen límites configurables mediante --poll y --wait-timeout; un timeout del cliente no demuestra que el servidor haya cancelado el trabajo. Consulte de nuevo el identificador antes de decidir otra acción. Los comandos de cancelación, terminación, repetición y recuperación tienen efectos distintos y deben usarse conforme al estado y al alcance autorizado.
Conserve una evidencia mínima: versión del cliente, entorno, identificadores, parámetros no sensibles, estado y comparación de salida. Revise los permisos de los informes exportados. Termine la sesión local cuando corresponda y revoque claves temporales que hayan dejado de ser necesarias. Los ejemplos de esta guía describen contratos verificados en código; su ejecución contra un servicio requiere una comprobación separada y no se afirma realizada durante la preparación del manual.