Trabalhar com APIs que podem demorar muito para serem concluídas

  • Artigo

Alguns cenários, como copiar ou carregar da URL, não podem sempre ser concluídos em um período de tempo finito. Para lidar com esses cenários e manter uma latência de resposta de API baixa, essas ações são implementadas usando um padrão de ações de execução longa.

  1. O aplicativo solicita uma ação de execução longa por meio da API. A API aceita a ação e retorna uma resposta 202 Accepted junto com um cabeçalho de Local para que a URL de API recupere relatórios de status de ação.
  2. O aplicativo solicita a URL de relatório de status de ação e recebe uma resposta AsyncJobStatus com o progresso da ação de execução longa
  3. A ação de execução longa é concluída. Na próxima vez, o aplicativo solicita a URL de relatório de status da ação e recebe uma resposta AsyncJobStatus com a conclusão da ação.

Solicitação de ação inicial

Vamos percorrer as etapas de um cenário de cópia de exemplo. Nesse cenário, um aplicativo faz uma solicitação para copiar uma pasta com uma grande quantidade de dados. Essa solicitação provavelmente levará vários segundos para ser concluída, pois a quantidade de dados é grande.

POST /drive/items/{folder-item-id}/copy
Content-Type: application/json
Prefer: respond-async

{
  "parentReference": {
    "path": "/drive/root:/Documents"
  },
  "name": "Copy of LargeFolder1"
}

A API responde que a ação foi aceita e fornece a URL para recuperar o status da ação de execução longa.

HTTP/1.1 202 Accepted
Location: https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Em muitos casos, esse pode ser o fim da solicitação, pois a ação de cópia será concluída sem que o aplicativo faça trabalho adicional. No entanto, se o aplicativo quiser mostrar o status da ação de cópia ou garantir que ela seja concluída sem erros, ele poderá fazer isso usando a URL de monitor.

Recuperar um relatório de status da URL de monitor

Para verificar o status da ação de cópia, o aplicativo faz uma solicitação para a URL fornecida na resposta anterior. Observação: Essa solicitação não requer autenticação, pois a URL é de curta duração e exclusiva para o chamador original.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

O serviço responde com a informação de que a ação de execução longa ainda está em andamento:

HTTP/1.1 202 Accepted
Content-type: application/json

{
  "operation": "ItemCopy",
  "percentageComplete": 27.8,
  "status": "inProgress"
}

As informações podem ser usadas para fornecer uma atualização ao usuário sobre o progresso da ação de cópia. O aplicativo pode continuar a sondar a URL de monitor para solicitar atualizações de status e acompanhar o andamento da ação.

Recuperar um relatório de status concluído da URL de monitor

Após alguns segundos, a operação de cópia foi concluída. Dessa vez, quando o aplicativo faz uma solicitação para a URL de monitor, a resposta é um redirecionamento para o resultado concluído da ação.

GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717

Após a conclusão da ação, a resposta do serviço de monitor retornará a resourceId para obter os resultados.

HTTP/1.1 303 See Other
Content-type: application/json

{
    "percentageComplete": 100.0,
    "resourceId": "01MOWKYVJML57KN2ANMBA3JZJS2MBGC7KM",
    "status": "completed"
}

Recuperar os resultados da operação concluída