сайт: delta

Получение только что созданных, обновленных или удаленных сайтов без необходимости полного считывания всего семейства сайтов.

Вызов разностной функции для сайтов аналогичен запросу GET, за исключением того, что, применяя маркеры состояния в одном или нескольких из этих вызовов, можно запросить добавочные изменения на сайтах. Это позволяет поддерживать и синхронизировать локальное хранилище сайтов пользователя без необходимости каждый раз получать все сайты с сервера. Приложение вызывает API без указания параметров. Служба начинает перечисление сайтов и возвращает страницы изменений для этих сайтов в сопровождении @odata.nextLink или @odata.deltaLink. Приложение должно продолжать выполнять вызовы с помощью @odata.nextLink , пока в ответе не появится @odata.deltaLink .

После получения всех изменений их можно применить к местному штату. Чтобы отслеживать будущие изменения, вызовите разностный API с помощью @odata.deltaLink в предыдущем ответе.

Все ресурсы, помеченные как удаленные, должны быть удалены из локального состояния.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	❌	❌	❌

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	Sites.Read.All	Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Для приложений	Sites.Read.All	Sites.ReadWrite.All

HTTP-запрос

GET /sites/delta

Параметры запроса

В URL-адрес запроса можно включить следующий необязательный параметр запроса.

Параметр	Тип	Описание
token	String	Если значение равно latest, вызов возвращает пустой ответ с последним разностным маркером. Если значение является предыдущим разностным маркером, вызов возвращает новое состояние с момента выдачи этого маркера.

Этот метод также поддерживает $selectпараметры запроса ,$expandи $top OData для настройки ответа.

Заголовки запросов

Заголовок	Значение
Авторизация	Bearer {token}. Обязательно.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

При успешном выполнении этот метод возвращает код отклика 200 OK и коллекцию объектов site в тексте отклика.

Помимо семейства объектов сайта , ответ также включает одно из следующих свойств.

Имя	Значение	Описание
@odata.nextLink	URL-адрес	URL-адрес для получения следующей доступной страницы изменений, если в текущем наборе есть дополнительные изменения.
@odata.deltaLink	URL-адрес	URL-адрес, возвращаемый вместо @odata.nextLink после возврата всех текущих изменений. Используйте это свойство для чтения следующего набора изменений в будущем.

В некоторых случаях служба возвращает 410 Gone код ответа с ответом об ошибке, содержащим один из следующих кодов ошибок, и Location заголовок, содержащий новый nextLink , который запускает новое разностное перечисление. Это происходит, когда служба не может предоставить список изменений для заданного маркера; Например, если клиент пытается повторно использовать старый маркер после длительного отключения или состояние сервера изменилось и требуется новый маркер.

После завершения полного перечисления сравните возвращенные сайты с локальным состоянием и следуйте инструкциям на основе типа ошибки.

Тип "ошибка"	Инструкции
resyncChangesApplyDifferences	Замените все локальные сайты версиями с сервера (включая удаление), если вы уверены, что служба была обновлена с локальными изменениями при последней синхронизации. Отправьте все локальные изменения, не загруженные на сервер.
resyncChangesUploadDifferences	Отправьте все локальные сайты, которые служба не вернула, и все сайты, отличные от версий сервера. Сохраните обе копии, если вы не знаете, какая из них является более актуальной.

Дополнительные сведения см. в разделе Ответы на ошибки Microsoft Graph и типы ресурсов.

Примеры

Пример 1. Исходный запрос

В следующем примере показан первоначальный запрос и способ вызова этого API для определения локального состояния.

Запрос

В следующем примере показан начальный запрос.

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

CLI

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

В следующем примере показан ответ, включающий первую страницу изменений и свойство @odata.nextLink , указывающее, что в текущем наборе сайтов больше нет доступных сайтов. Приложение должно продолжать запрашивать значение URL-адреса @odata.nextLink , пока не будут извлечены все страницы сайтов.

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

Пример 2. Запрос последней страницы

В следующем примере показан запрос, который обращается к последней странице в наборе, и как вызвать этот API для обновления локального состояния.

Запрос

В следующем примере показан запрос после первоначального запроса.

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

CLI

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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";
});

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta -Token "1230919asd190410jlka" 

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

В следующем примере показан ответ, указывающий, что сайт с именем All Company был удален между первоначальным запросом и этим запросом на обновление локального состояния.

Последняя страница сайтов содержит свойство @odata.deltaLink , которое предоставляет URL-адрес, который можно использовать позже для получения изменений с текущего набора сайтов.

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": {}
        }
    ]
}

Пример 3. Запрос разностной ссылки

В некоторых сценариях может потребоваться запросить текущее deltaLink значение без предварительного перечисления всех сайтов, списков и веб-сайтов. Это может быть полезно, если вашему приложению нужно только знать об изменениях и не нужно знать о существующих сайтах. Чтобы получить последнюю версию deltaLink, вызовите delta с параметром ?token=latestстроки запроса .

Примечание: Если вы хотите сохранить полное локальное представление ресурсов, необходимо использовать delta для начального перечисления. Только с помощью функции delta можно гарантировать, что считываются все необходимые данные.

Запрос

Ниже показан пример запроса.

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

CLI

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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";
});

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Sites

Get-MgSiteDelta -Token "latest" 

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по 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)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Ниже показан пример отклика.

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

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

См. также

• Отслеживание изменений данных Microsoft Graph с помощью запроса изменений
• Рекомендации по обнаружению файлов и определению изменений в масштабе