Utilisation d’actions de longue durée

  • Article

Cet article explique comment utiliser des actions de longue durée lorsque vous utilisez des API Microsoft Graph. Certaines réponses d’API nécessitent un temps indéterminé pour s’exécuter. Au lieu d’attendre que l’action soit terminée avant de retourner une réponse, Microsoft Graph peut utiliser un modèle d’actions de longue durée. Ce modèle permet à votre application d’interroger les mises à jour d’état sur une action de longue durée, sans qu’aucune demande n’attende la fin de l’action.

Le modèle général implique les étapes suivantes :

  1. Votre application demande une action de longue durée via l’API. L’API accepte l’action et retourne une 202 Accepted réponse avec un Location en-tête pour l’URL de l’API afin de récupérer les rapports d’état de l’action.
  2. Votre application demande l’URL du rapport d’état de l’action et reçoit une réponse asynchroneJobStatus avec la progression de l’action de longue durée.
  3. L’action de longue durée se termine.
  4. Votre application demande à nouveau l’URL du rapport d’état de l’action et reçoit une réponse asyncJobStatus qui indique l’achèvement de l’action.

Configuration requise

Les mêmes autorisations que celles requises pour effectuer une action de longue durée sont également requises pour interroger l’état d’une action de longue durée.

Demande d’action initiale

L’exemple suivant utilise la méthode driveitem : copy . Dans ce scénario, votre application effectue une demande de copie d’un dossier qui contient une grande quantité de données. Cette demande est susceptible de prendre plusieurs secondes, car la quantité de données est importante.

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

L’API répond que l’action a été acceptée et fournit l’URL pour récupérer 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

Note: L’URL d’emplacement retournée peut ne pas se trouver sur le point de terminaison de l’API Microsoft Graph.

Dans de nombreux cas, cette étape est la fin de la demande, car l’action de copie se termine sans autre travail de la part de l’application. Toutefois, si votre application doit afficher l’état de l’action de copie ou s’assurer qu’elle se termine sans erreur, elle peut le faire à l’aide de l’URL du moniteur.

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.

Note: Cette demande ne nécessite 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 répond en indiquant 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

Après quelques secondes, l’opération de copie se termine. Cette fois, lorsque l’application envoie une requête à l’URL du moniteur, la réponse est une redirection vers le résultat terminé 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 d’analyse retourne l’ID de ressource pour les résultats.

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

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

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

Une fois le travail terminé, l’URL du moniteur retourne l’ID de ressource du résultat. Dans ce cas, il s’agit de la nouvelle copie de l’élément d’origine. L’exemple suivant montre comment traiter ce nouvel élément à l’aide de l’ID de ressource.

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
}

Ressources prises en charge

Les actions de longue durée sont prises en charge sur les méthodes suivantes.

Ressource API
driveItem Copier