Trabalhar com ações demoradas

Este artigo descreve como trabalhar com ações de execução prolongada quando utiliza as APIs do Microsoft Graph. Algumas respostas de API requerem uma quantidade indeterminada de tempo para concluir. Em vez de aguardar até que a ação esteja concluída antes de devolver uma resposta, o Microsoft Graph poderá utilizar um padrão de ações de execução prolongada. Este padrão fornece à sua aplicação uma forma de consultar as atualizações de estado numa ação de execução prolongada, sem qualquer pedido à espera que a ação seja concluída.

O padrão geral envolve os seguintes passos:

1. A sua aplicação pede uma ação de execução prolongada através da API. A API aceita a ação e devolve uma 202 Accepted resposta juntamente com um Location cabeçalho para o URL da API obter relatórios de estado de ação.
2. A sua aplicação pede o URL do relatório de estado da ação e recebe uma resposta asyncJobStatus com o progresso da ação de execução prolongada.
3. A ação de execução prolongada é concluída.
4. A aplicação pede novamente o URL do relatório de estado de ação e recebe uma resposta asyncJobStatus que mostra a conclusão da ação.

Pré-requisitos

As mesmas permissões necessárias para executar uma ação de execução prolongada também são necessárias para consultar o estado de uma ação de execução prolongada.

Solicitação de ação inicial

O exemplo seguinte utiliza o método driveitem: copy . Neste cenário, a sua aplicação faz um pedido para copiar uma pasta que contém uma grande quantidade de dados. É provável que este pedido dedquia vários segundos a ser concluído porque 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 projeto e criar uma instância authProvider .

CLI

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 projeto e criar uma instância authProvider .

Ir

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância authProvider .

PHP

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância 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 projeto e criar uma instância authProvider .

Python

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

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 projeto e criar uma instância authProvider .

A API responde que a ação foi aceite e fornece o URL para obter o estado da ação de execução prolongada.

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

Nota: O URL de localização devolvido pode não estar no ponto final da Microsoft Graph API.

Em muitos casos, este passo é o fim do pedido, porque a ação de cópia é concluída sem qualquer outro trabalho da aplicação. No entanto, se a sua aplicação precisar de mostrar o estado da ação de cópia ou garantir que é concluída sem erros, pode fazê-lo utilizando o URL do 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.

Nota: Este pedido não requer autenticação, porque o URL é de curta duração e exclusivo para o autor da chamada original.

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

O serviço responde com informações de que a ação de execução prolongada ainda está em curso.

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 é concluída. Desta vez, quando a aplicação faz um pedido ao URL do monitor, a resposta é um redirecionamento para o resultado final da ação.

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

Quando a ação for concluída, a resposta do serviço de monitorização devolve o ID do recurso para 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

Quando a tarefa estiver concluída, o URL do monitor devolve o ID de recurso do resultado. Neste caso, é a nova cópia do item original. O exemplo seguinte mostra como pode resolver este novo item com o ID de recurso.

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 projeto e criar uma instância authProvider .

CLI

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 projeto e criar uma instância authProvider .

Ir

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

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao projeto e criar uma instância 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 projeto e criar uma instância 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 projeto e criar uma instância authProvider .

PHP

<?php
use Microsoft\Graph\Beta\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 projeto e criar uma instância 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 projeto e criar uma instância authProvider .

Python

from msgraph_beta 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 projeto e criar uma instância authProvider .

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

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

Recursos com suporte

As ações de execução prolongada são suportadas nos seguintes métodos.

Recurso	API
driveItem	copy