Получение добавочных изменений для групп

Статья
01/14/2024

Разностный запрос в Microsoft Graph позволяет запрашивать добавления, удаления или обновления поддерживаемых ресурсов с помощью ряда разностных запросов. Для групп дельта-запрос позволяет обнаруживать изменения, не извлекая весь набор групп для сравнения изменений.

Клиенты, выполняющие синхронизацию групп с локальным хранилищем профилей, смогут использовать дельта-запрос как для первичной полной синхронизации, так и для добавочной синхронизации. Как правило, клиент выполняет начальную полную синхронизацию всех групп в клиенте, а затем периодически получает добавочные изменения в группы.

Отслеживание изменений в группах

Отслеживайте изменения пользователей с помощью одного или нескольких запросов GET с помощью функции delta. Запрос GET имеет следующие характеристики:

Функция delta , предопределенная URL-пути.
Маркер состояния (deltatoken или skiptoken) из предыдущего вызова разностной функции GET.
[Необязательно] Любые поддерживаемые параметры запроса

Пример

В этой статье показана серия примеров запросов для отслеживания изменений в группах:

Исходный запрос и ответ
Запрос nextLink и отклик
Последний запрос nextLink и отклик
Запрос deltaLink и отклик deltaLink

Исходный запрос

Чтобы отслеживать изменения в групповом ресурсе, сделайте запрос и включите дельта-функцию в виде сегмента URL-адреса.

Совет

/delta — это ярлык для полного имени /microsoft.graph.delta. Запросы, созданные пакетами SDK Для Microsoft Graph, используют полное имя.

Обратите внимание на следующие элементы:

Необязательный параметр $select включен в запрос, чтобы продемонстрировать, как параметры запроса автоматически включаются в последующие запросы. При необходимости параметры запроса должны быть указаны в начальном запросе.
- На наличие изменений отслеживаются только свойства, включенные в $select . Если $select параметр не указан, все свойства объекта отслеживаются на наличие изменений.
Необязательный параметр запроса $select также используется, чтобы показать, как участников групп можно получать вместе с объектами групп. Эта возможность позволяет отслеживать изменения членства, например при добавлении или удалении пользователей из групп.
Исходный запрос не включает маркер состояния. Маркеры состояния используются в последующих запросах.

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members


// 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.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","members" };
});



mgc groups delta get --select "displayName,description,members"



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

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","members"},
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "members"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.select('displayName,description,members')
	.get();


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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","description","members"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,members"


from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","members"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Исходный отклик

В случае успешного выполнения этот метод возвращает код отклика 200 OK и объект коллекции group в тексте отклика. Если весь набор групп слишком велик, чтобы поместиться в один ответ, @odata.nextLink включается маркер состояния.

В этом примере возвращается URL-адрес @odata.nextLink. Это означает, что в текущем сеансе можно получить дополнительные страницы данных. Обратите внимание на в $skiptoken URL-адресе. Параметр $select из исходного запроса кодируется в URL-адресе @odata.nextLink.

Свойство members@delta входит в группу All Company и содержит двух текущих участников группы. Sg-HR не содержит это свойство, так как в группе нет членов.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"All Company",
      "description":"This is the default group for everyone in the network",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"sg-HR",
      "description":"All HR personnel",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

Запрос nextLink

Во втором запросе используется ссылка @odata.nextLink из предыдущего запроса, содержащая маркер skiptoken. Обратите внимание, что параметр $select не виден, так как он закодирован и включен в маркер.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ


// 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.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ").GetAsDeltaGetResponseAsync();



mgc groups delta get



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


requestSkiptoken := "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ"

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.skiptoken('pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ')
	.get();


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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Skiptoken "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ"


from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Ответ nextLink

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mark 8 Project Team",
      "description":"Mark 8 Project Team",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"Sales and Marketing",
      "description":"Sales and Marketing",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

Последний запрос nextLink

Третий запрос использует последний @odata.nextLink, полученный из последнего запроса на синхронизацию.

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_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.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7").GetAsDeltaGetResponseAsync();



mgc groups delta get



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


requestSkiptoken := "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7"

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.skiptoken('ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7')
	.get();


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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->skiptoken = "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Skiptoken "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7"


from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		skiptoken = "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Последний отклик nextLink

Если возвращается URL-адрес @odata.deltaLink, это означает, что больше нет данных о текущем состоянии объектов группы. В последующих запросах приложение использует URL-адрес @odata.deltaLink, чтобы узнавать о других изменениях групп. Сохраните маркер deltatoken и используйте его в URL-адресе последующего запроса, чтобы находить другие изменения в группах.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"All Employees",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"Remote living",
      "description":"Remote living",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

Запрос deltaLink

@odata.deltaLink Используя из последнего ответа, вы получаете изменения (добавления, удаления или обновления) в группах с момента последнего запроса. К таким изменениям относятся:

создание объектов групп;
удаление объектов групп;
Группировать объекты, для которых изменено отслеживаемое свойство (например, обновлено displayName).
Группирование объектов, для которых были добавлены или удалены объекты-члены.

GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw


// 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.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw").GetAsDeltaGetResponseAsync();



mgc groups delta get



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


requestDeltatoken := "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw"

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Deltatoken: &requestDeltatoken,
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();


const options = {
	authProvider,
};

const client = Client.init(options);

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


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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->deltatoken = "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Deltatoken "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw"


from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		deltatoken = "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Отклик deltaLink

Ответ deltaLink с пустым массивом

Если изменений нет, @odata.deltaLink возвращается без результатов — свойство value является пустым массивом. Обязательно замените предыдущую ссылку в приложении для использования в последующих запросах.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

Ответ deltaLink с изменениями

При наличии изменений включается коллекция измененных групп. Отклик также содержит ссылку @odata.nextLink (если требуется получить несколько страниц) или @odata.deltaLink. Реализуйте такой же порядок перехода по ссылкам @odata.nextLink, сохраняя заключительную ссылку @odata.deltaLink для последующих вызовов.

Примечание.

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

Некоторые моменты, которые следует отметить в примере ответа:

Объекты возвращаются с тем же набором свойств, который изначально указывался с помощью параметра запроса $select.
Включаются как измененные, так и неизменяемые свойства: свойство description имеет новое значение, а свойство displayName не изменилось.
members@delta содержит следующие изменения членства в группе.
- Пользователь с идентификатором 632f6bb2-3ec8-4c1f-9073-0027a8c6859 был удален из группы, удалив его членство, как описано в свойстве @removed . Объекты, удаленные из группы путем удаления объекта, не обнаруживаются разностными запросами.
- Второй пользователь с идентификатором 37de1ae3-408f-4702-8636-20824abda004 был добавлен в группу.

Объект группы может содержать заметку @removed в следующих сценариях:

При удалении группы (группы Microsoft 365) элемент содержит заметку: @removed со значением "reason": "changed".
При окончательном удалении группы (группы безопасности или безвозвратного удаления группы Microsoft 365) элемент содержит заметку со @removed значением "reason": "deleted".
Заметок о создании или восстановлении группы не существует.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

Постраничный переход в случае списка членов большой группы

Свойство members@delta включается в объекты групп по умолчанию, если $select параметр запроса не указан или если $select=members параметр явно указан. Для групп с большим количеством участников возможно, что все участники не смогут поместиться в один ответ. Реализуйте следующий шаблон в таких случаях.

Примечание.

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

Предположим, что выполняется следующий разностный запрос (либо для регистрации полного исходного состояния групп, либо для получения изменений):

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members


// 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.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","members" };
});



mgc groups delta get --select "displayName,description,members"



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

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","members"},
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
delta, err := graphClient.Groups().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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "members"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.select('displayName,description,members')
	.get();


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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","description","members"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,members"


from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","members"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

Microsoft Graph может возвращать ответ, содержащий только один объект группы с большим списком членов в свойстве members@delta :

Первая страница

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}

При выполнении @odata.nextLinkдействия может появиться ответ, содержащий тот же объект группы. Возвращаются те же значения свойств, members@delta но теперь свойство содержит другой список пользователей.

Вторая страница

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}

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

Для корректной реализации этого порядка следуйте приведенным ниже рекомендациям.

Всегда переходите по ссылке @odata.nextLink и локально выполняйте объединение для состояния каждой группы. По мере получения откликов для одной и той же группы составляйте полный список членов в приложении.
Не предполагайте определенную последовательность ответов. Предполагайте, что одна и та же группа может встречаться в любом месте последовательности @odata.nextLink, и обрабатывайте этот случай в логике объединения.

Обзор запросов изменений Microsoft Graph.

Поделиться через

Получение добавочных изменений для групп

Отслеживание изменений в группах

Пример

Исходный запрос

Исходный отклик

Запрос nextLink

Ответ nextLink

Последний запрос nextLink

Последний отклик nextLink

Запрос deltaLink

Отклик deltaLink

Ответ deltaLink с пустым массивом

Ответ deltaLink с изменениями

Постраничный переход в случае списка членов большой группы

Обратная связь

Обратная связь

Дополнительные ресурсы

Поделиться через

Получение добавочных изменений для групп

Отслеживание изменений в группах

Пример

Исходный запрос

Исходный отклик

Запрос nextLink

Ответ nextLink

Последний запрос nextLink

Последний отклик nextLink

Запрос deltaLink

Отклик deltaLink

Ответ deltaLink с пустым массивом

Ответ deltaLink с изменениями

Постраничный переход в случае списка членов большой группы

Связанные материалы

Обратная связь

Обратная связь

Дополнительные ресурсы