directoryObject: delta
Важно!
API версии /beta
в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Пространство имен: microsoft.graph
Получение вновь созданных, обновленных или удаленных объектов каталога без полного считывания всей коллекции directoryObject. Дополнительные сведения о функции delta см. в разделе Использование разностного запроса для отслеживания изменений в данных Microsoft Graph .
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Разрешения
В следующей таблице показаны разрешения с наименьшими привилегиями, необходимые каждому типу ресурсов при вызове этого API. Дополнительные сведения, включая сведения о том, как выбрать разрешения, см. в статье Разрешения.
Поддерживаемый ресурс | Делегированное (рабочая или учебная учетная запись) | Приложение | Делегированные (личная учетная запись Майкрософт) |
---|---|---|---|
application | Application.Read.All | Application.Read.All | Не поддерживается |
administrativeUnit | AdministrativeUnit.Read.All | AdministrativeUnit.Read.All | Не поддерживается |
device | Device.Read.All | Device.Read.All | Не поддерживается |
directoryRole | RoleManagement.Read.Directory | RoleManagement.Read.Directory | Не поддерживается |
group | Group.Read.All | Group.Read.All | Не поддерживается |
orgContact | OrgContact.Read.All | OrgContact.Read.All | Не поддерживается |
servicePrincipal | Application.Read.All | Application.Read.All | Не поддерживается |
user | User.Read.All | User.Read.All | Не поддерживается |
HTTP-запрос
Отслеживание изменений для коллекции типа объекта каталога.
GET /directoryObjects/delta?$filter=isof('microsoft.graph.application')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.administrativeUnit')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.device')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.directoryRole')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.group')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.orgContact')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.servicePrincipal')
GET /directoryObjects/delta?$filter=isof('microsoft.graph.user')
Отслеживание изменений для объекта каталога.
GET /directoryObjects/delta?$filter=id eq '{id}'
Параметры запросов OData
Этот метод поддерживает необязательные параметры запроса OData для настройки ответа.
- Вы можете использовать параметр запроса
$select
так же, как в любом другом запросе GET, чтобы задать только те свойства, которые необходимы для эффективной работы. Свойство id возвращается всегда. - При фильтрации нескольких объектов, например ,
/directoryObjects/delta/?$filter= id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ffff' or id eq '004d6a07-fe70-4b92-add5-e6e37b8affff'
существует ограничение в 50 выражений фильтра. - Синтаксисы можно объединить
$filter
. Например,$filter=isof('{resource type}') or id eq '{id}'
. Это обеспечивает пересечение объектов, заданных сопоставлением{resource type}
и типом{id}
ресурса .
Заголовки запросов
Имя | Описание |
---|---|
Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Content-Type | application/json |
Prefer | return=minimal Указание этого заголовка с запросом, использующим параметр @odata.deltaLink , приведет к возвращению только свойств объекта, измененных с момента последнего цикла. Необязательно. |
Текст запроса
Не указывайте текст запроса для этого метода.
Отклик
В случае успешного выполнения этот метод возвращает 200 OK
код отклика и объект коллекции directoryObject в тексте отклика. Ответ также включает маркер состояния, который является URL-адресом @odata.nextLink
или URL-адресом @odata.deltaLink
.
Если возвращается URL-адрес
@odata.nextLink
:- Это означает, что в сеансе требуется извлечь больше страниц данных. Приложение продолжает выполнять запросы, используя
@odata.nextLink
URL-адрес, пока URL-адрес не@odata.deltaLink
будет включен в ответ. - Отклик включает тот же набор свойств, что и начальный разностный запрос. Это позволяет фиксировать полное текущее состояние объектов при запуске разностного цикла.
- Это означает, что в сеансе требуется извлечь больше страниц данных. Приложение продолжает выполнять запросы, используя
Если возвращается URL-адрес
@odata.deltaLink
:- Это означает, что больше нет данных о существующем состоянии возвращаемого ресурса. Сохраните и используйте URL-адрес
@odata.deltaLink
, чтобы узнавать об изменениях ресурса в следующем цикле. - Вы можете указать заголовок
Prefer:return=minimal
, чтобы включить в значения отклика только свойства, измененные с момента создания@odata.deltaLink
.
- Это означает, что больше нет данных о существующем состоянии возвращаемого ресурса. Сохраните и используйте URL-адрес
По умолчанию: возвращение свойств, совпадающих с начальным разностным запросом
По умолчанию запросы с использованием @odata.deltaLink
или @odata.nextLink
возвращают те же свойства, которые выбраны в начальном разностном запросе, следующим образом:
- Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
- Если свойство не изменилось, старое значение включается в ответ.
- Если свойство ранее никогда не настраивалось, оно не включается в отклик.
Примечание. При таком поведении просмотр отклика не дает возможность определить, изменилось ли свойство. Кроме того, разностные ответы, как правило, имеют большой размер, так как они содержат все значения свойств, как показано в примере 3.
Альтернатива: возвращение только измененных свойств
Добавление необязательного заголовка запроса prefer:return=minimal
приводит к следующему результату:
- Если свойство изменилось, в отклике содержится новое значение. Сюда включаются свойства с заданным значением NULL.
- Если свойство не изменилось, оно вообще не включается в ответ. (Отличается от поведения по умолчанию.)
Примечание. Заголовок можно добавить в запрос
@odata.deltaLink
в любой момент разностного цикла. Заголовок влияет только на набор свойств, включенный в отклик, и не влияет на способ выполнения разностного запроса. См . пример 4.
Примеры
Пример 1. Получение изменений для коллекции пользователей и групп
Запрос
В следующем примере показан запрос с использованием $filter=isof('{resource type}')
параметра для пользователей и групп. Параметр отсутствует $select
, поэтому набор свойств по умолчанию отслеживается и возвращается.
GET https://graph.microsoft.com/beta/directoryObjects/delta?filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')
Отклик
Ниже приведен пример ответа при использовании @odata.deltaLink
, полученного из инициализации запроса с $filter=isof('{resource type}')
помощью . Обратите внимание на наличие свойства members@delta , которое включает идентификаторы объектов-членов в группе.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects","@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvY1FSSc_",
"value":[
{
"@odata.type": "#microsoft.graph.user",
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
},
{
"@odata.type": "#microsoft.graph.group",
"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",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
"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. Получение коллекции изменений для объекта каталога
Запрос
В следующем примере показан запрос с помощью $filter=id eq '{id}'
параметра . Параметр отсутствует $select
, поэтому набор свойств по умолчанию отслеживается и возвращается.
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=id eq '87d349ed-44d7-43e1-9a83-5f2406dee5bd'
Отклик
Ниже приведен пример ответа при использовании @odata.deltaLink
, полученного из инициализации запроса с $filter=id eq '{id}'
помощью .
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.group",
"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",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
"members@delta": [
{
"@odata.type": "#microsoft.graph.user",
"id": "693acd06-2877-4339-8ade-b704261fe7a0"
},
{
"@odata.type": "#microsoft.graph.user",
"id": "49320844-be99-4164-8167-87ff5d047ace"
}
]
}
]
}
Пример 3. Получение изменений определенных свойств для коллекции пользователей и групп
Запрос
В следующем примере показан первоначальный запрос, выбирая по одному свойству от пользователя и группы для отслеживания изменений с поведением ответа по умолчанию:
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Отклик
Ниже приведен пример ответа при использовании @odata.deltaLink
, полученного в результате инициализации запроса. Оба свойства включены в ответ, и неизвестно, какие из них были изменены с момента @odata.deltaLink
получения.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.user",
"surname": "Vance",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
},
{
"@odata.type": "#microsoft.graph.group",
"displayName":"All Company",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
}
]
}
Пример 4. Получение определенных свойств только в том случае, если они были изменены для коллекции пользователей и групп
Запрос
В следующем примере показан первоначальный запрос, выбирая по одному свойству от пользователя и группы для отслеживания изменений с альтернативным минимальным поведением ответа:
GET https://graph.microsoft.com/beta/directoryObjects/delta?$filter=isof('microsoft.graph.user') or isof('microsoft.graph.group')&$select=microsoft.graph.user/surname,microsoft.graph.group/displayName
Prefer: return=minimal
Отклик
Ниже приведен пример ответа при использовании @odata.deltaLink
, полученного в результате инициализации запроса. Свойство microsoft.graph.user/surname
не включается, что означает, что оно не изменилось с момента последнего разностного запроса; microsoft.graph.group/displayName
оно включается, что означает, что его значение изменилось.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink":"https://graph.microsoft.com/beta/directoryObjects/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjsXoYQp_dpA3cNJWc",
"value": [
{
"@odata.type": "#microsoft.graph.group",
"displayName":"Everyone",
"id": "72052a9a-c466-4995-8210-95a1c1221995",
}
]
}
Связанные материалы
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по