Executar estudos

Esta página mostra como iniciar, acompanhar e parar execuções pela API. Os arquivos produzidos estão em Arquivos de resultado. Autenticação, Operation e erros comuns estão na visão geral. Para escolher o que executar pela tela do Portal, veja Trilhas de estudos.

Uma execução pela API passa pelas mesmas validações, escolha de rodadas, processamento e publicação de resultados que uma execução iniciada pelo Portal ou por um agendamento.

Iniciar

POST /studies/{study_key}/executions (executions:write) exige Idempotency-Key. O corpo pode ser vazio, e então todas as rodadas são executadas:

curl -sS -X POST "$MYRIA_API/api/v1/studies/$STUDY_KEY/executions" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: executar-191-001" \
  -d '{"comment":"Teste parcial","selection":{"mode":"single","round_key":"minha-org-206"}}'

O corpo aceita só comment (texto de até 1.000 caracteres) e selection. selection tem dois campos, mode e round_key:

`mode`	O que executa	`round_key`
`all`	Todas as rodadas do estudo. É o padrão quando `selection` é omitida.	Não envie.
`single`	Só a rodada informada.	Obrigatório.
`from_round`	A rodada informada e as seguintes da mesma trilha.	Obrigatório.
`track`	Todas as rodadas da trilha da rodada informada, em qualquer posição.	Obrigatório.

from_round e track não incluem trilhas irmãs, mesmo que apareçam depois na ordem do estudo. Campos desconhecidos, modo inválido ou round_key ausente retornam 400 com execution_selection_invalid. A seleção faz parte do que a Idempotency-Key protege: a mesma chave não pode ser usada com outro modo ou outra rodada.

Repetir a mesma intenção enquanto a admissão está em andamento devolve a mesma Operation e preserva o processamento ativo. Se o processamento for interrompido, o servidor detecta a interrupção e retoma o mesmo pedido automaticamente.

A resposta é 202 Operation. Quando o pedido chega a succeeded, result.execution_id identifica a execução.

Antes de começar, o Myria confere:

que o estudo não tem outra execução em andamento (409 study_execution_active);
que as rodadas selecionadas estão prontas e, em single e from_round, que as rodadas anteriores fora da seleção já têm resultados válidos. Uma fonte compartilhada sem resultado não é executada automaticamente: o pedido é recusado;
que os executáveis e as licenças exigidos pelas rodadas selecionadas (NEWAVE, DECOMP, GEVAZP, DESSEM) existem e são válidos. Se faltar algum, o pedido termina em failed com execution_prerequisite_missing e nada é iniciado.

Depois de corrigir o problema, envie uma nova execução com outra Idempotency-Key. Um pedido anterior em attention_required não bloqueia uma nova execução.

No DESSEM, um dia só executa depois que o dia anterior da mesma trilha tiver resultados válidos. Ao executar a trilha inteira, o Myria espera o dia anterior terminar antes de preparar o seguinte.

Acompanhar

GET /studies/{study_key}/executions lista as execuções do estudo (paginação por cursor). GET /executions/{execution_id} devolve uma execução:

{
  "execution_id": "exec_0123456789abcdef0123456789abcdef",
  "study_key": "minha-org-191",
  "status": "running",
  "selection": {
    "requested": {"mode": "single", "round_key": "minha-org-206"},
    "resolved": [{"round_key": "minha-org-206", "order": 1}]
  },
  "legs": [
    {"leg_id": "leg_...", "round_key": "minha-org-206", "order": 1,
     "state": "running", "reason_code": null,
     "attempt": {"attempt_id": "attempt_...", "status": "running"}}
  ],
  "reason_codes": []
}

status vale running, succeeded, failed, cancelled ou attention_required. Cada etapa (legs) é uma rodada; o state da etapa vale pending, running, completed, nonconverged, failed, stopped ou skipped. reason_codes e reason_code explicam falhas e etapas puladas.

Se uma rodada for parada pelo painel, ela fica stopped e seus descendentes que ainda não iniciaram ficam skipped. As trilhas independentes continuam. Quando todas as etapas restantes terminam sem outra falha determinante, a execução passa a cancelled, preservando os resultados já concluídos.

resolved_deck_version é a versão da configuração usada e input_commit_sha, a versão dos arquivos de entrada lida na largada. Os dois ficam fixos durante a execução: uma alteração no estudo feita depois não muda o que está rodando.

attention_required indica que a execução precisa de análise, por exemplo porque um resultado obrigatório não foi coletado. Não trate esse estado como autorização para iniciar outra execução: consulte reason_codes e os arquivos de resultado.

Para ser avisado em vez de consultar, assine os eventos execution.* no webhook.

Parar

POST /executions/{execution_id}/stop (executions:write) para a execução inteira. Exige Idempotency-Key e não aceita corpo:

curl -sS -X POST "$MYRIA_API/api/v1/executions/$EXECUTION_ID/stop" \
  -H "Authorization: Bearer $MYRIA_TOKEN" \
  -H "Idempotency-Key: parar-exec-001"

A resposta é 202 Operation. Se já houver uma parada em andamento, a resposta é 409 stop_already_in_progress.

O Myria interrompe a execução no servidor e preserva os resultados já produzidos. Só quando isso é confirmado a execução termina com status: "cancelled"; por isso, ela pode ter um conjunto parcial de arquivos, ou nenhum, se ainda não tinha começado. cancellable: false no pedido de parada significa que ele não pode mais ser desfeito, não que a parada deixou de acontecer.

Iniciar​

Acompanhar​

Parar​

Iniciar

Acompanhar

Parar