長時間実行されるアクションの処理

[アーティクル]
06/06/2024

この記事では、Microsoft Graph API を使用するときに実行時間の長いアクションを操作する方法について説明します。一部の API 応答では、完了するまでに不確定な時間が必要です。応答を返す前にアクションが完了するまで待たずに、Microsoft Graph では実行時間の長いアクションパターンを使用する場合があります。このパターンにより、実行時間の長いアクションで状態の更新をポーリングする方法がアプリに提供されます。要求はアクションの完了を待機しません。

一般的なパターンには、次の手順が含まれます。

アプリは、API を介して実行時間の長いアクションを要求します。 API はアクションを受け入れ、アクション状態レポートを202 AcceptedLocation取得するための API URL のヘッダーと共に応答を返します。
アプリはアクション状態レポート URL を要求し、実行時間の長いアクションの進行状況を示す asyncJobStatus 応答を受け取ります。
実行時間の長いアクションが完了します。
アプリは、アクションの状態レポート URL を再度要求し、アクションの完了を示す asyncJobStatus 応答を受け取ります。

前提条件

実行時間の長いアクションの状態を照会するには、実行時間の長いアクションを実行するために必要なのと同じアクセス許可も必要です。

最初のアクション要求

次の例では、 driveitem: copy メソッドを使用します。このシナリオでは、アプリが大量のデータを含むフォルダーをコピーするように要求します。データ量が多いため、この要求が完了するまでに数秒かかる可能性があります。

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://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Copy.PostAsync(requestBody);



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 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://video2.skills-academy.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)


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


Import-Module Microsoft.Graph.Beta.Files

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

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


# 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://video2.skills-academy.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)

API は、アクションが受け入れられたことを応答し、実行時間の長いアクションの状態を取得する URL を提供します。

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

多くの場合、この手順は要求の終わりです。これは、コピーアクションがアプリの他の作業なしで完了するためです。ただし、アプリでコピーアクションの状態を表示する必要がある場合、またはエラーなしで完了したことを確認する必要がある場合は、モニター 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

アクションが完了すると、モニターサービスからの応答によって結果のリソース ID が返されます。

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

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

完了した操作の結果を取得する

ジョブが完了すると、モニター URL は結果のリソース ID を返します。この場合は、元のアイテムの新しいコピーです。次の例は、リソース ID を使用してこの新しい項目に対処する方法を示しています。

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://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].GetAsync();



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



// 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://video2.skills-academy.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)


// 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\Beta\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


# 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://video2.skills-academy.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()

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

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

サポートされているリソース

実行時間の長いアクションは、次のメソッドでサポートされています。

Resource	API
driveItem	コピー

次の方法で共有