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

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

Пространство имен 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, описанные ниже.

• Для 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 имеет значение [email protected].

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq '[email protected]'

Дополнительные сведения о параметрах запроса 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, чтобы вы могли быстрее запускать распространенные запросы. Чтобы просмотреть доступные примеры, выберите Показать другие примеры. Выберите Вкл для набора примеров, который вы хотите просмотреть, и после закрытия окна выбора должен появиться список готовых запросов.

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

Postman

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

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

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

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