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

Microsoft Graph — это соответствующий ограничениям REST веб-API, обеспечивающий доступ к ресурсам службы Microsoft Cloud. После регистрации приложения и получения маркеров аутентификации для пользователя или службы можно отправлять запросы к API Microsoft Graph.Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. After you register your app and get authentication tokens for a user or service, you can make requests to the Microsoft Graph API.

Важно! Изменяется принцип применения политик условного доступа к Microsoft Graph.Important: How conditional access policies apply to Microsoft Graph is changing. Вам необходимо обновить свои приложения, чтобы они могли обрабатывать сценарии, в которых выполняется настройка политик условного доступа.Applications need to be updated to handle scenarios where conditional access policies are configured. Дополнительные сведения и рекомендации см. в статье Руководство для разработчиков по условному доступу в Azure Active Directory.For more information and guidance, see Developer Guidance for Azure Active Directory Conditional Access.

Пространство имен ODataOData namespace

API Microsoft Graph определяет большую часть своих ресурсов, методов и перечислений в пространстве имен OData, microsoft.graph, в метаданных Microsoft Graph.The Microsoft Graph API defines most of its resources, methods, and enumerations in the OData namespace, microsoft.graph, in the Microsoft Graph metadata. Небольшое число наборов API определено во вложенных пространствах имен, например API записей звонков, определяющий такие ресурсы, как callRecord в microsoft.graph.callRecords.A small number of API sets are defined in their sub-namespaces, such as the call records API which defines resources like callRecord in microsoft.graph.callRecords.

Если явно не указано в соответствующем разделе, предполагается, что типы, методы и перечисления являются частью пространства имен microsoft.graph.Unless explicitly specified in the corresponding topic, assume types, methods, and enumerations are part of the microsoft.graph namespace.

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

Для чтения или записи ресурса, например пользователя или сообщения электронной почты, создайте запрос, показанный ниже:To read from or write to a resource such as a user or an email message, you construct a request that looks like the following:

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

Компоненты запроса:The components of a request include:

  • {Метод HTTP} — метод HTTP, используемый в запросе для Microsoft Graph.{HTTP method} - The HTTP method used on the request to Microsoft Graph.
  • {версия} — версия API Microsoft Graph, которую использует приложение.{version} - The version of the Microsoft Graph API your application is using.
  • {ресурс} — ресурс Microsoft Graph, на который вы ссылаетесь.{resource} - The resource in Microsoft Graph that you're referencing.
  • {параметры-запроса} — необязательные параметры запроса OData или метода REST для изменения ответа.{query-parameters} - Optional OData query options or REST method parameters that customize the response.

После создания запроса возвращается ответ, который включает:After you make a request, a response is returned that includes:

  • Код состояния — код состояния HTTP, который указывает на результат операции. Сведения о кодах ошибок HTTP см. в разделе Ошибки.Status code - An HTTP status code that indicates success or failure. For details about HTTP error codes, see Errors.
  • Ответ — запрошенные данные или результат операции. Для некоторых операций ответ может быть пустым.Response message - The data that you requested or the result of the operation. The response message can be empty for some operations.
  • nextLink — если найдено много данных, чтобы пролистать их все, используйте URL-адрес, возвращенный в свойстве @odata.nextLink. Дополнительные сведения см. в этой статье.nextLink - If your request returns a lot of data, you need to page through it by using the URL returned in @odata.nextLink. For details, see Paging.

Методы HTTPHTTP methods

Чтобы определить функцию запроса, Microsoft Graph использует метод HTTP. API поддерживает перечисленные ниже методы.Microsoft Graph uses the HTTP method on your request to determine what your request is doing. The API supports the following methods.

МетодMethod ОписаниеDescription
GETGET Чтение данных из ресурса.Read data from a resource.
POSTPOST Создание нового ресурса или выполнение действия.Create a new resource, or perform an action.
PATCHPATCH Обновление ресурса с использованием новых значений.Update a resource with new values.
PUTPUT Замена ресурса новым.Replace a resource with a new one.
DELETEDELETE Удаление ресурса.Remove a resource.
  • Для CRUD-методов GET и DELETE указывать текст запроса не нужно.For the CRUD methods GET and DELETE, no request body is required.
  • Для методов POST, PATCH и PUT текст запроса обычно указывается в формате JSON и содержит такие дополнительные сведения, как значения свойств ресурса.The POST, PATCH, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

ВерсияVersion

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

  • v1.0 включает общедоступные API. Используйте версию 1.0 для всех рабочих приложений.v1.0 includes generally available APIs. Use the v1.0 version for all production apps.
  • beta содержит бета-версии API. Так как мы можем вносить в бета-версии API критические изменения, рекомендуем использовать их только для проверки разрабатываемых приложений. Не используйте бета-версии API в рабочих приложениях.beta includes APIs that are currently in preview. Because we might introduce breaking changes to our beta APIs, we recommend that you use the beta version only to test apps that are in development; do not use beta APIs in your production apps.

Мы всегда рады отзывам о бета-версиях API. Чтобы оставить отзыв или предложить функцию, посетите нашу страницу UserVoice.We are always looking for feedback on our beta APIs. To provide feedback or request features, see our UserVoice page.

Дополнительные сведения о версиях API см. в статье Управление версиями и поддержка.For more information about API versions, see Versioning and support.

РесурсResource

Ресурс может быть объектом или сложным типом и обычно определяется с помощью свойств.A resource can be an entity or complex type, commonly defined with properties. Объекты всегда содержат свойство id, что отличает их от сложных типов.Entities differ from complex types by always including an id property.

URL-адрес будет включать ресурс, с которым вы взаимодействуете в запросе, например me, user, group, drive и site.Your URL will include the resource you are interacting with in the request, such as me, user, group, drive, and site. Часто ресурсы верхнего уровня также включают связи, которые вы можете использовать для доступа к дополнительным ресурсам, например к ресурсам me/messages или me/drive.Often, top-level resources also include relationships, which you can use to access additional resources, like me/messages or me/drive. Вы также можете взаимодействовать с ресурсами при помощи методов. Например, чтобы отправить электронное письмо, воспользуйтесь методом me/sendMail.You can also interact with resources using methods; for example, to send an email, use me/sendMail. Дополнительные сведения см. в статье Доступ к данным и методам с помощью Microsoft Graph.For more information, see Access data and methods by navigating Microsoft Graph.

Для доступа к каждому ресурсу могут потребоваться особые разрешения. Для создания и обновления ресурса часто требуется более высокий уровень разрешений, чем для чтения. Сведения о требуемых разрешениях см. в справочной статье о методе.Each resource might require different permissions to access it. You will often need a higher level of permissions to create or update a resource than to read it. For details about required permissions, see the method reference topic.

Сведения о разрешениях см. в справочнике по разрешениям.For details about permissions, see Permissions reference.

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

В качестве параметров запросов могут использоваться системные параметры запроса OData или другие строки, поддерживаемые методом для настройки ответа.Query parameters can be OData system query options, or other strings that a method accepts to customize its response.

Вы можете использовать необязательные системные параметры запроса OData, чтобы изменять свойства, включаемые в ответ, находить элементы, соответствующие пользовательскому запросу, и указывать дополнительные параметры для метода.You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.

Например, если добавить указанный ниже параметр filter, будут возвращаться только сообщения, у которых свойство emailAddress имеет значение jon@contoso.com.For example, adding the following filter parameter restricts the messages returned to only those with the emailAddress property of jon@contoso.com.

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

Дополнительные сведения о параметрах запроса OData см. в статье Настройка ответов с помощью параметров запроса.For more information about OData query options, see Use query parameters to customize responses.

Помимо параметров запроса OData, некоторые методы требуют указание значений параметров в составе URL-адреса запроса.Aside from OData query options, some methods require parameter values specified as part of the query URL. Например, вы можете получить коллекцию событий, произошедших в течение периода времени в календаре пользователя, запросив связь calendarView объекта user и указав в качестве параметров запроса значения периода startDateTime и endDateTime.For example, you can get a collection of events that occurred during a time period in a user's calendar, by querying the calendarView relationship of a user, and specifying the period startDateTime and endDateTime values as query parameters:

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

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

Песочница GraphGraph Explorer

Песочница Graph — это веб-инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph.Graph Explorer is a web-based tool that you can use to build and test requests using Microsoft Graph APIs. Песочница Graph доступна по адресу: https://developer.microsoft.com/graph/graph-explorer.You can access Graph Explorer at: https://developer.microsoft.com/graph/graph-explorer.

Вы можете получить доступ к демонстрационным данным без входа или можете войти в свой клиент.You can either access demo data without signing in, or you can sign in to a tenant of your own. Для создания запроса выполните следующие действия:Use the following steps to build the request:

  1. Выберите метод HTTP.Select the HTTP method.
  2. Выберите версию API, которую нужно использовать.Select the version of API that you want to use.
  3. Введите запрос в текстовое поле запроса.Type the query in the request text box.
  4. Нажмите Запуск запроса.Select Run Query.

В следующем примере показан запрос, возвращающий сведения о пользователях в демонстрационном клиенте:The following example shows a request that returns information about users in the demo tenant:

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

Примеры запросов представлены в песочнице Graph, чтобы вы могли быстрее запускать распространенные запросы.Sample queries are provided in Graph Explorer to enable you to more quickly run common requests. Чтобы просмотреть доступные примеры, выберите Показать другие примеры.To see the samples that are available, select show more samples. Выберите Вкл для набора примеров, который вы хотите просмотреть, и после закрытия окна выбора должен появиться список готовых запросов.Select On for the set of samples that you want to see, and then after closing the selection window, you should see a list of predefined requests.

После отправки запроса отображается код состояния и сообщение, а запрос выводится на вкладке Просмотр отклика.A status code and message are displayed after a request is sent and the response is shown in the Response Preview tab.

PostmanPostman

Postman — это инструмент, который можно использовать для создания и тестирования запросов с помощью API Microsoft Graph.Postman is a tool that you can use to build and test requests using the Microsoft Graph APIs. Вы можете скачать Postman по адресу: https://www.getpostman.com/.You can download Postman at: https://www.getpostman.com/. Чтобы взаимодействовать с Microsoft Graph в Postman, используйте коллекцию Microsoft Graph.To interact with Microsoft Graph in Postman, you use the Microsoft Graph collection.

Дополнительные сведения см. в статье Использование Postman с API Microsoft Graph.For more information, see Use Postman with the Microsoft Graph API.

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

Все готово для настройки Microsoft Graph.You're ready to get up and running with Microsoft Graph. Воспользуйтесь кратким руководством по началу работы или начните использовать один из наших пакетов SDK и примеров кода.Try the Quick Start, or get started using one of our SDKs and code samples.