Table of contents
TOC
Свернуть оглавление
Развернуть оглавление

Разностный запрос | Общие понятия API Graph

Jimaco Brannian|Последнее обновление: 03.09.2016
|
1 Участник

Область применения: API Graph | Azure Active Directory

В этом разделе обсуждается функция разностного запроса API Graph Azure AD. Разностный запрос возвращает все изменения, внесенные в указанные сущности в период между двумя последовательными запросами. Например, при выполнении разностного запроса через час после предыдущего разностного запроса возвращаются только изменения, внесенные в течение этого часа. Эта функциональность особенно полезна при синхронизации данных каталога клиента с хранилищем данных приложения.

Чтобы выполнить разностный запрос для каталога клиента, ваше приложение должно быть авторизовано клиентом. Дополнительные сведения см. в статье Интеграция приложений с Azure Active Directory.

Важно

Доступ к функциональным возможностям API Graph Azure AD можно получить и через Microsoft Graph — универсальный API, который также включает API других служб Майкрософт, таких как Outlook, OneDrive, OneNote, Планировщик и Office Graph, и позволяет получать к ним доступ через единую конечную точку с маркером единого доступа. Обратите внимание на то, что в настоящее время Microsoft Graph не поддерживает разностные запросы; для работы с этой функцией необходимо использовать API Graph Azure AD.

Разностные запросы

В этом разделе описываются разностные запросы. Всем запросам требуются следующие компоненты:

  • Действительный 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 (контакт). Допустимо только в случае, если &ltresourceSet&gt имеет значение directoryObjects; в противном случае &ltresourceSet&lt переопределяет фильтр. Например, если &ltresourceSet&gt имеет значение users, а также указан параметр $filter, независимо от значения фильтра будут возвращаться только изменения для пользователей. Если &ltresourceSet&gt имеет значение directoryObjects, а параметр $filter не задан, возвращаются изменения для всех поддерживаемых типов сущностей (User, Group и Contact).

Чтобы указать один тип сущности, используйте одно из следующих выражений:
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')
Чтобы указать несколько типов сущностей, используйте оператор or, например $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^ не задан, включаются все свойства.

Свойства могут быть указаны полностью или без уточнения. Несколько свойств разделяются запятыми.
  • Полные свойства имеют заданный тип сущности, например User/displayName Если параметр &ltresourceSet&gt задан со значением directoryObjects, полные свойства ОБЯЗАТЕЛЬНЫ, например https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.
  • Для неуточненных свойств тип сущности не задан, например displayName. Их можно использовать только в том случае, если для параметра &ltresourceSet&gt задано значение, отличное от directoryObjects, например https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

Примечание. Пары "ключ-значение" в строке запроса чувствительны к регистру, однако их порядок не имеет значения.

Далее представлен пример простейшего разностного запроса. Он используется во время начальной синхронизации.

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. Это необходимо, чтобы убедиться, что приложения могут узнать об удалении ранее созданных объектов и ссылок.

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

© 2017 Microsoft