Partager via

Utilisation des API de longue durée

  • Article

Dans certains scénarios, il n’est pas possible d’exécuter des actions comme copy ou upload from URL dans un temps déterminé. Pour gérer ces scénarios et réduire le temps de réponse de l’API, ces actions sont implémentées avec un modèle d’actions de longue durée.

  1. L’application demande une action de longue durée via l’API. L’API accepte l’action et renvoie une réponse 202 Accepted avec un en-tête Location pour l’URL de l’API afin de récupérer les rapports d’état de l’action.
  2. L’application demande l’URL du rapport d’état de l’action et reçoit une réponse AsyncJobStatus avec la progression de l’action de longue durée.
  3. L’action de longue durée est terminée. La fois suivante, l’application demande l’URL du rapport d’état de l’action et reçoit une réponse AsyncJobStatus à la fin de l’action.

Demande d’action initiale

Voici les étapes d’exécution d’une action de copie. Dans ce scénario, une application demande de copier un dossier contenant une grande quantité de données. Cette demande risque de prendre plusieurs secondes car le volume de données est conséquent.

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

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

L’API répond que l’action a été acceptée et envoie l’URL pour obtenir l’état de l’action de longue durée.

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

Dans de nombreux cas, il peut s’agir de la fin de la demande, car l’action de copie est effectuée sans que l’application n’effectue de travail supplémentaire. Toutefois, si l’application souhaite afficher l’état de l’action de copie ou pour s’assurer qu’elle s’exécute sans erreur, l’URL de surveillance peut être utilisée.

Récupérer un rapport d’état à partir de l’URL de surveillance

Pour vérifier l’état de l’action de copie, l’application soumet une demande à l’URL fournie dans la réponse précédente. Remarque : Cette demande ne requiert pas d’authentification, car l’URL est de courte durée et propre à l’appelant d’origine.

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

Le service informe que l’action de longue durée est toujours en cours :

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

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

Ces informations peuvent être utilisées pour fournir une mise à jour à l’utilisateur sur la progression de l’action de copie. L’application continue d’interroger l’URL de surveillance pour demander les mises à jour du statut et effectuer le suivi de l’avancement de l’action.

Récupérer un rapport d’état de fin de l’URL de surveillance

Au bout de quelques secondes, l’opération de copie est terminée. À ce stade, lorsque l’application soumet une demande à l’URL de surveillance, la réponse est une redirection vers le résultat final de l’action.

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

Une fois l’action terminée, la réponse du service de surveillance renvoie l’objet resourceId pour les résultats.

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

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

Récupérer les résultats de l’action terminée