处理长时间运行的操作 (beta)

项目
03/21/2024

某些 API 响应完成所需的时间不确定。 Microsoft Graph 可能会使用长时间运行操作模式，而不是等待操作完成之后再返回响应。此模式为应用提供了一种轮询长时间运行的操作的状态更新的方法，而无需等待操作完成的任何请求。

常规模式包括以下步骤：

应用请求通过 API 执行长时间运行的操作。 API 接受操作，并返回 202 Accepted 响应以及 API URL 的 Location 头，以便检索操作状态报告。
应用请求获取操作状态报告 URL，然后收到包含长时间运行的操作进度的 AsyncJobStatus 响应。
长时间运行的操作完成。
应用再次请求获取操作状态报告 URL ，然后收到显示操作已完成状态的 AsyncJobStatus 响应。

初始操作请求

让我们来逐步完成 DriveItem 复制示例方案。在此方案中，应用请求复制包含大量数据的文件夹。因为数据量较大，所以此请求可能需要几秒钟才能完成。

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



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
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

copy, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Copy().Post(context.Background(), requestBody, nil)


// 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);


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);


<?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();


Import-Module Microsoft.Graph.Beta.Files

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

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


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.copy.copy_post_request_body import CopyPostRequestBody
from msgraph.generated.models.item_reference import ItemReference

graph_client = GraphServiceClient(credentials, scopes)

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)

API 予以响应，指明已接受此操作，并返回用于检索长时间运行的操作状态的 URL。

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

注意：返回的位置 URL 可能不在 Microsoft Graph API 终结点上。

在很多情况下，请求到此结束，因为复制操作的完成无需应用执行其他任何工作。不过，如果应用需要显示复制操作的状态，或确保其正确完成，可以使用监视器 URL。

通过监视器 URL 检索状态报告

为了检查复制操作的状态，应用会请求获取上一响应中返回的 URL。 注意：此请求无需验证，因为这是原始调用方专属的短期 URL。

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

服务响应返回的信息指明长时间运行的操作仍在进行中：

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

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

此信息可用于向用户提供复制操作的最新进度。应用可以继续轮询监视器 URL，以请求获取状态更新并跟踪操作进度。

通过监视器 URL 检索已完成状态报告

几秒钟后，复制操作完成。当应用向监视器 URL 发出请求时，响应返回的是重定向到操作的最终结果。

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

完成操作后，监视器服务的响应将返回结果的 resourceId。

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

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

检索已完成的操作的结果

完成作业后，监视器 URL 返回结果的 resourceId，在此例中为原始项的新副本。可以使用 resourceId 处理此新项，例如：

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();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta drives items get --drive-id {drive-id} --drive-item-id {driveItem-id}



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



items, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Get(context.Background(), nil)


// 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();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


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


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


Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "",
    "name": "Copy of LargeFolder1",
    "folder": { },
    "size": 12019
}

支持的资源

以下 API 方法支持长时间运行的操作

资源	API
DriveItem	Copy

先决条件

查询长时间运行的操作的状态也需要执行长时间运行的操作所需的相同权限。