Запрос Microsoft Graph через интерфейс REST

  • 3 мин

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

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

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

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

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

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

Запрос содержит следующие компоненты:

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

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

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

Методы HTTP

Microsoft Graph использует метод HTTP из запроса, чтобы определить его назначение. Этот API поддерживает следующие методы.

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

Версия

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

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

Ресурс

Ресурсом может быть сущность или сложный тип, обычно определяемый свойствами. Сущности отличаются от сложных типов тем, что обязательно содержат свойство id (идентификатор).

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

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

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

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

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

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

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

Другие ресурсы

Ниже приведены ссылки на некоторые средства, которые можно использовать для создания и тестирования запросов с помощью API Microsoft Graph.