Trabajar con acciones de ejecución prolongada (beta)Working with long running actions (beta)

Algunas respuestas de API requieren un tiempo indeterminado para completarse.Some API responses require indeterminate time to complete. En lugar de esperar hasta que se completa la acción antes de devolver una respuesta, Microsoft Graph puede usar un modelo de acciones de larga duración.Instead of waiting until the action is complete before returning a response, Microsoft Graph may use a long running actions pattern. Este patrón proporciona a la aplicación una forma de sondear las actualizaciones de estado en una acción de larga duración, sin ninguna solicitud que espere a que se complete la acción.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.

El modelo general sigue estos pasos:The general pattern follows these steps:

  1. La aplicación solicita una acción de larga duración mediante la API.Your app requests a long running action via the API. La API acepta la acción y devuelve una respuesta 202 Accepted junto con un encabezado de ubicación para la dirección URL de la API para recuperar los informes de estado de la acción.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. La aplicación solicita la dirección URL del informe de estado de la acción y recibe una respuesta AsyncJobStatus con el progreso de la acción de larga duraciónYour app requests the action status report URL and receives an AsyncJobStatus response with the progress of the long running action.
  3. Se completa la acción de larga duración.The long running action completes.
  4. La aplicación vuelve a solicitar la dirección URL del informe de estado de la acción y recibe una respuesta AsyncJobStatus en la que se muestra la finalización de la acción.Your app requests the action status report URL again and receives an AsyncJobStatus response showing the completion of the action.

Solicitud de acción inicialInitial action request

Vamos a recorrer los pasos para obtener un ejemplo del escenario copiar de DriveItem.Let's walk through the steps for an example DriveItem Copy scenario. En este escenario, la aplicación solicita copiar una carpeta que contiene una gran cantidad de datos.In this scenario, your app requests to copy a folder that contains a large amount of data. Esta solicitud probablemente tardará varios segundos en completarse ya que la cantidad de datos es 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"
}

La API responde que la acción se ha aceptado junto con la dirección URL para recuperar el estado de la acción de larga duración.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

Nota: La dirección URL devuelta no puede estar en el punto de conexión de la API de Microsoft Graph.Note: The location URL returned may not be on the Microsoft Graph API endpoint.

En muchos casos esto puede ser el final de la solicitud, ya que la acción de copia se completará sin que la aplicación realice ninguna acción adicional. En cambio, si la aplicación tiene que mostrar el estado de la acción de copia o garantizar que finaliza sin errores, puede hacerlo con la dirección URL de supervisión.In many cases this may be the end of the request, since the copy action will complete without the app doing any additional work. 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 un informe de estado desde la dirección URL de supervisiónRetrieve a status report from the monitor URL

Para comprobar el estado de la acción de copia, la aplicación realiza una solicitud a la dirección URL proporcionada en la respuesta anterior. Nota: Esta solicitud no necesita autenticación, ya que la dirección URL es de corta duración y única para el autor de la llamada 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

El servicio responde con información de que la acción de larga duración todavía está en curso: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"
}

Esta información puede usarse para proporcionar una actualización al usuario sobre el progreso de la acción de copia. La aplicación puede continuar sondeando la dirección URL de supervisión para solicitar actualizaciones de estado y mantener el seguimiento del progreso de la acción.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 un informe de estado completado desde la dirección URL de supervisiónRetrieve a completed status report from the monitor URL

Después de unos segundos, la operación de copia se ha completado. Esta vez, cuando la aplicación realiza una solicitud a la dirección URL de supervisión, la respuesta es un redireccionamiento al resultado finalizado de la acción.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

Una vez finalizada la acción, la respuesta del servicio de supervisión devolverá el valor resourceId de los 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 los resultados de la operación completadaRetrieve the results of the completed operation

Una vez que haya finalizado el trabajo, la dirección URL de supervisión devuelve el resourceId del resultado, en este caso la nueva copia del elemento 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. Puede dirigir este nuevo elemento mediante resourceId, por ejemplo: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 admitidosSupported resources

Las acciones de larga duración son compatibles con los siguientes métodos de la APILong running actions are supported on the following API methods

RecursoResource APIAPI
DriveItemDriveItem CopiarCopy

Requisitos previosPrerequisites

Para consultar el estado de una acción de larga duración se requieren los mismos permisos que para realizarla.The same permissions that are required to perform a long running action are also required to query the status of a long running action.