listItem: delta

Namespace: microsoft.graph

Obtenha itens de lista recém-criados, atualizados ou excluídos sem precisar executar uma leitura completa de toda a coleção de itens.

Seu aplicativo começa chamando delta sem parâmetros. O serviço começa a enumerar a hierarquia da lista, retornando páginas de itens e um @odata.nextLink ou um @odata.deltaLink. Seu aplicativo deve continuar chamando com o @odata.nextLink até que você veja um @odata.deltaLink retornado.

Depois de receber todas as alterações, você poderá aplicá-las ao seu estado local. Para marcar alterações no futuro, ligue delta novamente com o @odata.deltaLink da resposta anterior.

O feed delta mostra o estado mais recente de cada item, e não cada alteração. Se um item foi 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.

Os itens com essa propriedade devem ser removidos do estado local.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global	Governo dos EUA L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

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)	Sites.Read.All	Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Aplicativo	Sites.Read.All	Sites.ReadWrite.All

Solicitação HTTP

GET /sites/{siteId}/lists/{listId}/items/delta

Parâmetros de consulta

Na URL da solicitação, você pode incluir o seguinte parâmetro de consulta opcional.

Parâmetro	Tipo	Descrição
token	Cadeia de caracteres	Se não for especificado, enumera o estado atual da hierarquia. Se `latest`, retornará uma resposta vazia com o token delta mais recente. Se um token delta anterior retorna um novo estado desde esse token.

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

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 objetos listItem no corpo da resposta.

Além de uma coleção de objetos listItem , a resposta também inclui uma das propriedades a seguir.

Nome	Valor	Descrição
@odata.nextLink	URL	Uma URL para recuperar a próxima página disponível de alterações, caso haja 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. Use esta propriedade para ler o próximo conjunto de alterações no futuro.

Em alguns casos, o serviço retorna um 410 Gone código de resposta com uma resposta de erro que contém um dos códigos de erro a seguir e um Location cabeçalho que contém uma nova nextLink que inicia uma nova enumeração delta. Isso ocorre quando 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 ficar desconectado por um longo tempo ou se o estado do servidor for alterado e um novo token for necessário.

Depois que a enumeração completa for concluída, compare os itens retornados com seu estado local e siga as instruções com base no tipo de erro.

Tipo de erro	Instruções
resyncChangesApplyDifferences	Substitua todos os itens locais pelas versões do servidor (incluindo exclusões) se tiver certeza de que o serviço estava atualizado com suas 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 itens que diferem das versões do servidor. Guarde as duas cópias se não tiver certeza de qual delas está mais atualizada.

Além dos erros de ressincronização e para obter mais detalhes sobre como os erros são retornados, consulte Tipos de recursos e respostas de erro do Microsoft Graph.

Exemplos

Exemplo 1: solicitação inicial

O exemplo a seguir mostra uma solicitação inicial e como chamar essa API para estabelecer seu estado local.

Solicitação

O exemplo a seguir mostra uma solicitação inicial.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/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.Sites["{site-id}"].Lists["{list-id}"].Items.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.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get()->wait();


Import-Module Microsoft.Graph.Sites

Get-MgSiteListItemDelta -SiteId $siteId -ListId $listId


# 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.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get()

Resposta

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

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
      "id": "2",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "2",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
      "id": "3",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "3",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Exemplo 2: solicitação de última página

O exemplo a seguir mostra uma solicitação que obtém a última página em um conjunto e como chamar essa API para atualizar seu estado local.

Solicitação

O exemplo a seguir mostra uma solicitação após a solicitação inicial.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka


// 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.Sites["{site-id}"].Lists["{list-id}"].Items.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "1230919asd190410jlka";
});



// 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"
	  graphsites "github.com/microsoftgraph/msgraph-sdk-go/sites"
	  //other-imports
)


requestToken := "1230919asd190410jlka"

requestParameters := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "1230919asd190410jlka";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka')
	.get();


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


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

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


$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Sites

Get-MgSiteListItemDelta -SiteId $siteId -ListId $listId -Token "1230919asd190410jlka"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.sites.item.lists.item.items.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 = "1230919asd190410jlka",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get(request_configuration = request_configuration)

Resposta

O exemplo a seguir mostra a resposta que indica que o item nomeado TestItemB.txt foi excluído e o item TestFolder foi adicionado ou modificado entre a solicitação inicial e esta 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.

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2016-03-21T20:01:37Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "id": "3",
      "parentReference": {
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      },
      "deleted": {
        "state": "deleted"
      }
    }
  ],
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Exemplo 3: solicitação de link delta

Em alguns cenários, talvez você queira solicitar o valor atual deltaLink sem primeiro enumerar todos os itens da lista. Isso pode ser útil se o seu aplicativo quiser saber apenas sobre alterações e não precisar saber sobre itens existentes. Para recuperar o mais recente deltaLink, chame delta com o parâmetro ?token=latestde cadeia de caracteres de consulta .

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/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.Sites["{site-id}"].Lists["{list-id}"].Items.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"
	  graphsites "github.com/microsoftgraph/msgraph-sdk-go/sites"
	  //other-imports
)


requestToken := "latest"

requestParameters := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphsites.ItemListsItemItemsDeltaRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Sites().BySiteId("site-id").Lists().ByListId("list-id").Items().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.sites().bySiteId("{site-id}").lists().byListId("{list-id}").items().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "latest";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=latest')
	.get();


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


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

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


$result = $graphServiceClient->sites()->bySiteId('site-id')->lists()->byListId('list-id')->items()->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Sites

Get-MgSiteListItemDelta -SiteId $siteId -ListId $listId -Token "latest"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.sites.item.lists.item.items.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.sites.by_site_id('site-id').lists.by_list_id('list-id').items.delta.get(request_configuration = request_configuration)

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "value": [ ],
  "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Comentários

Esta página foi útil?

Last updated on 2026-08-24

listItem: delta

Permissões

Solicitação HTTP

Parâmetros de consulta

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: solicitação inicial

Solicitação

Resposta

Exemplo 2: solicitação de última página

Solicitação

Resposta

Exemplo 3: solicitação de link delta

Solicitação

Resposta

Conteúdo relacionado

Comentários

Recursos adicionais