CLI e API: consultar e automatizar com contexto explícito

A CLI permite consultar objetos e execuções e realizar ações autorizadas pelo terminal. Esta guia usa os comandos e caminhos do cliente distribuído, sem apresentar todos os endpoints internos como uma API pública universal. A versão da CLI é independente da versão 22.0.5 da plataforma; confira a versão e a ajuda do artefato instalado antes de automatizar.

Preparação e autenticação

Abra Developer Tools, escolha a distribuição da sua plataforma e confira versão, estado de assinatura e SHA-256. Calcule o hash do arquivo baixado e compare com o publicado. Um nome de arquivo correto não substitui a verificação. Instale conforme as instruções do pacote e execute dova --version.

Crie uma API key pessoal para o laboratório e informe a URL autorizada do ambiente:

dova login --url https://dova-lab.example.invalid

O domínio .invalid é propositalmente ilustrativo e não oferece serviço. Substitua-o pelo host de laboratório da organização. A CLI solicita a chave em uma entrada interativa; não a coloque na linha de comando, em exemplos ou histórico compartilhado. Confira a identidade e o tenant retornados antes de continuar.

A configuração autenticada fica no perfil local. Proteja esse perfil e não anexe seu conteúdo a chamados. dova logout remove o login local; revogar a API key no servidor é outra ação. Para impedir uso em qualquer computador, revogue a chave pela interface e revise as automações dependentes.

Primeira verificação somente de leitura

Nos exemplos, Laboratorio é um Domain ilustrativo. Substitua pelo espaço autorizado:

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 os resultados com Repository, Workflows e Monitor. Uma lista vazia pode ser correta para os filtros. Nomes não são necessariamente únicos; use os identificadores retornados nas ações seguintes. JSON facilita processar campos explícitos e CSV permite revisão tabular autorizada.

Caminhos usados pelo cliente

O cliente usa autenticação Bearer e espera JSON. As coleções não têm uma chave universal: Workflows usa orchestrations e execuções usa runs. Em uma integração direta, valide o esquema, a autorização e os erros esperados. Não converta uma falha de autenticação em lista vazia aparentemente válida. Uma API key continua sujeita ao tenant, papel e permissões do proprietário.

Executar um laboratório publicado

Os laboratórios de clientes e regional também têm uma verificação local histórica sem rede. Executar as regras pelo servidor é outra fase: prepare definições publicadas, permissões e destinos exclusivos. Essa fase comunica com o serviço e pode gravar saídas.

Para um Workflow com uma fonte de arquivo:

dova workflow run ID_WORKFLOW --input transform_workflows/inputs/customers.csv --wait --output json

Em várias fontes, repita --source no formato TASK_ID:SOURCE_NODE_ID=FILE. Use os identificadores reais da tarefa e dos nós:

dova workflow run ID_WORKFLOW --source ID_TAREFA:source_txt=transform_workflows/inputs/transactions.txt --source ID_TAREFA:source_xlsx=transform_workflows/inputs/customers.xlsx --wait --output json

Não combine --input e --source. O cliente também admite --var CHAVE=VALOR e --param CHAVE=VALOR; respeite tipos e definições permitidos pelo Workflow. Não inclua segredos. Registre o intento, confira o estado terminal e compare o CSV real com o oráculo; o término do comando não comprova qualidade dos dados.

Espera, recuperação e encerramento

--wait acompanha o intento até um estado terminal. --poll e --wait-timeout controlam a espera do cliente. Um timeout não prova que o servidor cancelou o trabalho; consulte novamente o mesmo identificador antes de iniciar outro. Cancelar, terminar, repetir e recuperar têm efeitos distintos e dependem do estado e das permissões.

Guarde versão do cliente, ambiente, identificadores, parâmetros não sensíveis, estado e comparação de saída. Proteja relatórios exportados. Encerre o login local quando apropriado e revogue chaves temporárias. Estes exemplos descrevem contratos do cliente; não significam que execuções contra um serviço tenham sido realizadas durante a preparação do manual.