POST /v1/sync/task.
200, com a tarefa em QUEUED:
Ciclo de vida
Status
Uma tarefa que encontra uma falha temporária volta para
QUEUED e é executada de novo. Ela só termina em FAILED depois de esgotar as novas tentativas, então uma passagem de PROCESSING para QUEUED é normal.
O polling omite response até a tarefa chegar a um estado final. Uma tarefa com falha traz, em vez disso, uma string error no nível superior:
Créditos no envio e no polling
Preços, reservas e limites estão em Créditos e limites.
Tempo de processamento
task.latencyMs é o tempo que o motor levou: da primeira retirada por um worker até o resultado final, em milissegundos, sem a espera na fila. Se uma falha transitória devolve a tarefa à fila, a contagem continua a partir dessa primeira retirada. É null na resposta de envio e enquanto a tarefa está QUEUED ou PROCESSING, e um número no polling final e no webhook. O cabeçalho X-Latency-Ms mede outra coisa: o tempo que este servidor gastou nessa única requisição HTTP.
Prioridade
priority aceita de 1 a 10 e o padrão é 1. Valores fora desse intervalo são ajustados ao limite, não rejeitados. O valor é devolvido nos metadados da tarefa.
Retenção
Você pode consultar uma tarefa finalizada por 24 horas depois que ela termina. Depois disso,GET /v1/async/task/{id} retorna 404 RESOURCE_NOT_FOUND, a mesma resposta de um id desconhecido ou de uma tarefa de outra conta. Tarefas QUEUED e PROCESSING continuam visíveis, não importa a idade.
A janela de 24 horas também vale para os corpos de resultado em GET /v1/batches/{id}/items e nas leituras de grades. O idempotencyKey de uma tarefa continua reservado por mais tempo, por pelo menos 30 dias depois da solicitação (veja Idempotência). As novas tentativas automáticas de webhook seguem seu próprio cronograma, independente dessa janela.
Esperar o resultado em uma só requisição
POST /v1/sync/task aceita o mesmo corpo e mantém a requisição aberta até a tarefa terminar, por no máximo 290 segundos. A resposta é então 200 com o mesmo corpo do polling da tarefa, inclusive para uma tarefa que falhou.
Os mecanismos de resposta demoram mais que as tarefas de SERP e Search. Mantenha a requisição aberta conforme o tipo de mecanismo que você chama, como agrupado no catálogo de mecanismos, e defina o timeout do seu cliente HTTP alguns segundos acima:
- Uma tarefa que não terminou quando a espera acaba é respondida com
202, a tarefa eLocation: /v1/async/task/{id}. Ela continua rodando e é cobrada normalmente, então faça polling desse endereço ou receba o webhook. Um202também pode vir na hora enquanto o serviço mantém muitas requisições abertas. - Envie
Prefer: wait=<segundos>para manter a requisição por menos de 290 segundos. Fique abaixo do timeout do seu cliente HTTP, para receber o id da tarefa antes que ele desista. - Envie um
idempotencyKey. Enviar a mesma chave de novo responde com a tarefa que a detém, então você pode repetir uma requisição que expirou do seu lado sem executar a tarefa duas vezes. - Com
Accept: text/htmlepayload.include.html: true, uma tarefa concluída é respondida com a página salva emtext/html, eX-Task-Idtraz o id da tarefa. Uma tarefa que falhou, ou cuja página não pôde ser salva, é respondida com406e o corpo JSON.
Webhook ou polling
Prefira webhooks. Use o polling para recuperar o que você não recebeu.
Um cliente robusto faz os dois: recebe o webhook como caminho rápido e consulta por polling qualquer tarefa de que não teve notícia, com folga dentro da janela de 24 horas.
Próximos passos
Webhooks
Payload, assinaturas e novas tentativas.
Lotes e grades
Envie até 10.000 tarefas de uma vez.