Поделиться через

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

  • Статья

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

Важно!

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

Пространство имен 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 для изменения ответа.
  • {headers} — заголовки запросов, которые настраивают запрос. Может быть необязательным или обязательным в зависимости от API.

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

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

Методы HTTP

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

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

Важно!

Размер запросов на запись в microsoft API Graph ограничен в 4 МБ.

В некоторых случаях фактический размер запроса на запись меньше 4 МБ. Например, при присоединении файла к пользовательскому событию POST /me/events/{id}/attachments используется ограничение размера запроса в 3 МБ, так как размер файла около 3,5 МБ может быть больше 4 МБ при кодировании в base64.

Запросы, превышающие предельный размер, завершаются ошибкой с кодом состояния HTTP 413 и сообщением об ошибке "Запросить сущность слишком большой" или "Полезные данные слишком большие".

Версия

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 поддерживает как стандартные заголовки HTTP, так и пользовательские заголовки.

Для определенных API может потребоваться включить в запрос дополнительные заголовки. С другой стороны, Microsoft Graph всегда будет возвращать обязательные заголовки, такие как request-id заголовок в ответе, или некоторые заголовки могут быть специфичными для некоторых API или функций. Например, Retry-After заголовок включается, когда приложение достигает ограничений регулирования; или Location заголовок, включенный для длительных операций.

Заголовки не учитывают регистр, как определено в rfc 9110 , если явно не указано иное.

Инструменты для взаимодействия с 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 и примеров кода.