Использование API Microsoft Graph

Microsoft Graph — это соответствующий ограничениям REST веб-API, обеспечивающий доступ к ресурсам службы Microsoft Cloud. После регистрации приложения и получения маркеров аутентификации для пользователя или службы можно отправлять запросы к API Microsoft Graph.

Важно! Изменяется принцип применения политик условного доступа к Microsoft Graph. Вам необходимо обновить свои приложения, чтобы они могли обрабатывать сценарии, в которых выполняется настройка политик условного доступа. Дополнительные сведения и рекомендации см. в статье Руководство для разработчиков по условному доступу в Azure Active Directory.

Пространство имен OData

API Microsoft Graph определяет большую часть своих ресурсов, методов и перечислений в пространстве имен OData, microsoft.graph, в метаданных Microsoft Graph. Небольшое число наборов API определено во вложенных пространствах имен, например API записей звонков, определяющий такие ресурсы, как callRecord в microsoft.graph.callRecords.

Если явно не указано в соответствующем разделе, предполагается, что типы, методы и перечисления являются частью пространства имен microsoft.graph.

Вызов метода API REST

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

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Компоненты запроса:

  • {Метод HTTP} — метод HTTP, используемый в запросе для Microsoft Graph.
  • {версия} — версия API Microsoft Graph, которую использует приложение.
  • {ресурс} — ресурс Microsoft Graph, на который вы ссылаетесь.
  • {параметры-запроса} — необязательные параметры запроса OData или метода REST для изменения ответа.

После создания запроса возвращается ответ, который включает:

  • Код состояния — код состояния HTTP, который указывает на результат операции. Сведения о кодах ошибок HTTP см. в разделе Ошибки.
  • Ответ — запрошенные данные или результат операции. Для некоторых операций ответ может быть пустым.
  • nextLink — если найдено много данных, чтобы пролистать их все, используйте URL-адрес, возвращенный в свойстве @odata.nextLink. Дополнительные сведения см. в этой статье.

Методы HTTP

Чтобы определить функцию запроса, Microsoft Graph использует метод HTTP. API поддерживает перечисленные ниже методы.

Метод Описание
GET Чтение данных из ресурса.
POST Создание нового ресурса или выполнение действия.
PATCH Обновление ресурса с использованием новых значений.
PUT Замена ресурса новым.
DELETE Удаление ресурса.
  • Для CRUD-методов GET и DELETE указывать текст запроса не нужно.
  • Для методов POST, PATCH и PUT текст запроса обычно указывается в формате JSON и содержит такие дополнительные сведения, как значения свойств ресурса.

Версия

Microsoft Graph в настоящее время поддерживает две версии: v1.0 и beta.

  • v1.0 включает общедоступные API. Используйте версию 1.0 для всех рабочих приложений.
  • beta содержит бета-версии API. Так как мы можем вносить в бета-версии API критические изменения, рекомендуем использовать их только для проверки разрабатываемых приложений. Не используйте бета-версии API в рабочих приложениях.

Мы всегда рады отзывам о бета-версиях API. Чтобы оставить отзыв или предложить функцию, посетите наш форум идей для платформы разработчиков Microsoft 365.

Дополнительные сведения о версиях API см. в статье Управление версиями и поддержка.

Ресурс

Ресурс может быть объектом или сложным типом и обычно определяется с помощью свойств. Объекты всегда содержат свойство id, что отличает их от сложных типов.

URL-адрес будет включать ресурсы, с которыми вы взаимодействуете в запросе, например me, user, group, drive и site. Часто ресурсы верхнего уровня также включают связи, которые можно использовать для доступа к дополнительным ресурсам, например me/messages или me/drive. Работать с ресурсами можно также с помощью методов. Например, для отправки сообщения электронной почты используйте me/sendMail. Дополнительные сведения см. в статье Доступ к данным и методам с помощью Microsoft Graph.

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

Сведения о разрешениях см. в справочнике по разрешениям.

Параметры запроса

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

Вы можете использовать необязательные системные параметры запроса OData, чтобы изменять свойства, включаемые в ответ, находить элементы, соответствующие пользовательскому запросу, и указывать дополнительные параметры для метода.

Например, если добавить указанный ниже параметр filter, будут возвращаться только сообщения, у которых свойство emailAddress имеет значение jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Дополнительные сведения о параметрах запроса OData см. в статье Настройка ответов с помощью параметров запроса.

Помимо параметров запроса OData, некоторые методы требуют указание значений параметров в составе URL-адреса запроса. Например, вы можете получить коллекцию событий, произошедших в течение периода времени в календаре пользователя, запросив связь calendarView объекта user и указав в качестве параметров запроса значения периода startDateTime и endDateTime.

GET https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Инструменты для взаимодействия с Microsoft Graph

Песочница Graph

Песочница Graph — это веб-инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph. Песочница Graph доступна по адресу: https://developer.microsoft.com/graph/graph-explorer.

Вы можете получить доступ к демонстрационным данным без входа или войти в свой клиент. Чтобы отправить запрос, выполните следующее:

  1. Выберите метод HTTP.
  2. Выберите версию API, которую нужно использовать.
  3. Введите запрос в текстовое поле запроса.
  4. Нажмите Запуск запроса.

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

Снимок экрана: песочница Graph с выделенным запросом пользователя GET

Примеры запросов представлены в песочнице Graph, чтобы вы могли быстрее запускать распространенные запросы. Чтобы просмотреть доступные примеры, выберите Показать другие примеры. Выберите Вкл для набора примеров, который вы хотите просмотреть, и после закрытия окна выбора должен появиться список готовых запросов.

После отправки запроса отображается код состояния и сообщение, а запрос выводится на вкладке Просмотр отклика.

Postman

Postman — это инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph. Вы можете скачать Postman по адресу: https://www.getpostman.com/. Чтобы взаимодействовать с Microsoft Graph в Postman, используйте коллекцию Microsoft Graph.

Дополнительные сведения см. в статье Использование Postman с API Microsoft Graph.

Дальнейшие действия

Все готово для настройки Microsoft Graph. Воспользуйтесь кратким руководством или начните с одного из пакетов SDK или примеров кода.