Различия запросов между Azure AD Graph и Microsoft Graph

  • Статья

Эта статья является частью шага 1. Просмотр различий API в процессе миграции приложений.

Microsoft Graph и API Graph Azure Active Directory (Azure AD) — это интерфейсы REST API, поддерживающие соглашения OData для параметров запроса. Однако синтаксис различается между этими двумя API.

Используйте Обозреватель Graph, чтобы опробовать эти шаблоны запросов на основе собственных данных и узнать о различиях в запросах и ответах перед обновлением кода.

Базовые запросы

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

Сведения о запросе Azure AD Graph Microsoft Graph
Синтаксис запроса https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters https://graph.microsoft.com/{version}/{resource}?query-parameters
Конечные точки службы:
-Глобального https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- Германия (в отставке) https://graph.cloudapi.de https://graph.microsoft.de
- Китай (21Vianet) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} Укажите идентификатор клиента или доменное имя в запросе. Необязательный параметр. Идентификатор клиента выводится из маркера доступа.

Если вы указываете идентификатор клиента, используйте следующий синтаксис: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters.
{version} Укажите версию выпуска Azure AD Graph в запросе с помощью обязательного параметра запроса. Укажите версию выпуска Microsoft Graph в запросе как часть URL-адреса сразу после конечной точки службы.

Синтаксис параметров запроса одинаков для Microsoft Graph и Azure AD Graph. Однако Microsoft Graph поддерживает больше параметров запросов и возможностей запросов, чем Azure AD Graph.

Пример сравнения запросов

Предположим, вам нужен список всех пользователей с именами, начиная с "Dan" в клиенте Contoso. В следующей таблице показаны различия запросов между Azure AD Graph и Microsoft Graph.

Azure AD Graph Microsoft Graph
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

Идентификаторы первичного ключа: objectId и id

В Azure AD Graph все типы ресурсов сущности имеют уникальный идентификатор (или первичный ключ) с именем objectId. Для большинства сущностей (если не указано иное) этот идентификатор называется id в Microsoft Graph.

Помимо первичного ключа, некоторые сущности поддерживают альтернативный идентификатор ключа. Например, ресурсы application и servicePrincipal в Microsoft Graph поддерживают альтернативный идентификатор ключа для свойства appId .

Свойства и $select по умолчанию

Рекомендуется запрашивать только те свойства, которые действительно нужны приложению. $select Используйте параметр запроса в запросах GET, чтобы настроить ответ так, чтобы он включал только те свойства, которые требуются приложению.

В некоторых случаях в Microsoft Graph, например в операциях GET или LIST для ресурсов пользователей и групп , возвращается только подмножество всех свойств. Эти свойства по умолчанию представляют наиболее часто используемые свойства для ресурсов. С другой стороны, Azure AD Graph возвращает полный набор всех свойств для соответствующего ресурса. Если ресурс возвращает только свойства по умолчанию, приложение должно явно запрашивать другие свойства с помощью $select параметра запроса.

Чтобы проиллюстрировать разницу, используйте Обозреватель Graph для выполнения следующих запросов и сравнения различных ответов.

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

Обратите внимание на разницу в ответах. Версия /beta возвращает больше свойств, чем /v1.0 версия. Если ваше приложение использует, например, свойство streetAddress , необходимо обновить v1.0 запросы, чтобы использовать $select параметр запроса для запроса свойства streetAddress в дополнение к другим свойствам, которые нужны приложению. Например:

https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode

Дополнительные сведения о:

Связи и свойства навигации

Связи (или свойства навигации) — это ключевое понятие в Azure AD Graph и Microsoft Graph, создающее сеть связанных ресурсов. Например, свойства manager и directReports расширяют ресурс пользователя для предоставления иерархии организации.

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

Azure AD запросы Graph используются для $links указания связей между ресурсами. Вместо этого Microsoft Graph использует нотацию OData версии 4.01 $ref .

В следующей таблице показано несколько примеров:

Задача Azure AD Graph Microsoft Graph
Добавление участника POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
Список ссылок участников GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
Список участников GET /groups/{id}/members GET /groups/{id}/members
Удаление участника DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

При переносе приложений в Microsoft Graph обновите ссылки, которые используются $links для связывания ресурсов $ref .

Следующее действие

Еще раз просмотрите контрольный список миграции