Поддерживаемые параметры запросов, фильтров и операций разбиения на страницы | Общие понятия API Graph
В этой статье представлены параметры запросов, фильтры и операции разбиения на страницы, которые можно использовать при работе с API Graph Azure Active Directory (AD). Последний раздел содержит несколько примеров распространенных запросов, которые можно выполнять с помощью API Graph Azure AD.
Важно!
Для доступа к ресурсам 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.
Адресация
Все приведенные ниже запросы обращаются к клиенту по имени домена. Вы можете заменить contoso.com на одно из зарегистрированных доменных имен вашего клиента с идентификатором GUID или с псевдонимом MyOrganization вашего клиента (для делегированного доступа). В некоторых случаях можно использовать псевдоним me. Сведения о других способах обращения к клиенту см. в статье Общие сведения об операциях.
Поддерживаемые параметры запросов
Graph поддерживает следующие параметры запросов: $filter, $orderby, $expand, $top и $format. В настоящее время не поддерживаются следующие параметры запросов: $count, $inlinecount и $skip.
$filter
К запросам, в которых содержится фильтр, применяются следующие ограничения общего характера.
Выражения $filter нельзя объединять с выражениями $orderby.
Фильтрация не поддерживается для запросов к объектам каталога DirectoryRole и SubscribedSku.
Не все свойства поддерживаемых объектов каталога можно использовать в качестве критерия фильтра. Дополнительные сведения о свойствах, которые можно использовать в фильтрах, см. в разделах User, Group и Contact.
На выражения фильтров налагаются следующие ограничения.
Логические операторы: поддерживаются операторы and и or. Пример:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')Операторы сравнения: поддерживаются операторы eq (равно), ge (больше или равно) и le (меньше или равно).
Поддерживается инструкция startswith. Пример:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')Поддерживается any при запросе свойств с несколькими значениями. Пример:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')Арифметические операторы: не поддерживаются.
Функции: не поддерживаются.
Значения null в качестве операнда в выражениях фильтра не поддерживаются. Например, нельзя указать значение null для фильтрации незаданных свойств.
$orderby
$orderby выполняет сортировку возвращенных объектов по указанному параметру. В следующей таблице приводятся примеры запросов с использованием $orderby.
| Запрос | Описание |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Возвращает список пользователей, упорядоченных по отображаемому имени. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Возвращает список первых 50 пользователей, упорядоченных по отображаемому имени. |
На выражения $orderby налагаются следующие ограничения.
В настоящее время поддерживаются два порядка сортировки: DisplayName для объектов User и Group и UserPrincipalName для объектов User. По умолчанию для пользователей применяется порядок сортировки UserPrincipalName.
Выражения $orderby нельзя объединять с выражениями $filter.
$expand
$expand возвращает сам объект и связанные с ним объекты. В следующей таблице приводятся примеры запросов с использованием $expand.
| Запрос | Описание |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Возвращает группу и всех ее членов. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Возвращает пользователя и его подчиненных. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Возвращает пользователя и его руководителя. |
На выражения $expand налагаются следующие ограничения.
- В запросе может возвращаться не более 20 объектов.
$top
$top не поддерживается для запросов к объектам каталога DirectoryRole или SubscribedSku.
Поддержка разбиения на страницы
В Graph можно переходить по страницам вперед и назад. Ответ, содержащий разбитые по страницам результаты, будет включать токен пропуска (odata.nextLink), позволяющий получить следующую страницу результатов. Этот токен пропуска можно объединять с аргументом запроса previous-page=true для перехода по страницам в обратном направлении.
Следующий пример запроса демонстрирует переход по страницам вперед.
| Запрос | Описание |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
В запрос включен параметр $skiptoken из предыдущего ответа, который позволяет перейти на следующую страницу результатов. |
Следующий пример запроса демонстрирует переход по страницам назад.
| Запрос | Описание |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
В запрос включен параметр $skiptoken из предыдущего ответа. Если он объединяется с параметром &previous-page=true, то будет извлекаться предыдущая страница результатов. |
Далее показывается процесс, состоящий из запросов и ответов, для перехода по страницам назад и вперед:
- Выполняется запрос для получения списка первых 10 пользователей из 15. Ответ содержит токен пропуска, обозначающий конец страницы из 10 пользователей.
- Чтобы получить последние 5 пользователей, выполняется другой запрос, содержащий токен пропуска из предыдущего запроса.
- Чтобы вернуться на страницу назад, выполняется запрос с использованием токена пропуска, полученного в шаге 1, и параметра &previous-page=true.
- Ответ содержит предыдущую (первую) страницу из 10 пользователей. В другом сценарии, в котором остается больше страниц, необходимо получить новый токен пропуска. Этот новый токен пропуска можно добавить в запрос вместе с параметром &previous-page=true, чтобы снова получить предыдущую страницу.
На запросы с переходами по страницам налагаются следующие ограничения.
- Размер страницы по умолчанию равен 100. Максимальный размер страницы равен 999.
- Запросы к ролям не поддерживают разбиение на страницы. Сюда входит чтение самих объектов роли, а также членов роли.
- Запросы списка ресурсов, такие как поиск всех пользователей в клиенте (/users), не поддерживают разбиение на страницы. Например:
https://graph.windows.net/contoso.com/users?api-version=1.6. Однако для всех типов запросов с применением фильтра разбиение на страницы не поддерживается, и возвращается только первая страница результатов. - Разбиение на страницы для поиска связей (например, данных о членстве в группах) не поддерживается. Например:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
Порядок сортировки
- Результирующий набор запроса всех пользователей упорядочивается по свойству UserPrincipalName. Например:
https://graph.windows.net/contoso.com/users?api-version=1.6. - Результирующий набор запроса всех других ресурсов верхнего уровня, таких как группы, контакты и пр., упорядочивается по свойству objectId. Например:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - Порядок результатов других запросов (отличных от запросов ресурсов верхнего уровня) не определен.
Стандартные запросы
В следующих разделах представлено несколько примеров стандартных запросов, которые можно выполнять с помощью API Graph.
Запрос ресурсов верхнего уровня
В следующих запросах показано, как получить доступ к ресурсам верхнего уровня в API Graph, на примере клиента contoso.com. Обратите внимание на то, что для выполнения запросов к клиенту потребуется заголовок авторизации, который содержит действительный токен носителя, полученный из Azure AD.
| Ресурс верхнего уровня | Результаты запроса | URI (для contoso.com) |
|---|---|---|
| Ресурсы верхнего уровня | Возвращает список URI ресурсов верхнего уровня для службы каталогов (также перечисленных ниже) | https://graph.windows.net/contoso.com?api-version=1.6 |
| Сведения об организации | Возвращает сведения об организации | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Контакты | Возвращает контактную информацию организации | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Возвращает сведения о пользователе | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Группы | Возвращает данные о группе | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Роли каталога | Возвращает все активированные роли каталога в клиенте | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Возвращает подписки клиента | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Метаданные каталога | Возвращает документ метаданных службы, описывающий модель данных (то есть структуру и организацию ресурсов каталога) | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Другие операции запросов
В следующей таблице представлено несколько дополнительных примеров запросов API Graph, где в качестве примера используется клиент contoso.com.
| Операция запроса | URI (для contoso.com) |
|---|---|
| Выводит список всех пользователей и групп | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Получение отдельных пользователей путем указания objectId или userPrincipalName | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| Запрос и фильтр для пользователя, в котором displayName имеет значение Jon Doe | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Запрос и фильтр для определенных пользователей, в котором firstName имеет значение Jon | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Фильтр по значениям givenName и фамилии. | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Получение отдельной группы путем указания objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Получение руководителя пользователя | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Получение списка непосредственных подчиненных пользователя | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Получение списка ссылок на непосредственных подчиненных пользователя | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Получение списка членов группы | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Получение списка ссылок на членов группы. | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Получение списка групп, членом (постоянным) которых является пользователь | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Получение списка групп, членом (постоянным) которых является пользователь | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Запрос и фильтр для групп с displayName >= "az" and <= "dz" | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Возвращать все локальные учетные записи пользователей в клиенте Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Возвращает локальную учетную запись пользователя с именем входа joe@example.com из клиента Azure Active Directory B2C | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
Примечание. Пробел в строке запроса должен быть закодирован в формате URL перед отправкой запроса. Например, следующая строка запроса https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 должна быть закодирована в формате URL-адреса так: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.