Общие сведения об операциях | Общие понятия 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 Ключ, который идентифицирует текущий сеанс в службе каталога.

Для каждого запроса рекомендуется выполнять как минимум следующие действия:

  1. Зарегистрировать точное время подачи запроса.
  2. Отправить и зарегистрировать client-request-id.
  3. Зарегистрировать код 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 см. в статье Разностный запрос.

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