Общие сведения об операциях | Общие понятия API Graph
API Graph Azure Active Directory (AD) — это служба, совместимая с OData 3.0. Ее можно использовать для чтения и изменения таких объектов, как пользователи, группы и контакты в клиенте. API Graph Azure AD предоставляет конечные точки REST, в которые вы отправляете HTTP-запросы для выполнения операций с использованием службы. В следующих разделах представлены общие сведения о форматировании запросов и возможные ответы при использовании API Graph для чтения и записи ресурсов каталога, для вызова функций или действий каталога или для выполнения запросов к каталогу. Более подробные сведения о выполнении определенных операций с ресурсами каталога см. в разделе Справочника по API Graph Azure AD о соответствующей операции.
Успешный запрос в API Graph должен направляться в действительную конечную точку и иметь правильный формат, т. е. содержать все необходимые заголовки и, если необходимо, полезные данные JSON в теле запроса. Выполняющее запрос приложение должно включать маркер, полученный из Azure AD и подтверждающий, что оно авторизовано для доступа к ресурсам, на которые направлен запрос. Кроме того, приложение должно быть способно обрабатывать любые ответы, поступающие от API Graph.
Разделы этой статьи помогут вам понять формат запросов и ответов, используемый в API Graph.
Важно!
Для доступа к ресурсам 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.
Проверка подлинности и авторизация
Каждый запрос в API Graph должен включать прикрепленный токен носителя, присвоенный ему Azure Active Directory. Токен передает сведения о приложении, пользователе, выполнившем вход (в случае делегированных разрешений), проверке подлинности и операциях в каталоге, которые ваше приложение имеет право выполнять. Токен передается в заголовке Authorization запроса. Например (для краткости токен сокращен):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
API Graph выполняет авторизацию на основе областей разрешений доступа OAuth 2.0, указанных в токене. Дополнительные сведения об областях разрешений, предоставляемых API Graph, см. в статье Области разрешений API Graph.
Чтобы приложение проходило проверку подлинности в Azure AD и вызывало API Graph, необходимо добавить его в клиент и настроить для требований разрешений (областей разрешений доступа OAuth 2.0) для Windows Azure Active Directory. Сведения о добавлении и настройке приложения см. в статье Интеграция приложений с Azure Active Directory.
В Azure AD используется протокол проверки подлинности OAuth 2.0. Дополнительные сведения об OAuth 2.0 в Azure AD, включая поддерживаемые потоки и маркеры доступа, см. в статье OAuth 2.0 в Azure AD.
Адресация конечных точек
Для выполнения операций с использованием API Graph вы отправляете HTTP-запросы с поддерживаемым методом (обычно это GET, POST, PATCH, PUT или DELETE) к конечной точке, ориентированной на службу, коллекцию ресурсов, отдельный ресурс, свойство навигации ресурса либо предоставляемую службой функцию или действие. Конечные точки предоставляются в виде URL-адресов.
Ниже описан основной формат конечной точки API Graph:
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
URL-адрес состоит из следующих компонентов:
- Корень службы: корень службы для всех запросов API Graph — это
https://graph.windows.net. - Идентификатор клиента {tenant_id}: идентификатор клиента, на который направлен запрос.
- Путь к ресурсу {resource_path}: путь к ресурсу — это, например, пользователь или группа, на которых направлен запрос.
- Версия API Graph {api_version}: версия Graph API, на которую направлен запрос. Выражается как параметр запроса и является обязательным.
Примечание. В некоторых случаях при чтении коллекций ресурсов в запросы OData могут добавляться параметры для фильтрации, заказа и постраничного представления набора результатов. Дополнительные сведения см. в разделе Параметры запроса OData в этой статье.
Идентификатор клиента {tenant_id}
Целевой клиент запроса можно указать одним из четырех способов:
По идентификатору объекта клиента. Это GUID, назначенный при создании клиента. Его можно найти в свойстве objectId объекта TenantDetail. Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей по идентификатору объекта клиента:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.По проверенному (зарегистрированному) доменному имени. Это одно из доменных имен, зарегистрированных для клиента. Они хранятся в свойстве verifiedDomains объекта TenantDetail. Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей клиента с доменом contoso.com:
https://graph.windows.net/contoso.com/users?api-version=1.6.С использованием псевдонима
myOrganization. Этот псевдоним доступен только при использовании проверки подлинности OAuth Authorization Code Grant (трехступенчатой), т. е. области делегированных разрешений. Прописные и строчные буквы в псевдониме не различаются. В URL-адресе заменяется идентификатор объекта или домен клиента. При использовании псевдонима API-интерфейс Graph определяет клиента на основе утверждений в токене, присоединенном к запросу. Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей с помощью псевдонима:
https://graph.windows.net/myorganization/users?api-version=1.6.С использованием псевдонима
me. Этот псевдоним доступен только при использовании проверки подлинности OAuth Authorization Code Grant (трехступенчатой), т. е. области делегированных разрешений. Прописные и строчные буквы в псевдониме не различаются. В URL-адресе заменяется идентификатор объекта или домен клиента. При использовании псевдонима API-интерфейс Graph определяет пользователя на основе утверждений в токене, присоединенном к запросу. Для обращения к пользователю, выполнившему вход с использованием псевдонима, используется следующий URL-адрес:https://graph.windows.net/me?api-version=1.6.
Примечание. Псевдоним me используется исключительно для операций с пользователем, выполнившим вход. Дополнительные сведения см. в статье Signed-in User Operations.
Путь к ресурсу {resource_path}
Параметр {resource_path} указывается по-разному в зависимости от того, к чему вы обращаетесь — к коллекции ресурсов, отдельному ресурсу, свойству навигации ресурса либо функции или действию, предоставляемым в клиенте или в ресурсе.
| Target | Путь | Описание |
|---|---|---|
| Метаданные службы | /$metadata |
Возвращает документ метаданных службы. В следующем примере демонстрируется обращение к метаданным службы с использованием клиента contoso.com: https://graph.windows.net/contoso.com/$metadata?api-version=1.6 Примечание. Для чтения метаданных службы проверка подлинности не требуется. |
| Коллекция ресурсов | /{resource_collection} |
Обращается к коллекции ресурсов, например к пользователям или группам в клиенте. Этот путь можно использовать для чтения ресурсов в коллекции, а также (в зависимости от типа ресурсов) для создания нового ресурса в клиенте. В большинстве случаев результирующий набор, возвращенный операцией чтения, можно уточнить, добавив параметры запроса для фильтрации, упорядочивания или постраничного представления результатов. В следующем примере демонстрируется обращение к коллекции пользователей: https://graph.windows.net/myorganization/users?api-version=1.6 |
| Отдельный ресурс | /{resource_collection}/{resource_id} |
Обращается к определенному ресурсу в клиенте, такому как пользователь, контакт, организация или группа. Для большинства ресурсов resource_id — это идентификатор объекта. Некоторые ресурсы позволяют использовать дополнительные спецификаторы, например, пользователей можно также указывать с помощью имени субъекта-пользователя (UPN). В зависимости от ресурса этот путь можно использовать для получения объявленных свойств ресурса, изменения объявленных свойств или удаления ресурса. В следующем примере демонстрируется обращение к пользователю john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| Свойство навигации (объекты) | /{resource_collection}/{resource_id}/{property_name} |
Обращается к свойству навигации определенного ресурса, такого как руководитель пользователя или его членство в группах либо члены группы. Этот путь можно использовать для получения объекта или объектов, на которые ссылается свойство навигации. В следующем примере демонстрируется обращение к руководителю john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6 Примечание. Эта форма адресации доступна только для операций чтения. |
| Свойство навигации (ссылки) | /{resource_collection}/{resource_id}/$links/{property_name} |
Обращается к свойству навигации определенного ресурса, такого как руководитель пользователя или его членство в группах либо члены группы. Эту форму адресации можно использовать для чтения и изменения свойства навигации. При чтении объекты, на которые ссылается свойство, возвращаются в виде одной или нескольких ссылок в тексте ответа. При записи объекты обозначаются как одна или несколько ссылок в тексте запроса. В следующем примере демонстрируется обращение к свойству руководителя john@contoso.com: https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6 |
| Функции и действия, предоставляемые в клиенте | /{function_name} |
Обращается к функции или действию, предоставляемым в клиенте. Функции и действия обычно вызываются с помощью запроса POST и могут включать текст запроса. В следующем примере демонстрируется обращение к функции isMemberOf: https://graph.windows.net/myorganization/isMemberOf?api-version=1.6. |
| Функции и действия, предоставляемые в ресурсе | /{resource_collection}/{resource_id}/{function_name} |
Обращается к функции или действию, предоставляемым в ресурсе. Функции и действия обычно вызываются с помощью запроса POST и могут включать текст запроса. В следующем примере демонстрируется обращение к функции getMemberGroups: https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6. |
Версия API Graph {api-version}
Параметр запроса api-version используется для обращения к определенной версии API Graph для выполнения операции. Этот параметр обязательный.
Параметр api-version может иметь одно из следующих значений:
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
Например, следующий URL-адрес обращается к коллекции пользователей, которые используют API Graph версии 1.6:
https://graph.windows.net/myorganization/users?api-version=1.6
Дополнительные сведения о версиях и отличиях версий по функциональным возможностям см. в статье Управление версиями.
Параметры запроса OData
Во многих случаях при чтении коллекции ресурсов можно фильтровать, сортировать и разбивать на страницы результирующий набор, добавляя к запросу параметры запроса OData.
API Graph поддерживает следующие параметры запроса OData:
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken и previous-page
Дополнительные сведения о поддерживаемых параметрах запросов OData и связанных с ними ограничениях в API Graph см. в статье Поддерживаемые запросы, фильтры и операции разбиения на страницы.
Заголовки запросов и ответов
В следующей таблице показаны основные заголовки HTTP, которые используются в запросах при работе с API Graph. Этот список не претендует на полноту.
| Заголовок запроса | Описание |
|---|---|
| Авторизация | Обязательный параметр. Токен носителя, выданный службой Azure Active Directory. Дополнительные сведения см. в статье Проверка подлинности и авторизация. |
| Content-Type | Требуется, если присутствует текст запроса. Тип носителя содержимого для текста запроса. Используйте application/json. Параметры могут быть включены с типом носителя. Примечание. application/atom+xml и application/xml (ссылки) поддерживаются, но не рекомендуются из соображений производительности, а также потому, что в дальнейшем поддержка XML будет прекращена. |
| Content-Length | Требуется, если присутствует текст запроса. Длина запроса в байтах. |
В следующей таблице показаны основные заголовки HTTP, которые API Graph возвращает в ответах. Этот список не претендует на полноту.
| Заголовок ответа | Описание |
|---|---|
| Content-Type | Тип носителя содержимого в тексте запроса. Значение по умолчанию — application/json. По умолчанию в ответ на запросы миниатюрных фотографий пользователей возвращается image/jpeg. |
| Расположение | Возвращается в ответах на запросы POST, которые создают в каталоге новый ресурс (объект). Содержит URI вновь созданного ресурса. |
| ocp-aad-diagnostics-server-name | Идентификатор сервера, который выполняет запрашиваемую операцию. |
| ocp-aad-session-key | Ключ, который идентифицирует текущий сеанс в службе каталога. |
Для каждого запроса рекомендуется выполнять как минимум следующие действия:
- Зарегистрировать точное время подачи запроса.
- Отправить и зарегистрировать
client-request-id. - Зарегистрировать код HTTP-ответа и
request-id.
Предоставленные таким образом сведения помогут Майкрософт устранить неполадки при обращении за помощью или поддержкой.
Тексты запросов и ответов
Тексты запросов POST, PUT и PATCH можно отправлять в полезных данных JSON или XML. Ответы сервера могут возвращаться в полезных данных JSON или XML. Полезные данные могут указываться в тексте запроса с помощью заголовка Content-Type, а в ответе — с помощью заголовка Accept.
Настоятельно рекомендуем использовать полезные данные JSON в запросах и ответах в API Graph. Это связано с соображениями производительности, а также с тем, что в дальнейшем поддержка XML будет прекращена.
Дополнительные функции
В предыдущих разделах обсуждалось форматирование основных запросов и ответов в API Graph. Расширенные возможности могут добавить дополнительные параметры строк запроса или значительно отличаться в текстах запросов и ответов от основных операций, описанных ранее в этой статье.
Эти функции включают перечисленные ниже.
- Пакетная обработка: API Graph поддерживает пакетную обработку. Пакетная отправка запросов уменьшает циклы приема-передачи запросов на сервере, что позволяет сократить нагрузку на сеть и ускорить выполнение операций. Дополнительные сведения о пакетной обработке в API Graph см. в статье Пакетная обработка.
- Разностный запрос: API Graph поддерживает выполнение разностных запросов. Разностный запрос позволяет возвращать изменения в определенных сущностях в клиенте, возникших между поданными в разное время запросами. Эта функция часто используется для синхронизации локального хранилища с изменениями в клиенте. Дополнительные сведения о разностном запросе в API Graph см. в статье Разностный запрос.