Работа с действиями, выполняющимися длительное время (бета-версия)

Для выполнения некоторых запросов API требуется неопределенное время. Вместо того чтобы ожидать завершения действия перед возвращением ответа, Microsoft Graph может использовать шаблон действий, выполняющихся длительное время. Этот шаблон предоставляет приложению способ опроса на наличие обновлений состояния в длительном действии без запроса, ожидая завершения действия.

В стандартном шаблоне выполняются следующие действия:

1. Ваше приложение запрашивает действие, выполняющееся длительное время, через API. API принимает действие и возвращает ответ 202 Accepted вместе с заголовком Location для URL-адреса API, чтобы можно было получать отчеты о состоянии действия.
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.models.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-адрес расположения, возможно, не будет соответствовать конечной точке API Microsoft Graph.

Во многих случаях это может быть завершением запроса, так как действие копирования будет выполняться без каких-либо дополнительных действий со стороны приложения. Тем не менее если вашему приложению необходимо отображать состояние действия копирования или убедиться, что действие выполнено без ошибок, приложение может сделать это, используя 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

По завершении действия в отклике службы отслеживания будет возвращен идентификатор ресурса для результатов.

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

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

Получение результатов выполненной операции

После завершения задания URL-адрес для отслеживания возвращает идентификатор ресурса результата (в данном случае новую копию исходного элемента). Вы можете обратиться к этому новому элементу с использованием идентификатора ресурса, например:

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	Copy

Необходимые компоненты

Для запроса сведений о состоянии действия, выполняющегося длительное время, необходимы такие же разрешения, что и для самого действия, выполняющегося длительное время.