Utilisation d’actions de longue durée

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.

HTTP

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

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Drives.Item.Items.Item.Copy;
using Microsoft.Graph.Beta.Models;

var requestBody = new CopyPostRequestBody
{
	ParentReference = new ItemReference
	{
		Path = "/drive/root:/Documents",
	},
	Name = "Copy of LargeFolder1",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Copy.PostAsync(requestBody);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

mgc-beta drives items copy post --drive-id {drive-id} --drive-item-id {driveItem-id} --body '{\
  "parentReference": {\
    "path": "/drive/root:/Documents"\
  },\
  "name": "Copy of LargeFolder1"\
}\
'

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-beta-sdk-go/drives"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphdrives.NewCopyPostRequestBody()
parentReference := graphmodels.NewItemReference()
path := "/drive/root:/Documents"
parentReference.SetPath(&path) 
requestBody.SetParentReference(parentReference)
name := "Copy of LargeFolder1"
requestBody.SetName(&name) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
copy, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Copy().Post(context.Background(), requestBody, nil)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.drives.item.items.item.copy.CopyPostRequestBody copyPostRequestBody = new com.microsoft.graph.beta.drives.item.items.item.copy.CopyPostRequestBody();
ItemReference parentReference = new ItemReference();
parentReference.setPath("/drive/root:/Documents");
copyPostRequestBody.setParentReference(parentReference);
copyPostRequestBody.setName("Copy of LargeFolder1");
var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").copy().post(copyPostRequestBody);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const driveItem = {
  parentReference: {
    path: '/drive/root:/Documents'
  },
  name: 'Copy of LargeFolder1'
};

await client.api('/me/drive/items/{folder-item-id}/copy')
	.version('beta')
	.post(driveItem);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Drives\Item\Items\Item\Copy\CopyPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\ItemReference;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new CopyPostRequestBody();
$parentReference = new ItemReference();
$parentReference->setPath('/drive/root:/Documents');
$requestBody->setParentReference($parentReference);
$requestBody->setName('Copy of LargeFolder1');

$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->copy()->post($requestBody)->wait();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Beta.Files

$params = @{
	parentReference = @{
		path = "/drive/root:/Documents"
	}
	name = "Copy of LargeFolder1"
}

Copy-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId -BodyParameter $params

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.drives.item.items.item.copy.copy_post_request_body import CopyPostRequestBody
from msgraph_beta.generated.models.item_reference import ItemReference
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CopyPostRequestBody(
	parent_reference = ItemReference(
		path = "/drive/root:/Documents",
	),
	name = "Copy of LargeFolder1",
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').copy.post(request_body)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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.

HTTP

GET https://graph.microsoft.com/beta/me/drive/items/{item-id}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].GetAsync();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

mgc-beta drives items get --drive-id {drive-id} --drive-item-id {driveItem-id}

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
items, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Get(context.Background(), nil)

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").get();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/items/{item-id}')
	.version('beta')
	.get();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->get()->wait();

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').get()

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

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