Использование 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.
Вы можете получить доступ к демонстрационным данным без входа или можете войти в свой клиент. Для создания запроса выполните следующие действия:
- Выберите метод HTTP.
- Выберите версию API, которую нужно использовать.
- Введите запрос в текстовое поле запроса.
- Нажмите Запуск запроса.
В следующем примере показан запрос, возвращающий сведения о пользователях в демонстрационном клиенте:
Примеры запросов представлены в песочнице Graph, чтобы вы могли быстрее запускать распространенные запросы. Чтобы просмотреть доступные примеры, выберите Показать другие примеры. Выберите Вкл для набора примеров, который вы хотите просмотреть, и после закрытия окна выбора должен появиться список готовых запросов.
После отправки запроса отображается код состояния и сообщение, а запрос выводится на вкладке Просмотр отклика.
Postman
Postman — это инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph. Вы можете скачать Postman по адресу: https://www.getpostman.com/. Чтобы взаимодействовать с Microsoft Graph в Postman, используйте коллекцию Microsoft Graph.
Дополнительные сведения см. в статье Использование Postman с API Microsoft Graph.
Дальнейшие действия
Все готово для настройки Microsoft Graph. Воспользуйтесь кратким руководством по началу работы или начните использовать один из наших пакетов SDK и примеров кода.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по