Arbeiten mit langen Aktionen

Artikel
11/07/2024

In diesem Artikel wird beschrieben, wie Sie mit Aktionen mit langer Ausführungszeit arbeiten, wenn Sie Microsoft Graph-APIs verwenden. Einige API-Antworten erfordern eine unbestimmte Zeit bis zum Abschluss. Anstatt zu warten, bis die Aktion abgeschlossen ist, bevor eine Antwort zurückgegeben wird, verwendet Microsoft Graph möglicherweise ein Muster mit lang andauernden Aktionen. Dieses Muster bietet Ihrer App eine Möglichkeit, Statusupdates für eine aktion mit langer Ausführungsdauer abzufragen, ohne dass eine Anforderung auf den Abschluss der Aktion wartet.

Das allgemeine Muster umfasst die folgenden Schritte:

Ihre App fordert eine Aktion mit langer Ausführungsdauer über die API an. Die API akzeptiert die Aktion und gibt eine 202 Accepted Antwort zusammen mit einem Location Header für die API-URL zurück, um Aktionsstatusberichte abzurufen.
Ihre App fordert die URL des Aktionsstatusberichts an und empfängt eine asyncJobStatus-Antwort mit dem Fortschritt der Aktion mit langer Ausführungszeit.
Die zeitintensive Aktion wird abgeschlossen.
Ihre App fordert die URL des Aktionsstatusberichts erneut an und empfängt eine asyncJobStatus-Antwort , die den Abschluss der Aktion anzeigt.

Voraussetzungen

Die gleichen Berechtigungen , die zum Ausführen einer Aktion mit langer Ausführungszeit erforderlich sind, sind auch erforderlich, um den Status einer Aktion mit langer Ausführungszeit abzufragen.

Anfängliche Aktionsanforderung

Im folgenden Beispiel wird die methode driveitem: copy verwendet. In diesem Szenario sendet Ihre App eine Anforderung zum Kopieren eines Ordners, der eine große Datenmenge enthält. Die Ausführung dieser Anforderung dauert wahrscheinlich mehrere Sekunden, da die Datenmenge groß ist.

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



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://learn.microsoft.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://learn.microsoft.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)

Die API antwortet, dass die Aktion akzeptiert wurde, und gibt die URL zum Abrufen des Status der Aktion mit langer Ausführungszeit an.

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

In vielen Fällen ist dieser Schritt das Ende der Anforderung, da die Kopieraktion ohne andere Arbeit von der App abgeschlossen wird. Wenn Ihre App jedoch den Status der Kopieraktion anzeigen oder sicherstellen muss, dass sie ohne Fehler abgeschlossen wird, kann sie dies mithilfe der Überwachungs-URL tun.

Abrufen eines Statusberichts von der Überwachungs-URL

Um den Status des Kopiervorgang zu überprüfen, stellt die App eine Anforderung an die URL, die in der vorherigen Antwort bereitgestellt wurde.

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

Der Dienst antwortet mit informationen, dass die zeitintensive Aktion noch ausgeführt wird.

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

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

Diese Information kann verwendet werden, um den Benutzer über den Fortschritt des Kopiervorgangs zu informieren. Die App kann die Überwachungs-URL weiterhin abfragen, um Statusupdates anzufordern und den Fortschritt der Aktion nachzuverfolgen.

Abrufen eines Statusberichts zum Abschluss von der Überwachungs-URL

Nach einigen Sekunden wird der Kopiervorgang abgeschlossen. Wenn die App diesmal eine Anforderung an die Überwachungs-URL sendet, ist die Antwort eine Umleitung zum abgeschlossenen Ergebnis der Aktion.

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

Wenn die Aktion abgeschlossen ist, gibt die Antwort des Überwachungsdiensts die Ressourcen-ID für die Ergebnisse zurück.

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

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

Abrufen der Ergebnisse des abgeschlossenen Vorgangs

Nach Abschluss des Auftrags gibt die Überwachungs-URL die Ressourcen-ID des Ergebnisses zurück. In diesem Fall handelt es sich um die neue Kopie des ursprünglichen Elements. Das folgende Beispiel zeigt, wie Sie dieses neue Element mithilfe der Ressourcen-ID behandeln können.

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



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://learn.microsoft.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://learn.microsoft.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
}

Unterstützte Ressourcen

Aktionen mit langer Ausführungszeit werden für die folgenden Methoden unterstützt.

Ressource	API
driveItem	Kopieren

Freigeben über