Some API responses require indeterminate time to complete.
Instead of waiting until the action is complete before returning a response, Microsoft Graph may use a long running actions pattern.
This pattern provides your app a way to poll for status updates on a long running action, without any request waiting for the action to complete.
The general pattern follows these steps:
Your app requests a long running action via the API. The API accepts the action and returns a 202 Accepted response along with a Location header for the API URL to retrieve action status reports.
Your app requests the action status report URL and receives an AsyncJobStatus response with the progress of the long running action.
The long running action completes.
Your app requests the action status report URL again and receives an AsyncJobStatus response showing the completion of the action.
Initial action request
Let's walk through the steps for an example DriveItem Copy scenario.
In this scenario, your app requests to copy a folder that contains a large amount of data.
This request will likely take several seconds to complete since the amount of data is large.
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"
}
// 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);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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"\
}\
'
// 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);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\CopyPostRequestBody;
use Microsoft\Graph\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();
Note: The location URL returned may not be on the Microsoft Graph API endpoint.
In many cases this may be the end of the request, since the copy action will complete without the app doing any additional work.
However, if your app needs to show the status of the copy action or ensure that it completes without error, it can do so using the monitor URL.
Retrieve a status report from the monitor URL
To check on the status of the copy action, the app makes a request to the URL provided in the previous response.
Note: This request does not require authentication, since the URL is short-lived and unique to the original caller.
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
The service responses with information that the long running action is still in progress:
This information can be used to provide an update to the user about the progress of the copy action.
The app can continue to poll the monitor URL to request status updates and keep track of the progress of the action.
Retrieve a completed status report from the monitor URL
After a few seconds the copy operation has completed.
This time when the app makes a request to the monitor URL the response is a redirection to the finished result of the action.
GET https://api.onedrive.com/monitor/4A3407B5-88FC-4504-8B21-0AABD3412717
When the action has completed, the response from the monitor service will return the resourceId for the results.
Once the job has completed, the monitor URL returns the resourceId of the result, in this case the new copy of the original item.
You can address this new item using the resourceId, for example:
GET https://graph.microsoft.com/beta/me/drive/items/{item-id}
// 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();
// 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();
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.