Operações longas na API: a resposta 202, o action_id e acompanhar o resultado

A resposta curta: as operações que demoram respondem logo 202 com um action_id, porque o trabalho continua depois da resposta. Não repita o pedido: acompanhe o resultado com GET /v1/actions/{id} até o estado ser done ou failed.

Que operações respondem 202

Operação	O que demora
Registar, renovar e transferir domínios	O trabalho continua depois da resposta. Algumas extensões, incluindo o .mz, são tratadas manualmente e demoram mais.
Ligar, desligar e reiniciar um VPS	A acção entra em fila. Ligar costuma demorar cerca de 2 minutos, e desligar cerca de 6.
Comprar um produto extra	A acção acaba com o pagamento; a entrega acompanha-se à parte.

Os estados de uma acção

Estado	O que quer dizer
queued	Na fila, à espera de começar.
running	A correr.
done	Terminou bem.
failed	Falhou. A razão vem em result.

curl https://api.mozout.com/v1/actions/0f8fad5b-d9cb-469f-a165-70867728950e \
-H "Authorization: Bearer $RLX_API_KEY"

A resposta traz o id, o tipo, o alvo (por exemplo, o domínio), o status, o result e as horas de criação e de actualização. Só se vêem as acções da própria conta.

Como acompanhar sem gastar pedidos

1	Guarde o action_id assim que receber o 202, junto da operação que o originou.

2	Consulte com calma. Um pedido a cada poucos segundos chega; ciclos muito rápidos só gastam os limites de pedidos.

3	Pare quando o estado for done ou failed, e leia o result.

4	Confirme o efeito final numa leitura normal: o domínio em GET /v1/domains/{domain}, o servidor em GET /v1/servers/{id}, o extra em GET /v1/extras/{id} com o extra_id da resposta.

Repetir o pedido em vez de acompanhar não acelera nada, e num servidor dá 409 action_in_progress, porque cada servidor faz uma acção de cada vez (o action_id em curso vem em details). Nas compras, use sempre a Idempotency-Key, para que uma repetição nunca compre duas vezes.

Particularidades dos servidores

Caso	O que acontece
Quem pode consultar	Só a chave que pediu a acção.
Frescura do estado	O estado vem de uma cópia com até 20 segundos e conta para o limite de leituras da conta. Passado esse limite, a acção continua running até à leitura seguinte.
Sem confirmação a tempo	failed com timed_out em result.reason. Veja nesse caso o estado do servidor.
O servidor deixou de estar disponível	failed com server_gone.

Porque é que a resposta não traz logo o resultado? Porque algumas tarefas dependem de outros sistemas e levam minutos. É a diferença entre uma resposta síncrona e assíncrona, explicada em síncrono ou assíncrono.

Quer ver uma acção a correr sem risco? Faça o pedido com uma chave Sandbox e acompanhe-o na documentação, a partir da página da API.

Ver a página da API

VEJA TAMBÉM

Síncrono ou assíncrono: porque a confirmação de um pagamento ou de um SMS chega depois

Idempotency-Key na nossa API: repetir uma compra, um pagamento ou um pedido sem o fazer duas vezes

Limites de pedidos da API: por chave, por conta e por tarefa, os cabeçalhos e o que fazer num 429

Domínios pela API: consultar um nome, registar, renovar e transferir com o saldo

Controlar um VPS pela API: ligar, desligar, reiniciar, senha de root, reinstalar e cópias

Webhook ou consulta periódica: como um sistema fica a saber que algo mudou noutro

PRODUTO RECOMENDADO

Hospedagem de sites com cPanel

Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde $6.60/mês (plano de 3 anos, com cupão)

Ver planos

Categorias

Categorias