group: delta

Пространство имен: microsoft.graph

Получение только что созданных, обновленных или удаленных групп, включая изменения членства в группах, без необходимости полного считывания всей коллекции групп. Дополнительные сведения см . в разделе Использование разностного запроса для отслеживания изменений в данных Microsoft Graph .

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

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

Разрешения

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

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

HTTP-запрос

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

GET /groups/delta

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

При отслеживании изменений в группах выполняется цикл из одного или нескольких вызовов разностных функций. Если вы используете параметры запроса, отличные от $deltatoken и $skiptoken, их необходимо указать в начальном запросе delta. Microsoft Graph автоматически кодирует указанные параметры в маркере, входящем в состав URL-адреса @odata.nextLink или @odata.deltaLink, включенного в отклик.

Параметры запроса нужно указать только один раз в первом запросе.

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

Параметр запроса	Тип	Описание
$deltatoken	string	Маркер состояния, возвращенный в @odata.deltaLink URL-адресе предыдущего вызова разностной функции для той же коллекции групп, что указывает на завершение этого раунда отслеживания изменений. Сохраните URL-адрес @odata.deltaLink с этим токеном и примените его в первом запросе следующего цикла отслеживания изменений для этой коллекции.
$skiptoken	строка	Этот токен состояния возвращается в URL-адресе @odata.nextLink предыдущего вызова функции delta и указывает, что из коллекции групп получены не все изменения.

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

Этот метод поддерживает необязательные параметры запроса OData для настройки ответа.

• Вы можете использовать параметр запроса $select так же, как в любом другом запросе GET, чтобы задать только те свойства, которые необходимы для эффективной работы. Свойство id возвращается всегда.
• Вы можете использовать для $select=members получения изменений членства. Вы можете дополнительно отслеживать другие изменения, такие как владение и многое другое, выбрав любое отношение группы типа directoryObject collection.
• Существует ограниченная поддержка :$filter
  • Единственное поддерживаемое выражение $filter предназначено для отслеживания изменений в определенном объекте: $filter=id+eq+{value}. Допускается фильтрация нескольких объектов. Например, https://graph.microsoft.com/v1.0/groups/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'. Максимальное количество фильтруемых объектов: 50.

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

Имя	Описание
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type	application/json
Prefer	return=minimal Указание этого заголовка с запросом, использующим параметр @odata.deltaLink, приведет к возвращению только свойств объекта, измененных с момента последнего цикла. Необязательно.

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

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

Отклик

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

• Если возвращается URL-адрес @odata.nextLink:

  • Это означает, что в сеансе требуется извлечь больше страниц данных. Приложение продолжает отправлять запросы, используя URL-адрес @odata.nextLink, пока в отклик не будет включен URL-адрес @odata.deltaLink.
  • Отклик включает тот же набор свойств, что и начальный разностный запрос. Это позволяет фиксировать полное текущее состояние объектов при запуске разностного цикла.

• Если возвращается URL-адрес @odata.deltaLink:

  • Это означает, что больше нет данных о существующем состоянии возвращаемого ресурса. Сохраните и используйте URL-адрес @odata.deltaLink, чтобы узнавать об изменениях ресурса в следующем цикле.
  • Вы можете указать заголовок Prefer:return=minimal, чтобы включить в значения отклика только свойства, измененные с момента создания @odata.deltaLink.

По умолчанию: возвращение свойств, совпадающих с начальным разностным запросом

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

• Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
• Если свойство не изменилось, старое значение включается в ответ.
• Если свойство ранее никогда не настраивалось, оно не включается в отклик.

Примечание. При таком поведении просмотр отклика не дает возможность определить, изменилось ли свойство. Кроме того, разностные ответы, как правило, имеют большой размер, так как они содержат все значения свойств, как показано во втором примере ниже.

Альтернатива: возвращение только измененных свойств

Добавление необязательного заголовка запроса prefer:return=minimal приводит к следующему результату:

• Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
• Если свойство не изменилось, оно вообще не включается в ответ. (Отличается от поведения по умолчанию.)

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

Пример

Запрос 1

Ниже показан пример запроса. Параметр отсутствует $select , поэтому набор свойств по умолчанию отслеживается и возвращается.

HTTP

GET https://graph.microsoft.com/v1.0/groups/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.Groups.Delta.GetAsDeltaGetResponseAsync();

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

CLI

mgc groups delta get

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

Go

// 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.Groups().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.groups().delta().get();

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

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

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta

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

Python

# 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.groups.delta.get()

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

Отклик 1

Ниже приведен пример ответа при использовании @odata.deltaLink , полученного в результате инициализации запроса.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

Обратите внимание на наличие свойства 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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
  "value":[
    {
      "createdDateTime":"2021-03-12T10:36:14Z",
      "description":"This is the default group for everyone in the network",
      "displayName":"All Company",
      "groupTypes": [
        "Unified"
      ],
      "mail": "allcompany@contoso.com",
      "members@delta": [
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "693acd06-2877-4339-8ade-b704261fe7a0"
        },
        {
          "@odata.type": "#microsoft.graph.user",
          "id": "49320844-be99-4164-8167-87ff5d047ace"
        }
      ]
    }
  ]
}

Запрос 2

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

HTTP

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

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

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

CLI

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

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

Go

// 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","mailNickname"},
}
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)

Подробнее о том, как добавить 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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "mailNickname"};
});

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

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

PHP

<?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","mailNickname"];
$requestConfiguration->queryParameters = $queryParameters;


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

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

PowerShell

Import-Module Microsoft.Graph.Groups

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

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

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.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","description","mailNickname"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

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

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

Отклик 2

Ниже приведен пример ответа при использовании @odata.deltaLink , полученного в результате инициализации запроса. Все три свойства включены в ответ, и неизвестно, какие из них были изменены с момента @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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "All Company",
      "description": null,
      "mailNickname": "allcompany@contoso.com"
    }
  ]
}

Запрос 3

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

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,mailNickname
Prefer: return=minimal

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.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","mailNickname" };
	requestConfiguration.Headers.Add("Prefer", "return=minimal");
});

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

CLI

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

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

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "return=minimal")

requestParameters := &graphgroups.GroupsDeltaWithRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","mailNickname"},
}
configuration := &graphgroups.GroupsDeltaWithRequestBuilderGetRequestConfiguration{
	Headers: headers,
	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)

Подробнее о том, как добавить 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.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "mailNickname"};
	requestConfiguration.headers.add("Prefer", "return=minimal");
});

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.header('Prefer','return=minimal')
	.select('displayName,description,mailNickname')
	.get();

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

PHP

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


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

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$headers = [
		'Prefer' => 'return=minimal',
	];
$requestConfiguration->headers = $headers;

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


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

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

PowerShell

Import-Module Microsoft.Graph.Groups

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

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

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.groups.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","description","mailNickname"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("Prefer", "return=minimal")


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

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

Отклик 3

Ниже приведен пример ответа при использовании @odata.deltaLink , полученного в результате инициализации запроса. Свойство mailNickname не включается, что означает, что оно не изменилось с момента последнего разностного запроса; displayName и description включаются, что означает, что их значения изменились.

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=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
  "value": [
    {
      "displayName": "Everyone",
      "description": null
    }
  ]
}

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

• Отслеживание изменений в данных Microsoft Graph с помощью разностного запроса.
• Получение добавочных изменений для групп.