site: delta

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

Uma chamada de função delta para sites é semelhante a uma solicitação GET, exceto que, aplicando adequadamente tokens de estado em uma ou mais dessas chamadas, você pode consultar alterações incrementais nos sites. Ele permite que você mantenha e sincronize um repositório local dos sites de um usuário sem precisar buscar todos os sites do servidor todas as vezes. O aplicativo chama a API sem especificar parâmetros. O serviço começa a enumerar sites e retorna páginas de alterações nesses sites, acompanhado de um @odata.nextLink ou um @odata.deltaLink. Seu aplicativo deve continuar fazendo chamadas usando o @odata.nextLink até que haja um @odata.deltaLink na resposta.

Depois de receber todas as alterações, você pode aplicá-las ao seu estado local. Para monitorar alterações futuras, chame a API delta usando o @odata.deltaLink na resposta anterior.

Todos os recursos marcados como excluídos devem ser removidos do seu estado local.

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

Serviço global	Governo dos EUA L4	GOVERNO DOS EUA L5 (DOD)	China operada pela 21Vianet
✅	❌	❌	❌

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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 privilegiadas mais altas
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/delta

Parâmetros de consulta

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

Parâmetro	Tipo	Descrição
token	Cadeia de caracteres	Se o valor for latest, a chamada retornará uma resposta vazia com o token delta mais recente. Se o valor for um token delta anterior, a chamada retornará o novo estado desde que esse token foi emitido.

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

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	{token} de portador. Obrigatório.

Corpo da solicitação

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

Resposta

Se bem sucedido, este método retorna um 200 OK código de resposta e uma coleção de objetos de lista no corpo da resposta.

Além da coleção de objetos do site , 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 se houver mais alterações no conjunto atual.
@odata.deltaLink	URL	Uma URL retornada em vez de @odata.nextLink depois que todas as alterações atuais forem retornadas. Use essa 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 seguintes códigos de erro e um Location cabeçalho que contém um novo nextLink que inicia uma nova enumeração delta. Ele 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 ser 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 sites 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 sites locais pelas versões do servidor (incluindo exclusões) se você tiver certeza de que o serviço estava atualizado com suas alterações locais quando você sincronizado pela última vez. Carregar alterações locais que o servidor não conhece.
resyncChangesUploadDifferences	Carregue todos os sites locais que o serviço não retornou e carregue nenhum site diferente das versões do servidor. Mantenha as duas cópias se não tiver certeza de qual delas está mais atualizada.

para obter mais informações, confira Respostas de erro e tipos de recurso do Microsoft Graph.

Exemplos

Exemplo 1: solicitação inicial

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

Solicitação

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

HTTP

GET https://graph.microsoft.com/v1.0/sites/delta

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.Sites.Delta.GetAsDeltaGetResponseAsync();

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc sites delta get

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

Ir

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



delta, err := graphClient.Sites().Delta().GetAsDeltaGetResponse(context.Background(), nil)

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

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.sites().delta().get();

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/sites/delta')
	.get();

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


$result = $graphServiceClient->sites()->delta()->get()->wait();

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

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta

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

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.sites.delta.get()

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

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 sites disponíveis no conjunto atual de sites. Seu aplicativo deve continuar solicitando o valor de URL de @odata.nextLink até que todas as páginas de sites sejam recuperadas.

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

{
  "value": [
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,712a596e-90a1-49e3-9b48-bfa80bee8740",
      "name": "teamSiteA"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteB"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteC"
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}

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

O exemplo a seguir mostra uma solicitação que acessa 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.

HTTP

GET https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka

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.Sites.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "1230919asd190410jlka";
});

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc sites delta get

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

Ir

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestToken := "1230919asd190410jlka"

requestParameters := &graphsites.SitesDelta()RequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphsites.SitesDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Sites().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

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

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.sites().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "1230919asd190410jlka";
});

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/sites/delta?token=1230919asd190410jlka')
	.get();

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

PHP

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


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

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


$result = $graphServiceClient->sites()->delta()->get($requestConfiguration)->wait();

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

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta -Token "1230919asd190410jlka" 

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

Python

from msgraph import GraphServiceClient
from msgraph.generated.sites.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "1230919asd190410jlka",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.sites.delta.get(request_configuration = request_configuration)

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

Resposta

O exemplo a seguir mostra a resposta que indica que o site nomeado All Company foi excluído entre a solicitação inicial e essa solicitação para atualizar o estado local.

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?$deltatoken=b2vm2fSuZ-V_1Gdq4ublGPD4lReifRNHYMGxkFf0yz2fTqr9U6jMyWv8hihThODJCO_5I7JbpAFLQAIOUzYXhCPl0jlQdjTC1o24iBe81xQyAWJOiP3q1xyMKjlfZUawWok3Njc_LIrrSgrdSydhsVCL6XYpRkYGJ9JDYxFMiJw2vUs1QC_S0cW6hqYQnOimeA918dQZwD8pJI9oUJryV2Ow-7Dj9p18p1I6pFg044k.xipVdgMKlOFIlXzPipsKzlFJbYUTD1sGiFiPe7uZA7Q",
    "value": [
        {
            "createdDateTime": "2024-03-11T02:36:04Z",
            "name": "All Company",
            "displayName": "All Company",
            "isPersonalSite": false,
            "id": "bd565af7-7963-4658-9a77-26e11ac73186",
            "root": {}
        }
    ]
}

Exemplo 3: solicitação de link delta

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

Nota: Se você quiser manter uma representação local completa dos recursos, deverá usar delta para a enumeração inicial. Usar o delta é a única maneira de garantir que você leu todos os dados de que precisa.

Solicitação

O exemplo a seguir mostra uma solicitação.

HTTP

GET https://graph.microsoft.com/v1.0/sites/delta?token=latest

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

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc sites delta get

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

Ir

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestToken := "latest"

requestParameters := &graphsites.SitesDelta()RequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphsites.SitesDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Sites().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

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

Java

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.sites().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "latest";
});

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

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

PHP

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


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

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


$result = $graphServiceClient->sites()->delta()->get($requestConfiguration)->wait();

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

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta -Token "latest" 

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

Python

from msgraph import GraphServiceClient
from msgraph.generated.sites.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "latest",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.sites.delta.get(request_configuration = request_configuration)

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

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/delta?token=1230919asd190410jlka"
}

Confira também

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