Como trabalhar com ações de execução longa (beta)Working with long running actions (beta)

Algumas respostas de API exigem tempo indeterminado para serem concluídas.Some API responses require indeterminate time to complete. Em vez de ter que esperar até que a ação seja concluída antes de retornar uma resposta, o Microsoft Graph pode usar um padrão de ações de execução longa.Instead of waiting until the action is complete before returning a response, Microsoft Graph may use a long running actions pattern. Este padrão fornece ao aplicativo uma maneira de Pesquisar atualizações de status em uma ação de execução longa, sem qualquer solicitação aguardando a conclusão da ação.This pattern provides your app a way to poll for status updates on a long running action, without any request waiting for the action to complete.

O padrão geral segue estas etapas:The general pattern follows these steps:

  1. O aplicativo solicita uma ação de execução longa por meio da API.Your app requests a long running action via the 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.The API accepts the action and returns a 202 Accepted response along with a Location header for the API URL to retrieve action status reports.
  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.Your app requests the action status report URL and receives an AsyncJobStatus response with the progress of the long running action.
  3. A ação de execução longa é concluída.The long running action completes.
  4. O aplicativo solicita a URL de relatório de status da ação novamente e recebe uma resposta AsyncJobStatus que mostra a conclusão da ação.Your app requests the action status report URL again and receives an AsyncJobStatus response showing the completion of the action.

Solicitação de ação inicialInitial action request

Vamos percorrer as etapas para obter um cenário de exemplo de DriveItem Copy.Let's walk through the steps for an example DriveItem Copy scenario. Neste cenário, o aplicativo solicita a cópia de uma pasta que contém uma grande quantidade de dados.In this scenario, your app requests to copy a folder that contains a large amount of data. Essa solicitação provavelmente levará vários segundos para ser concluída, pois a quantidade de dados é grande.This request will likely take several seconds to complete since the amount of data is large.

POST https://graph.microsoft.com/beta/me/drive/items/{folder-item-id}/copy
Content-Type: application/json

{
  "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.The API responds that the action was accepted and the URL for retrieving the status of the long running action.

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

Observação: o local da URL retornado pode não estar no ponto de extremidade da API do Microsoft Graph.Note: The location URL returned may not be on the Microsoft Graph API endpoint.

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 realize tarefas adicionais.In many cases this may be the end of the request, since the copy action will complete without the app doing any additional work. No entanto, se o aplicativo precisar mostrar o status da ação de cópia ou garantir que ela seja concluída sem erros, poderá fazer isso usando a URL de monitor.However, if your app needs to show the status of the copy action or ensure that it completes without error, it can do so using the monitor URL.

Recuperar um relatório de status da URL de monitorRetrieve a status report from the monitor URL

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.To check on the status of the copy action, the app makes a request to the URL provided in the previous response. Note: This request does not require authentication, since the URL is short-lived and unique to the original caller.

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:The service responses with information that the long running action is still in progress:

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.This information can be used to provide an update to the user about the progress of the copy action. The app can continue to poll the monitor URL to request status updates and keep track of the progress of the action.

Recuperar um relatório de status concluído da URL de monitorRetrieve a completed status report from the monitor URL

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.After a few seconds the copy operation has completed. This time when the app makes a request to the monitor URL the response is a redirection to the finished result of the action.

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.When the action has completed, the response from the monitor service will return the resourceId for the results.

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

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

Recuperar os resultados da operação concluídaRetrieve the results of the completed operation

Depois que o trabalho for concluído, a URL do monitor retornará o resourceId do resultado. Neste caso, trata-se da nova cópia do item original.Once the job has completed, the monitor URL returns the resourceId of the result, in this case the new copy of the original item. Você pode resolver esse novo item usando resourceId; por exemplo:You can address this new item using the resourceId, for example:

GET https://graph.microsoft.com/beta/me/drive/items/{item-id}
HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "",
    "name": "Copy of LargeFolder1",
    "folder": { },
    "size": 12019
}

Recursos com suporteSupported resources

Ações de execução longa têm suporte nos métodos de API a seguirLong running actions are supported on the following API methods

RecursoResource APIAPI
DriveItemDriveItem CopiarCopy

Pré-requisitosPrerequisites

As mesmas permissões que são necessárias para realizar uma ação de execução longa também são necessárias para consultar o status de uma ação de execução longa.The same permissions that are required to perform a long running action are also required to query the status of a long running action.