Разностный запрос | Общие понятия API Graph
Область применения: API Graph | Azure Active Directory
В этом разделе обсуждается функция разностного запроса API Graph Azure AD. Разностный запрос возвращает все изменения, внесенные в указанные сущности в период между двумя последовательными запросами. Например, при выполнении разностного запроса через час после предыдущего разностного запроса возвращаются только изменения, внесенные в течение этого часа. Эта функциональность особенно полезна при синхронизации данных каталога клиента с хранилищем данных приложения.
Чтобы выполнить разностный запрос для каталога клиента, ваше приложение должно быть авторизовано клиентом. Дополнительные сведения см. в статье Интеграция приложений с Azure Active Directory.
Важно!
Для доступа к ресурсам Azure Active Directory мы настоятельно рекомендуем использовать Microsoft Graph вместо API Azure AD Graph.Теперь наши усилия сфокусированы на разработке Microsoft Graph; дальнейшее продвижение API Azure AD Graph мы не планируем.Есть очень мало сценариев, в которых по-прежнему можно использовать API Azure AD Graph. Дополнительные сведения об этом см. в записи блога в центре разработчиков Office, где сравниваются решения Microsoft Graph и Azure AD Graph.
Разностные запросы
В этом разделе описываются разностные запросы. Всем запросам требуются следующие компоненты:
Действительный URL-адрес запроса, включая конечную точку Graph для клиента и применимые параметры строки запроса.
Заголовок авторизации, включая действительный маркер доступа, выданный Azure Active Directory. Дополнительную информацию о проверке подлинности в API Graph см. в статье Сценарии проверки подлинности для Azure AD.
URL-адрес разностного запроса
Далее показан формат URL-адреса для разностного запроса; квадратные скобки [] обозначают необязательные элементы.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
Этот URL-адрес состоит из иерархической сегментов, за которыми следует ряд параметров строки запроса в виде пар "ключ-значение".
URL-адрес: иерархические сегменты
| Сегмент | Описание |
|---|---|
| tenantId | Уникальный идентификатор клиента, для которого должен выполняться запрос. Обычно это один из проверенных доменов (свойство verifiedDomains) клиента, но это также может быть и идентификатор объекта клиента (свойство objectId). Указывается без учета регистра. |
| resourceSet | Определенный набор ресурсов клиента, для которого должен выполняться этот запрос. Определяет, какие ресурсы возвращаются в ответе на запрос. Поддерживаемые значения: directoryObjects, users, contacts и groups. В значениях различается регистр символов. |
URL-адрес: параметры строки запроса
| Параметр | Описание |
|---|---|
| api-version | Указывает версию API Graph , для которой формируется запрос. Обязательный параметр. Начиная с версии 1.5, значение этого параметра выражается числовым номером версии, например: api-version=1.5. Для предыдущих версий значение является строкой в формате ГГГГ-ММ-ДД, например: api-version=2013-04-05. (Заменяет используемый в предыдущей версии API Graph заголовок x-ms-dirapi-data-contract-version.) |
| deltaLink | Маркер возвращается в свойствах deltaLink или nextLink последнего ответа. Является обязательным, но будет пустым при первом запросе. (Заменяет параметр строки запроса skipToken в предыдущей версии API Graph.) |
| $filter | Указывает, какие типы сущностей должны быть включены в ответ. Необязательный параметр. Поддерживаемые типы сущностей: User (пользователь), Group (группа) и Contact (контакт). Допустимо только в случае, если <resourceSet> имеет значение directoryObjects; в противном случае <resourceSet< переопределяет фильтр. Например, если <resourceSet> имеет значение users, а также указан параметр $filter, независимо от значения фильтра будут возвращаться только изменения для пользователей. Если <resourceSet> имеет значение directoryObjects, а параметр $filter не задан, возвращаются изменения для всех поддерживаемых типов сущностей (User, Group и Contact). Чтобы указать один тип сущности, используйте одно из следующих выражений:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Заменяет параметр строки запроса objectScope в предыдущей версии API Graph.) Важно. Начиная с версии 1.5, пространство имен в API Graph изменилось с Microsoft.WindowsAzure.ActiveDirectory на Microsoft.DirectoryServices. В более ранних версиях API Graph по-прежнему используется предыдущее пространство имен, например $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Указывает, какие свойства должны быть включены в ответ. Если параметр *$select^ не задан, включаются все свойства. Свойства могут быть указаны полностью или без уточнения. Несколько свойств разделяются запятыми.
|
Примечание. Пары "ключ-значение" в строке запроса чувствительны к регистру, однако их порядок не имеет значения.
Далее представлен пример простейшего разностного запроса. Он используется во время начальной синхронизации.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Далее приведен пример последующего запроса.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Ответы на разностные запросы
В этом разделе описывается содержимое ответа на разностный запрос, возвращаемого при выполнении разностного запроса. Следующий список описывает содержимое ответа:
От 0 до 200 сущностей DirectoryObject, каждая из которых содержит изменения для конкретного объекта User, Group или Contact.
От 0 до 3000 сущностей DirectoryLinkChange, каждая из которых содержит изменения для конкретной связи member или manager.
Свойство deltaLink или nextLink. В любом случае его значение является чувствительной к регистру и закодированной в URL-адресе строкой, содержащей сведения о состоянии для набора изменений каталога, которые были возвращены клиенту, с учетом остальных произошедших в каталоге изменений. Эта строка (или маркер) должна быть включена в параметр строки запроса deltaLink в следующем разностном запросе.
Если возвращается свойство deltaLink, значит, изменений каталога, которые приложение может синхронизировать после этого ответа, не осталось. В соответствии с собственными требованиями приложение может ожидать некоторое заранее заданное время перед выдачей следующего разностного запроса.
Если возвращается свойство nextLink, то остались изменения каталога, которые приложение может синхронизировать после этого ответа. Приложение должно выдать следующий разностный запрос при первой возможности.
Ответы всегда возвращаются в формате JSON.
Рекомендации по использованию разностного запроса
В следующем списке перечислены важные рекомендации для приложений, использующих разностный запрос:
Изменения, возвращаемые разностным запросом, представляют состояние объектов каталога на момент ответа. Ваше приложение не должно обрабатывать эти изменения как журналы транзакций для воспроизведения.
Изменения отображаются в том порядке, в котором они имели место. Объекты, измененные последними, отображаются в конце, даже если такой объект был обновлен несколько раз. На их порядок также не влияет то, когда именно клиент получил эти изменения. В результате порядок изменений может отличаться от того порядка, в котором они произошли в каталоге.
Ваше приложение должно быть готово для воспроизведения, которое происходит, когда в следующих друг за другом ответах присутствуют одни и те же изменения. Хотя разностный запрос делает все возможное для уменьшения числа воспроизведений, они все равно могут иметь место.
Приложение должно быть готово к обработке неожиданного изменения удаления для объекта.
Разностный запрос может вернуть ссылку исходный или целевой объект, который еще не был возвращен другими ответами.
Дополнительную информацию об использовании заголовков запроса для ограничения запросов для улучшения производительности см. в разделе Дополнительные компоненты разностного запроса.
Примеры запросов и ответов
Ниже приведен пример начального разностного запроса:
GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net
Ниже приведен пример добавочного разностного запроса:
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net
Примечание. В обоих этих примерах параметр запроса $filter отображается исключительно в демонстрационных целях. Поскольку фильтр указывает все возможные типы целевого объекта для разностного запроса ("User", "Group" и "Contact"), его можно опустить, и запрос будет возвращать изменения для всех этих типов сущностей по умолчанию.
В следующем примере ответа показана возвращаемая JSON:
{
"odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",
# This is the deltaLink to be used for the next query
"aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
"value": [
# User object for John Smith
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
"objectType": "User",
"objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
"accountEnabled": true,
"displayName": "John Smith",
"givenName": "John",
"mailNickname": "johnsmith",
"passwordPolicies": "None",
"surname": "Smith",
"usageLocation": "US",
"userPrincipalName": "johnsmith@contoso.com"
},
# Group object for IT Administrators
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
"objectType": "Group",
"objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
"description": "IT Administrators",
"displayName": "Administrators",
"mailNickname": "Administrators",
"mailEnabled": false,
"securityEnabled": true
},
# Contact object for Jane Smith
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
"objectType": "Contact",
"objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
"displayName": "Jane Smith",
"givenName": "Jane",
"mail": "johnsmith@contoso.com",
"mailNickname": "johnsmith",
"proxyAddresses": [
"SMTP:janesmith@fabrikam.com"
],
"surname": "Smith"
},
# Member link indicating John Smith is a member of IT Admin Group
{
"odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
"objectType": "DirectoryLinkChange",
"objectId": "00000000-0000-0000-0000-000000000000",
"associationType": "Member",
"sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
"sourceObjectType": "Group",
"sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
"targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
"targetObjectType": "User",
"targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
}
]
}
Дополнительные компоненты разностного запроса
Теперь разностные запросы могут возвращать только обновленные свойства и ссылки. Это позволяет ускорить обработку и снизить количество полезных данных для вызовов разностного запроса. Этот параметр можно включить, задав для заголовка ocp-aad-dq-include-only-changed-properties значение true, как показано в следующем примере.
GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK
Например, если изменилось только значение свойства displayName для пользователя, возвращаемый объект будет выглядеть следующим образом:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Поддержка разностной синхронизация для текущей синхронизации. Можно указать специальный заголовок с запросом на получение только обновленного deltaToken. Этот маркер можно использовать в последующих запросах, которые будут возвращать только текущие изменения. Ниже представлен пример вызова:
GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK
Ответ будет содержать deltaLink, но не будет включать измененные объекты, подобные следующим:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Обнаружение удаленного элемента. Ответ также можно использовать для обнаружения удаленного элемента. Удаленные объекты и ссылки указываются свойством aad.isDeleted, для которого задано значение true. Это необходимо, чтобы убедиться, что приложения могут узнать об удалении ранее созданных объектов и ссылок.