Разностный запрос в Microsoft Graph позволяет запрашивать добавления, удаления или обновления поддерживаемых ресурсов с помощью ряда разностных запросов. Для пользователей разностный запрос позволяет обнаруживать изменения, не извлекая весь набор пользователей для сравнения изменений.
Клиенты, выполняющие синхронизацию пользователей с локальным хранилищем профилей, смогут использовать разностный запрос как для первичной полной синхронизации, так и для последующей добавочной синхронизации. Как правило, клиент выполняет начальную полную синхронизацию всех пользователей в клиенте, а затем периодически получает добавочные изменения для пользователей.
Отслеживание изменений пользователей
Отслеживайте изменения пользователей с помощью одного или нескольких запросов GET с помощью функции delta. Запрос GET имеет следующие характеристики:
Функция delta , предопределенная URL-пути.
Маркер состояния (deltatoken или skipToken) из предыдущего вызова разностной функции GET.
Чтобы отслеживать изменения в ресурсе пользователя, создайте запрос и включите функцию delta в виде сегмента URL-адреса.
Совет
/delta — это ярлык для полного имени /microsoft.graph.delta. Запросы, созданные пакетами SDK Для Microsoft Graph, используют полное имя.
Обратите внимание на следующие элементы:
Необязательный параметр $select включен в запрос, чтобы продемонстрировать, как параметры запроса автоматически включаются в последующие запросы. При необходимости параметры запроса должны быть указаны в начальном запросе.
На наличие изменений отслеживаются только свойства, включенные в $select . Если $select параметр не указан, все свойства объекта отслеживаются на наличие изменений.
Исходный запрос не включает маркер состояния. Маркеры состояния используются в последующих запросах.
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname
// 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.Users.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "displayName","givenName","surname" };
});
// 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"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersDeltaWithRequestBuilderGetQueryParameters{
Select: [] string {"displayName","givenName","surname"},
}
configuration := &graphusers.UsersDeltaWithRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().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.users().delta().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"displayName", "givenName", "surname"};
});
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.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(
select = ["displayName","givenName","surname"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.delta.get(request_configuration = request_configuration)
В случае успеха этот метод возвращает код отклика 200 OK и объект коллекции user в тексте отклика. При условии, что весь набор пользователей слишком велик, ответ включает @odata.nextLink маркер состояния в @odata.nextLink параметре .
В этом примере возвращается URL-адрес @odata.nextLink. Это означает, что в текущем сеансе можно получить дополнительные страницы данных. Обратите внимание на в $skiptoken URL-адресе. Параметр $select из исходного запроса кодируется в URL-адресе @odata.nextLink.
Ответ также содержит заметку @removed для пользователя с идентификатором 86462606-fde0-4fc4-9e0c-a20eb73e54c6. Заметка @removed добавляется в следующих сценариях:
Если пользователь удален, элемент содержит заметку: @removed со значением "reason": "changed".
При окончательном удалении пользователя элемент содержит заметку: @removed со значением "reason": "deleted".
Когда пользователь создается или восстанавливается из контейнера удаленных элементов, заметки отсутствуют.
Второй запрос указывает маркер skipToken, полученный из предыдущего отклика. Обратите внимание, что параметр $select закодирован и включен в skipToken.
GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa
// 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
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Users.Delta.WithUrl("https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa").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"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestSkiptoken := "oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa"
requestParameters := &graphusers.UsersDeltaWithRequestBuilderGetQueryParameters{
Skiptoken: &requestSkiptoken,
}
configuration := &graphusers.UsersDeltaWithRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.users.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.users.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa", graphClient.getRequestAdapter());
com.microsoft.graph.users.delta.DeltaGetResponse result = deltaRequestBuilder.get();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.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(
skiptoken = "oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.delta.get(request_configuration = request_configuration)
Отклик содержит другой объект @odata.nextLink с новым значением skipToken, означающим, что доступны дополнительные изменения, которые были отслежены для пользователей. Используйте URL-адрес @odata.nextLink в других запросах, пока URL-адрес @odata.deltaLink (в параметре @odata.deltaLink) не будет возвращен в окончательном отклике, даже если значение является пустым массивом.
GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7
// 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
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Users.Delta.WithUrl("https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7").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"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestSkiptoken := "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7"
requestParameters := &graphusers.UsersDeltaWithRequestBuilderGetQueryParameters{
Skiptoken: &requestSkiptoken,
}
configuration := &graphusers.UsersDeltaWithRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.users.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.users.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7", graphClient.getRequestAdapter());
com.microsoft.graph.users.delta.DeltaGetResponse result = deltaRequestBuilder.get();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.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(
skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.delta.get(request_configuration = request_configuration)
Этот ответ включает @odata.deltaLink URL-адрес, который указывает, что больше нет данных о существующем состоянии пользовательских объектов. В последующих запросах приложение использует URL-адрес @odata.deltaLink, чтобы узнавать о других изменениях пользователей. Сохраните маркер deltatoken и используйте его в URL-адресе последующего запроса, чтобы находить другие изменения пользователей.
deltatoken Используя из последнего ответа, вы получаете изменения (добавления, удаления или обновления) для пользователей с момента последнего запроса.
GET https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460
// 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
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Users.Delta.WithUrl("https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460").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"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestDeltatoken := "oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460"
requestParameters := &graphusers.UsersDeltaWithRequestBuilderGetQueryParameters{
Deltatoken: &requestDeltatoken,
}
configuration := &graphusers.UsersDeltaWithRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Users().Delta().GetAsDeltaGetResponse(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.users.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.users.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460", graphClient.getRequestAdapter());
com.microsoft.graph.users.delta.DeltaGetResponse result = deltaRequestBuilder.get();
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.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(
deltatoken = "oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460",
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.delta.get(request_configuration = request_configuration)
При наличии изменений включается коллекция измененных объектов пользователя. Отклик также содержит ссылку @odata.nextLink (если требуется получить несколько страниц) или @odata.deltaLink. Реализуйте такой же порядок перехода по ссылкам @odata.nextLink, сохраняя заключительную ссылку @odata.deltaLink для последующих вызовов.
Примечание.
При запросе могут происходить задержки репликации для пользователей, которые были недавно созданы, обновлены или удалены. Повторите @odata.nextLink или @odata.deltaLink через некоторое время, чтобы получить последние изменения.