Trabalhar com ações demoradas

Este artigo descreve como trabalhar com ações de longa duração ao usar APIs do Microsoft Graph. Algumas respostas da API exigem um tempo indeterminado para serem concluídas. Em vez de 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 prolongada. Esse padrão fornece ao aplicativo uma maneira de sondar atualizações de status em uma ação de execução prolongada, sem nenhuma solicitação aguardando a conclusão da ação.

O padrão geral envolve as seguintes etapas:

Seu aplicativo solicita uma ação de execução longa por meio da API. A API aceita a ação e retorna uma 202 Accepted resposta junto com um Location cabeçalho para a URL da API para recuperar relatórios de status da ação.
Seu aplicativo solicita a URL do relatório de status da ação e recebe uma resposta asyncJobStatus com o progresso da ação de execução prolongada.
A ação de execução prolongada é concluída.
Seu aplicativo solicita a URL do relatório de status da ação novamente 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 longa também são necessárias para consultar o status de uma ação de execução prolongada.

Solicitação de ação inicial

O exemplo a seguir usa o método driveitem: copy . Nesse cenário, seu aplicativo faz uma solicitação para copiar uma pasta que contém uma grande quantidade de dados. É provável que essa solicitação leve vários segundos para ser concluída porque a quantidade de dados é grande.

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



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

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

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

Em muitos casos, essa etapa é o fim da solicitação, pois a ação de cópia é concluída sem nenhum outro trabalho do aplicativo. No entanto, se o aplicativo precisar mostrar o status da ação de cópia ou garantir que ela seja concluída sem erros, ele poderá fazer isso usando a 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.

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 é concluída. Desta vez, quando o aplicativo faz uma solicitação para a 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 é concluída, a resposta do serviço monitor retorna a 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 o trabalho é concluído, a URL do monitor retorna a ID de recurso do resultado. Nesse caso, é a nova cópia do item original. O exemplo a seguir mostra como você pode resolver esse novo item usando a ID do recurso.

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



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

Recursos com suporte

Há suporte para ações de execução prolongada nos métodos a seguir.

Recurso	API
driveItem	copy

Comentários

Esta página foi útil?

Last updated on 2026-08-24