Различия запросов между 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
Дополнительные сведения о:
- Свойства по умолчанию для ресурсов пользователей и групп см. в разделе Пользователи и группы
- Параметр
$selectи другие поддерживаемые параметры запроса ODATA см . в разделе Использование параметров запроса для настройки ответов. - Другие рекомендуемые оптимизации см. в разделе Рекомендации.
Связи и свойства навигации
Связи (или свойства навигации) — это ключевое понятие в 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 .