driveItem: delta

Namespace: microsoft.graph

Acompanhe as alterações em um driveItem e seus filhos ao longo do tempo.

Seu aplicativo começa chamando delta sem parâmetros. O serviço começa a enumerar a hierarquia da unidade, retornando páginas de itens e um @odata.nextLink ou @odata.deltaLink, conforme descrito abaixo. Seu aplicativo deve continuar chamando com o @odata.nextLink até que você não veja mais um @odata.nextLink retornado ou até que você veja uma resposta com um conjunto vazio de alterações.

Quando terminar de receber todas as alterações, você pode aplicá-las ao seu estado local. Para verificar se há alterações no futuro, chame delta novamente com o @odata.deltaLink da resposta anterior.

Itens excluídos são retornados com a faceta deleted. Itens com esse conjunto de propriedades devem ser removidos do seu estado local.

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante)	Files.Read	Files. Read.All, Files. ReadWrite, Files. ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Files.Read	Files. Read.All, Files. ReadWrite, Files. ReadWrite.All
Application	Files.Read.All	Files. ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitação HTTP

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId | userPrincipalName}/drive/root/delta

Parâmetros de função

Parâmetro	Tipo	Descrição
token	string	Opcional. Quando não é especificado, enumera o estado da hierarquia atual. Quando é `latest`, retorna uma resposta vazia com o token delta mais recente. Quando é um token delta anterior, retorna o novo estado após o token.

Parâmetros de consulta opcionais

Esse método dá suporte aos $selectparâmetros de consulta , $expande $top OData para personalizar a resposta.

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
deltaExcludeParent	Cadeia de caracteres. Se esse cabeçalho de solicitação for incluído, a resposta incluirá os itens que foram alterados e não os itens pai na hierarquia.

Corpo da solicitação

Não forneça um corpo de solicitação para esse método.

Resposta

Se for bem-sucedido, esse método retornará um código de resposta 200 OK e uma coleção de recursos Driveitem no corpo da resposta.

Além da coleção de DriveItems, a resposta também incluirá uma das seguintes propriedades:

Nome	Valor	Descrição
@odata.nextLink	url	Uma URL para recuperar a próxima página disponível de alterações, se houver mais alterações no conjunto atual.
@odata.deltaLink	url	Uma URL retornada no lugar de @odata.nextLink após o retorno de todas as alterações atuais. Usada para ler o próximo conjunto de alterações no futuro.

Exemplos

Exemplo 1: solicitação inicial

Aqui está um exemplo de como chamar essa API para estabelecer seu estado local.

Solicitação

Veja um exemplo da solicitação inicial.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta


// 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}"].Delta.GetAsDeltaGetResponseAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


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


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph 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').delta.get()

Resposta

O exemplo a seguir mostra a resposta.

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

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

Essa resposta inclui a primeira página de alterações, e a propriedade @odata.nextLink indica que há mais itens disponíveis no conjunto atual de itens. Seu aplicativo deve continuar a solicitar o valor de URL de @odata.nextLink até que todas as páginas de itens tenham sido recuperadas.

Exemplo 2: última página em um conjunto

Aqui está um exemplo de como chamar essa API para atualizar seu estado local.

Solicitação

Aqui está um exemplo de solicitação após a solicitação inicial.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')


// 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}"].DeltaWithToken("{token}").GetAsDeltaWithTokenGetResponseAsync();



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
token := "{token}"
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").DeltaWithToken(&token).GetAsDeltaWithTokenGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").deltaWithToken("{token}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->deltaWithToken('{token}', )->get()->wait();

Snippet not available


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph 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').delta_with_token("{token}").get()

Resposta

O exemplo a seguir mostra a resposta.

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

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')"
}

Essa resposta indica que o item denominado folder2 foi excluído e que o item file.txt foi adicionado ou modificado entre a solicitação inicial e essa solicitação para atualizar o estado local.

A página final de itens inclui a propriedade @odata.deltaLink , que fornece a URL que pode ser usada posteriormente para recuperar alterações desde o conjunto atual de itens.

Pode haver casos em que o serviço não pode fornecer uma lista de alterações para um determinado token (por exemplo, se um cliente tentar reutilizar um token antigo depois de ter permanecido desconectado por um longo período, ou se o estado do servidor tiver mudado e um novo token for obrigatório). Nesses casos, o serviço retorna um HTTP 410 Gone erro com uma resposta de erro contendo um dos códigos de erro abaixo e um Location cabeçalho contendo um novo nextLink que inicia uma nova enumeração delta do zero. Depois de concluir a enumeração completa, compare os itens retornados com seu estado local e siga estas instruções.

Tipo de erro	Instruções
`resyncChangesApplyDifferences`	Substitua todos os itens locais pela versão do servidor (incluindo exclusões) se tiver certeza de que o serviço estava atualizado com as alterações locais quando você sincronizou pela última vez. Carregar alterações locais que o servidor não conhece.
`resyncChangesUploadDifferences`	Carregue todos os itens locais que o serviço não retornou e carregue todos os arquivos diferentes da versão do servidor (mantendo as duas cópias se você não tiver certeza de qual é mais atualizada).

Exemplo 3: recuperando o deltaLink atual

Em alguns cenários, pode ser útil solicitar o valor do deltaLink atual sem primeiro enumerar todos os itens que já estão na unidade.

Isso poderá ser útil se o seu aplicativo quiser saber apenas sobre as alterações, e não quiser saber sobre os itens existentes. Para recuperar o deltaLink mais recente, chame delta com um parâmetro de cadeia de caracteres de consulta ?token=latest.

Solicitação

GET /me/drive/root/delta?token=latest


// 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}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "latest";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)


requestToken := "latest"

requestParameters := &graphdrives.ItemItemsItemDeltaRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.ItemItemsItemDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "latest";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=latest')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "latest";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "latest"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "latest",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

Resposta

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

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

Exemplo 4: recuperando resultados delta usando um carimbo de data/hora

Em alguns cenários, o cliente pode saber o estado de uma unidade até um momento específico, mas não tem um deltaLink para esse momento. Nesse caso, o cliente pode chamar delta usando um carimbo token de data/hora codificado por URL para o valor do parâmetro de cadeia de caracteres de consulta, por exemplo, ?token=2021-09-29T20%3A00%3A00Z ou '?token=2021-09-29T12%3A00%3A00%2B8%3A00'.

O uso de um carimbo de data/hora no lugar de um token é compatível apenas com OneDrive for Business e Microsoft Office SharePoint Online.

Solicitação

GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z


// 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}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "2021-09-29T20:00:00Z";
});



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)


requestToken := "2021-09-29T20:00:00Z"

requestParameters := &graphdrives.ItemItemsItemDeltaRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.ItemItemsItemDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "2021-09-29T20:00:00Z";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=2021-09-29T20:00:00Z')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "2021-09-29T20:00:00Z";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "2021-09-29T20:00:00Z"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "2021-09-29T20:00:00Z",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

Resposta

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

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

Comentários

O feed delta mostra o estado mais recente de cada item, e não cada alteração. Se um item tiver sido renomeado duas vezes, ele só aparecerá uma vez, com seu nome mais recente.
O mesmo item pode aparecer mais de uma vez em um feed delta, por vários motivos. Você deve usar a última ocorrência que visualizar.
A parentReference propriedade nos itens não incluirá um valor para path. Isso ocorre porque renomear uma pasta não resulta em nenhum descendente da pasta sendo retornado do delta. Ao usar delta, você sempre deve controlar itens por id.
A consulta delta não retornará algumas propriedades DriveItem, dependendo da operação e do tipo de serviço, conforme mostrado nas tabelas a seguir.

OneDrive for Business

Tipo de operação Propriedades omitidas pela consulta delta

Criar/Modificar ctag

Excluir ctag, name

OneDrive (consumidor)

Tipo de operação Propriedades omitidas pela consulta delta

Criar/Modificar n/d

Excluir ctag, size

Tipo de operação	Propriedades omitidas pela consulta delta
Criar/Modificar	`ctag`
Excluir	`ctag`, `name`

Tipo de operação	Propriedades omitidas pela consulta delta
Criar/Modificar	n/d
Excluir	`ctag`, `size`

Hierarquias de permissões de verificação

Por padrão, a resposta da consulta delta inclui informações de compartilhamento para todos os itens na consulta que foram alterados, mesmo que eles herdem suas permissões do pai e não tenham alterações de compartilhamento direto. Isso normalmente resulta em uma chamada de acompanhamento para obter os detalhes de permissão para cada item, em vez de apenas aqueles cujas informações de compartilhamento foram alteradas. Você pode otimizar sua compreensão de como as alterações de permissão acontecem adicionando o cabeçalho Prefer: hierarchicalsharing à sua solicitação de consulta delta.

Quando o cabeçalho é fornecido, as Prefer: hierarchicalsharing informações de compartilhamento são retornadas para a raiz da hierarquia de permissões e itens que têm explicitamente alterações de compartilhamento. Nos casos em que a alteração de compartilhamento é para remover o compartilhamento de um item, você encontra uma faceta de compartilhamento vazia para diferenciar entre itens que herdam de seu pai e aqueles que são exclusivos, mas não têm links de compartilhamento. Você também verá essa faceta de compartilhamento vazia na raiz de uma hierarquia de permissões que não é compartilhada para estabelecer o escopo inicial.

Em muitos cenários de verificação, você pode estar interessado, especificamente, em alterações nas permissões. Para deixar claro na resposta da consulta delta quais alterações são resultados de alterações nas permissões, você pode fornecer o cabeçalho Prefer: deltashowsharingchanges. Quando esse cabeçalho é fornecido, todos os itens que aparecem na resposta de consulta delta devido a alterações de permissão têm a @microsoft.graph.sharedChanged":"True" anotação OData. Esse recurso é aplicável ao SharePoint e ao OneDrive for Business, mas não às contas de consumidor do OneDrive.

Observação

O uso do Prefer: deltashowsharingchanges cabeçalho exige que você use Prefer: deltashowremovedasdeleted e Prefer: deltatraversepermissiongaps. Esses valores de cabeçalho podem ser agrupados em um único cabeçalho: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.
Para processar as permissões corretamente, seu aplicativo precisará solicitar as permissões Sites.FullControl.All .

Para obter mais informações sobre cenários de verificação, consulte Práticas recomendadas para descobrir arquivos e detectar alterações em escala.

Respostas de erros

Além dos erros de ressincronização detalhados acima, confira os detalhes sobre como os erros são retornados em Respostas de Erros.

Usar a consulta delta para acompanhar alterações nos dados do Microsoft Graph Práticas recomendadas para descobrir arquivos e detectar alterações em escala

Comentários

Esta página foi útil?

Last updated on 2026-08-24

driveItem: delta

Permissões

Solicitação HTTP

Parâmetros de função

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: solicitação inicial

Solicitação

Resposta

Exemplo 2: última página em um conjunto

Solicitação

Resposta

Exemplo 3: recuperando o deltaLink atual

Solicitação

Resposta

Exemplo 4: recuperando resultados delta usando um carimbo de data/hora

Solicitação

Resposta

Comentários

Hierarquias de permissões de verificação

Respostas de erros

Conteúdo relacionado

Comentários

Recursos adicionais