Como trabalhar com ações de execução longa (beta)

Algumas respostas de API exigem tempo indeterminado para serem concluídas. Em vez de ter que esperar até que a ação seja concluída antes de retornar uma resposta, o Microsoft Graph pode usar um padrão de ações de execução longa. Esse padrão fornece ao seu aplicativo uma maneira de sondar status atualizações em uma ação de execução longa, sem qualquer solicitação aguardando a conclusão da ação.

O padrão geral segue estas etapas:

1. O aplicativo solicita uma ação de execução longa por meio da API. A API aceita a ação e retorna uma resposta 202 Accepted junto com um cabeçalho de Local para que a URL de API recupere relatórios de status de ação.
2. O aplicativo solicita a URL de relatório de status de ação e recebe uma resposta AsyncJobStatus com o progresso da ação de execução longa.
3. A ação de execução longa é concluída.
4. O aplicativo solicita a URL de relatório de status da ação novamente e recebe uma resposta AsyncJobStatus que mostra a conclusão da ação.

Solicitação de ação inicial

Vamos percorrer as etapas para obter um cenário de exemplo de DriveItem Copy. Neste cenário, o aplicativo solicita a cópia de uma pasta que contém uma grande quantidade de dados. Essa solicitação provavelmente levará vários segundos para ser concluída, pois a quantidade de dados é grande.

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

A API responde que a ação foi aceita e fornece a URL para recuperar o status da ação de execução longa.

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

Observação: o local da URL retornado pode não estar no ponto de extremidade da API do Microsoft Graph.

Em muitos casos, esse pode ser o fim da solicitação, pois a ação de cópia será concluída sem que o aplicativo realize tarefas adicionais. No entanto, se o aplicativo precisar mostrar o status da ação de cópia ou garantir que ela seja concluída sem erros, poderá fazer isso usando a URL de monitor.

Recuperar um relatório de status da URL de monitor

Para verificar o status da ação de cópia, o aplicativo faz uma solicitação para a URL fornecida na resposta anterior. Observação: Essa solicitação não requer autenticação, pois a URL é de curta duração e exclusiva para o chamador original.

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

O serviço responde com a informação de que a ação de execução longa ainda está em andamento:

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

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

As informações podem ser usadas para fornecer uma atualização ao usuário sobre o progresso da ação de cópia. O aplicativo pode continuar a sondar a URL de monitor para solicitar atualizações de status e acompanhar o andamento da ação.

Recuperar um relatório de status concluído da URL de monitor

Após alguns segundos, a operação de cópia foi concluída. Dessa vez, quando o aplicativo faz uma solicitação para a URL de monitor, a resposta é um redirecionamento para o resultado concluído da ação.

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

Após a conclusão da ação, a resposta do serviço de monitor retornará a resourceId para obter os resultados.

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

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

Recuperar os resultados da operação concluída

Depois que o trabalho for concluído, a URL do monitor retornará o resourceId do resultado. Neste caso, trata-se da nova cópia do item original. Você pode resolver esse novo item usando resourceId; por exemplo:

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

CLI

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

Ir

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)

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

PowerShell

Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaDriveItem -DriveId $driveId -DriveItemId $driveItemId

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância do authProvider .

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

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

Recursos com suporte

Ações de execução longa têm suporte nos métodos de API a seguir

Recurso	API
DriveItem	Copiar

Pré-requisitos

As mesmas permissões que são necessárias para realizar uma ação de execução longa também são necessárias para consultar o status de uma ação de execução longa.