Trabajar con las API que tardan mucho en completarse

  • Artículo

Algunos escenarios, como copiar o cargar desde la dirección URL, no se pueden completar siempre en un tiempo determinado. Para controlar estos escenarios y mantener una latencia de respuesta de la API baja, estas acciones se implementan con un patrón de acciones de larga duración.

  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. La próxima vez, la aplicación solicita la dirección URL del informe de estado de la acción y recibe una respuesta AsyncJobStatus con la finalización de la acción.

Solicitud de acción inicial

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

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

{
  "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

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 quiere 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 303 See Other
Content-type: application/json

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

Recuperar los resultados de la operación completada