長時間実行アクションの処理 (ベータ版)

一部の API 応答では、完了までに要する時間が不明です。 アクションが完了するまで待機してから応答を返す代わりに、Microsoft Graph では長時間実行アクションのパターンを使用できます。 このパターンにより、実行時間の長いアクションで状態の更新をポーリングする方法がアプリに提供されます。アクションの完了を待機する要求はありません。

一般的なパターンでは、以下の手順を実行します。

1. アプリが API 経由で長時間実行アクションを要求します。 API はアクションを承諾し、API URL の Location ヘッダーと共に 202 Accepted 応答を返して、アクションの状態レポートを取得します。
2. アプリは、アクションの状態レポート URL を要求して、長時間実行アクションの進行状況を含む AsyncJobStatus 応答を受け取ります。
3. 長時間実行アクションが完了します。
4. アプリはアクションの状態レポート URL を再度要求して、アクションの完了を示す AsyncJobStatus 応答を受け取ります。

最初のアクション要求

DriveItem コピー シナリオの例を順を追って説明します。 このシナリオでは、アプリは大量のデータが格納されているフォルダーのコピーを要求します。 この要求は、データが大量であるため完了までに数秒間かかる可能性があります。

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

CLI

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Go

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)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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);

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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);

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PHP

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Python

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)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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 を使用してこの新しいアイテムに対処することができます。次に例を示します。

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

CLI

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Go

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)

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、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();

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

PowerShell

Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

Python

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

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

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

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

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

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

リソース	API
DriveItem	コピー

前提条件

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