Trabajar con acciones de ejecución prolongada (beta)

Algunas respuestas de API requieren un tiempo indeterminado para completarse. 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. Este patrón proporciona a la aplicación una forma de sondear las actualizaciones de estado en una acción de larga ejecución, sin que ninguna solicitud esté esperando a que se complete la acción.

El modelo general sigue estos pasos:

  1. La aplicación solicita una acción de larga duración mediante la 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.
  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ón
  3. Se completa la acción de larga duración.
  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.

Solicitud de acción inicial

Vamos a recorrer los pasos para obtener un ejemplo del escenario copiar de DriveItem. En este escenario, la aplicación solicita copiar una carpeta que contiene una gran cantidad de datos. Esta solicitud probablemente tardará varios segundos en completarse ya que la cantidad de datos es grande.

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.

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.

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.

Recuperar un informe de estado desde la dirección URL de supervisión

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.

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:

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.

Recuperar un informe de estado completado desde la dirección URL de supervisión

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.

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.

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

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

Recuperar los resultados de la operación completada

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. Puede dirigir este nuevo elemento mediante resourceId, por ejemplo:

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 admitidos

Las acciones de larga duración son compatibles con los siguientes métodos de la API

Recurso API
DriveItem Copiar

Requisitos previos

Para consultar el estado de una acción de larga duración se requieren los mismos permisos que para realizarla.