Table of contents

Общие сведения об операциях | Общие понятия API GraphOperations overview | Graph API concepts

Jimaco Brannian|Последнее обновление: 19.06.2018
|
2 Участники

API Graph Azure Active Directory (AD) — это служба, совместимая с OData 3.0. Ее можно использовать для чтения и изменения таких объектов, как пользователи, группы и контакты в клиенте.The Azure Active Directory (AD) Graph API is an OData 3.0 compliant service that you can use to read and modify objects such as users, groups, and contacts in a tenant.API Graph Azure AD предоставляет конечные точки REST, в которые вы отправляете HTTP-запросы для выполнения операций с использованием службы.Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service.В следующих разделах представлены общие сведения о форматировании запросов и возможные ответы при использовании API Graph для чтения и записи ресурсов каталога, для вызова функций или действий каталога или для выполнения запросов к каталогу.The following sections provide general information about how to format requests and what to expect in responses when you use the Graph API to read and write directory resources, call directory functions or actions, or perform queries against the directory.Более подробные сведения о выполнении определенных операций с ресурсами каталога см. в разделе Справочника по API Graph Azure AD о соответствующей операции.For more detailed information about performing specific operations directory resources, see the appropriate operations topic in the Azure AD Graph API reference.

Важно

Для доступа к ресурсам Azure Active Directory мы настоятельно рекомендуем использовать Microsoft Graph вместо API Azure AD Graph.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Теперь наши усилия сфокусированы на разработке Microsoft Graph; дальнейшее продвижение API Azure AD Graph мы не планируем.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Есть очень мало сценариев, в которых по-прежнему можно использовать API Azure AD Graph. Дополнительные сведения об этом см. в записи блога в центре разработчиков Office, где сравниваются решения Microsoft Graph и Azure AD Graph.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Успешный запрос в API Graph должен направляться в действительную конечную точку и иметь правильный формат, т. е. содержать все необходимые заголовки и, если необходимо, полезные данные JSON в теле запроса.A successful request to the Graph API must be addressed to a valid endpoint and be well-formatted, that is, it must contain any required headers and, if necessary, a JSON payload in the request body.Выполняющее запрос приложение должно включать маркер, полученный из Azure AD и подтверждающий, что оно авторизовано для доступа к ресурсам, на которые направлен запрос.The app making the request must include a token received from Azure AD that proves that it is authorized to access the resources targeted by the request.Кроме того, приложение должно быть способно обрабатывать любые ответы, поступающие от API Graph.The app must be able to handle any responses received from the Graph API.

Разделы этой статьи помогут вам понять формат запросов и ответов, используемый в API Graph.The sections in this topic will help you understand the format of requests and responses used with the Graph API.

Аутентификация и авторизация Authentication and authorization

Каждый запрос в API Graph должен включать прикрепленный токен носителя, присвоенный ему Azure Active Directory.Every request to the Graph API must have a bearer token issued by Azure Active Directory attached.Токен передает сведения о приложении, пользователе, выполнившем вход (в случае делегированных разрешений), проверке подлинности и операциях в каталоге, которые ваше приложение имеет право выполнять.The token carries information about your app, the signed-in user (in the case of delegated permissions), authentication, and the operations on the directory that your app is authorized to perform.Токен передается в заголовке Authorization запроса.This token is carried in the Authorization header of the request.Например (для краткости токен сокращен):For example (the token has been shortened for brevity):

Authorization: Bearer eyJ0eX ... FWSXfwtQ

API Graph выполняет авторизацию на основе областей разрешений доступа OAuth 2.0, указанных в токене.The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token.Дополнительные сведения об областях разрешений, предоставляемых API Graph, см. в статье Области разрешений API Graph.For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

Чтобы приложение проходило проверку подлинности в Azure AD и вызывало API Graph, необходимо добавить его в клиент и настроить для требований разрешений (областей разрешений доступа OAuth 2.0) для Windows Azure Active Directory.In order for your app to authenticate with Azure AD and call the Graph API, you must add it to your tenant and configure it to require permissions (OAuth 2.0 permission scopes) for Windows Azure Active Directory.Сведения о добавлении и настройке приложения см. в статье Интеграция приложений с Azure Active Directory.For information about adding and configuring an app, see Integrating Applications with Azure Active Directory.

В Azure AD используется протокол проверки подлинности OAuth 2.0.Azure AD uses the OAuth 2.0 authentication protocol.Дополнительные сведения об OAuth 2.0 в Azure AD, включая поддерживаемые потоки и маркеры доступа, см. в статье OAuth 2.0 в Azure AD.You can learn more about OAuth 2.0 in Azure AD, including supported flows and access tokens in OAuth 2.0 in Azure AD.

Адресация конечных точек Endpoint addressing

Для выполнения операций с использованием API Graph вы отправляете HTTP-запросы с поддерживаемым методом (обычно это GET, POST, PATCH, PUT или DELETE) к конечной точке, ориентированной на службу, коллекцию ресурсов, отдельный ресурс, свойство навигации ресурса либо предоставляемую службой функцию или действие.To perform operations with the Graph API, you send HTTP requests with a supported method - typically GET, POST, PATCH, PUT, or DELETE -- to an endpoint that targets the service, a resource collection, an individual resource, a navigation property of a resource, or a function or action exposed by the service.Конечные точки предоставляются в виде URL-адресов.Endpoints are expressed as URLs.

Ниже описан основной формат конечной точки API Graph:The following describes the basic format of a Graph API endpoint:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}

URL-адрес состоит из следующих компонентов:The following components comprise the URL:

  • Корень службы: корень службы для всех запросов API Graph — это https://graph.windows.net.Service Root: The service root for all Graph API requests is https://graph.windows.net.
  • Идентификатор клиента {tenant_id}: идентификатор клиента, на который направлен запрос.Tenant Identifier {tenant_id}: The identifier for the tenant that the request targets.
  • Путь к ресурсу {resource_path}: путь к ресурсу — это, например, пользователь или группа, на которых направлен запрос.Resource path {resource_path}: The path to the resource -- for example, a user or a group -- that the request targets.
  • Версия API Graph {api_version}: версия Graph API, на которую направлен запрос.Graph API Version {api_version}: The version of the Graph API targeted by the request.Выражается как параметр запроса и является обязательным.This is expressed as a query parameter and is required.

Примечание. В некоторых случаях при чтении коллекций ресурсов в запросы OData могут добавляться параметры для фильтрации, заказа и постраничного представления набора результатов.Note: In some cases, when reading resource collections, OData query parameters can be added to the request to filter, order, and page the result set.Дополнительные сведения см. в разделе Параметры запроса OData в этой статье.For more information, see the OData query parameters section in this topic.

Идентификатор клиента {tenant_id} Tenant identifier {tenant_id}

Целевой клиент запроса можно указать одним из четырех способов:You can specify the target tenant of a request in one of four ways:

  • По идентификатору объекта клиента.By tenant object ID.Это GUID, назначенный при создании клиента.The GUID that was assigned when the tenant was created.Его можно найти в свойстве objectId объекта TenantDetail.This can be found in the objectId property of the TenantDetail object.Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей по идентификатору объекта клиента:The following URL shows how to address the users resource collection by using the tenant object ID:
    https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.

  • По проверенному (зарегистрированному) доменному имени.By verified (registered) domain name.Это одно из доменных имен, зарегистрированных для клиента.One of the domain names that are registered for the tenant.Они хранятся в свойстве verifiedDomains объекта TenantDetail.These can be found in the verifiedDomains property of the TenantDetail object.Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей клиента с доменом contoso.com:The following URL shows how to address the users resource collection of a tenant that has the domain contoso.com:
    https://graph.windows.net/contoso.com/users?api-version=1.6.https://graph.windows.net/contoso.com/users?api-version=1.6.

  • С использованием псевдонима myOrganization.By using the myOrganization alias.Этот псевдоним доступен только при использовании проверки подлинности OAuth Authorization Code Grant (трехступенчатой), т. е. области делегированных разрешений.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.Прописные и строчные буквы в псевдониме не различаются.The alias is not case sensitive.В URL-адресе заменяется идентификатор объекта или домен клиента.It replaces the object ID or tenant domain in the URL.При использовании псевдонима API-интерфейс Graph определяет клиента на основе утверждений в токене, присоединенном к запросу.When the alias is used, Graph API derives the tenant from the claims presented in the token attached to the request.Следующий URL-адрес показывает, как обращаться к коллекции ресурсов пользователей с помощью псевдонима:The following URL shows how to address the users resource collection of a tenant using this alias:
    https://graph.windows.net/myorganization/users?api-version=1.6.https://graph.windows.net/myorganization/users?api-version=1.6.

  • С использованием псевдонима me.By using the me alias.Этот псевдоним доступен только при использовании проверки подлинности OAuth Authorization Code Grant (трехступенчатой), т. е. области делегированных разрешений.This alias is only available when using OAuth Authorization Code Grant type (3-legged) authentication; that is, when using a delegated permission scope.Прописные и строчные буквы в псевдониме не различаются.The alias is not case sensitive.В URL-адресе заменяется идентификатор объекта или домен клиента.It replaces the object ID or tenant domain in the URL.При использовании псевдонима API-интерфейс Graph определяет пользователя на основе утверждений в токене, присоединенном к запросу.When the alias is used, Graph API derives the user from the claims presented in the token attached to the request.Для обращения к пользователю, выполнившему вход с использованием псевдонима, используется следующий URL-адрес:The following URL to address the signed-in user using this alias:
    https://graph.windows.net/me?api-version=1.6.https://graph.windows.net/me?api-version=1.6.

Примечание. Псевдоним me используется исключительно для операций с пользователем, выполнившим вход.Note: You use me alias solely to target operations against the signed-in user.Дополнительные сведения см. в статье Signed-in User Operations.For more information, see Signed-in User Operations.

Путь к ресурсу {resource_path} Resource path {resource_path}

Параметр {resource_path} указывается по-разному в зависимости от того, к чему вы обращаетесь — к коллекции ресурсов, отдельному ресурсу, свойству навигации ресурса либо функции или действию, предоставляемым в клиенте или в ресурсе.You specify the {resource_path} differently depending on whether you are targeting a resource collection, an individual resource, a navigation property of a resource, a function or action exposed on the tenant, or a function or action exposed on a resource.

TargetTargetПутьPathОписаниеExplanation
Метаданные службыService Metadata/$metadataВозвращает документ метаданных службы.Returns the service metadata document.В следующем примере демонстрируется обращение к метаданным службы с использованием клиента contoso.com:The following example targets service metadata using the contoso.com tenant:
https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Примечание. Для чтения метаданных службы проверка подлинности не требуется.Note: No authentication is necessary to read the service metadata.
Коллекция ресурсовResource collection/{resource_collection}Обращается к коллекции ресурсов, например к пользователям или группам в клиенте.Targets a resource collection, such as users or groups in the tenant.Этот путь можно использовать для чтения ресурсов в коллекции, а также (в зависимости от типа ресурсов) для создания нового ресурса в клиенте.You can use this path to read resources in the collection, and, depending on the resource type, to create a new resource in the tenant.В большинстве случаев результирующий набор, возвращенный операцией чтения, можно уточнить, добавив параметры запроса для фильтрации, упорядочивания или постраничного представления результатов.In many cases the result set returned by a read can be further refined by the addition of query parameters to filter, order, or page the results.В следующем примере демонстрируется обращение к коллекции пользователей:The following example targets the user collection:
https://graph.windows.net/myorganization/users?api-version=1.6
Отдельный ресурсSingle resource/{resource_collection}/{resource_id}Обращается к определенному ресурсу в клиенте, такому как пользователь, контакт, организация или группа.Targets a specific resource in a tenant, such as a user, organizational contact, or group.Для большинства ресурсов resource_id — это идентификатор объекта.For most resources the resource_id is the object ID.Некоторые ресурсы позволяют использовать дополнительные спецификаторы, например, пользователей можно также указывать с помощью имени субъекта-пользователя (UPN).Some resources allow additional specifiers; for example, users can be also specified by user principal name (UPN).В зависимости от ресурса этот путь можно использовать для получения объявленных свойств ресурса, изменения объявленных свойств или удаления ресурса.Depending on the resource, you can use this path to get the declared properties of the resource, to modify its declared properties, or to delete the resource.В следующем примере демонстрируется обращение к пользователю john@contoso.com:The following example targets the user john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6
Свойство навигации (объекты)Navigation property (objects)/{resource_collection}/{resource_id}/{property_name}Обращается к свойству навигации определенного ресурса, такого как руководитель пользователя или его членство в группах либо члены группы.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Этот путь можно использовать для получения объекта или объектов, на которые ссылается свойство навигации.You can use this path to return the object or objects referenced by the target navigation property.В следующем примере демонстрируется обращение к руководителю john@contoso.com:The following example targets the manager of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6

Примечание. Эта форма адресации доступна только для операций чтения.Note: This form of addressing is only available for reads.
Свойство навигации (ссылки)Navigation property (links)/{resource_collection}/{resource_id}/$links/{property_name}Обращается к свойству навигации определенного ресурса, такого как руководитель пользователя или его членство в группах либо члены группы.Targets a navigation property of a specific resource, such as a user's manager or group memberships, or a group's members.Эту форму адресации можно использовать для чтения и изменения свойства навигации.You can use this form of addressing to both read and modify a navigation property.При чтении объекты, на которые ссылается свойство, возвращаются в виде одной или нескольких ссылок в тексте ответа.On reads, the objects referenced by the property are returned as one or more links in the response body.При записи объекты обозначаются как одна или несколько ссылок в тексте запроса.On writes, the objects are specified as one or more links in the request body.В следующем примере демонстрируется обращение к свойству руководителя john@contoso.com:The following example targets the manager property of john@contoso.com:
https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6
Функции и действия, предоставляемые в клиентеFunctions or actions exposed on the tenant/{function_name}Обращается к функции или действию, предоставляемым в клиенте.Targets a function or action exposed at the tenant.Функции и действия обычно вызываются с помощью запроса POST и могут включать текст запроса.Functions and actions are typically invoked with a POST Request and may include a request body.В следующем примере показано обращение к функции isMemberOf:The following example targets the isMemberOf function:
https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.https://graph.windows.net/myorganization/isMemberOf?api-version=1.6.
Функции и действия, предоставляемые в ресурсеFunctions or actions exposed on a resource./{resource_collection}/{resource_id}/{function_name}Обращается к функции или действию, предоставляемым в ресурсе.Targets a function or action exposed on a resource.Функции и действия обычно вызываются с помощью запроса POST и могут включать текст запроса.Functions and actions are typically invoked with a POST Request and may include a request body.В следующем примере показано обращение к функции getMemberGroups:The following example targets the getMemberGroups function:
https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

Версия API Graph {api-version} Graph API version {api-version}

Параметр запроса api-version используется для обращения к определенной версии API Graph для выполнения операции.You use the api-version query parameter to target a specific version of the Graph API for an operation.Этот параметр обязательный.This parameter is required.

Параметр api-version может иметь одно из следующих значений:The value for the api-version parameter can be one of the following:

  • "beta""beta"
  • "1.6""1.6"
  • "1.5""1.5"
  • "2013/11/08""2013/11/08"
  • "2013/04/05""2013/04/05"

Например, следующий URL-адрес обращается к коллекции пользователей, которые используют API Graph версии 1.6:For example the following URL targets the user collection using Graph API version 1.6:

https://graph.windows.net/myorganization/users?api-version=1.6

Дополнительные сведения о версиях и отличиях версий по функциональным возможностям см. в статье Управление версиями.For more information about versions and feature changes between versions, see Versioning.

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

Во многих случаях при чтении коллекции ресурсов можно фильтровать, сортировать и разбивать на страницы результирующий набор, добавляя к запросу параметры запроса OData.In many cases when you read a collection of resources, you can filter, sort, and page the result set by attaching OData query parameters to your request.

API Graph поддерживает следующие параметры запроса OData:The Graph API supports the following Odata query parameters:

  • $filter$filter
  • $batch$batch
  • $expand$expand
  • $orderby$orderby
  • $top$top
  • $skiptoken и previous-page$skiptoken and previous-page

Дополнительные сведения о поддерживаемых параметрах запросов OData и связанных с ними ограничениях в API Graph см. в статье Поддерживаемые запросы, фильтры и операции разбиения на страницы.See Supported Queries, Filters, and Paging Options for more information about supported OData query parameters and their limitations in the Graph API.

Заголовки запросов и ответов Request and response headers

В следующей таблице показаны основные заголовки HTTP, которые используются в запросах при работе с API Graph.The following table shows common HTTP headers used in requests with the Graph API.Этот список не претендует на полноту.It is not meant to be comprehensive.

Заголовок запросаRequest HeaderОписаниеDescription
АвторизацияAuthorizationОбязательный параметр.Required.Токен носителя, выданный службой Azure Active Directory.A bearer token issued by Azure Active Directory.Дополнительные сведения см. в статье Проверка подлинности и авторизация.See Authentication and Authorization in this topic for more information.
Content-TypeContent-TypeТребуется, если присутствует текст запроса.Required if request body is present.Тип носителя содержимого для текста запроса.The media type of the content in the request body.Используйте application/json.Use application/json.Параметры могут быть включены с типом носителя.Parameters may be included with the media type.
Примечание. application/atom+xml и application/xml (ссылки) поддерживаются, но не рекомендуются из соображений производительности, а также потому, что в дальнейшем поддержка XML будет прекращена.Note: application/atom+xml and application/xml (for links) are supported but are not recommended both for performance reasons and because support for XML will be deprecated in a future release.
Content-LengthContent-LengthТребуется, если присутствует текст запроса.Required if request body is present.Длина запроса в байтах.The length of the request in bytes.

В следующей таблице показаны основные заголовки HTTP, которые API Graph возвращает в ответах.The following table shows common HTTP headers returned in responses by the Graph API.Этот список не претендует на полноту.It is not meant to be comprehensive.

Заголовок ответаResponse HeaderОписаниеDescription
Content-TypeContent-TypeТип носителя содержимого в тексте запроса.The media type of the content in the response body.Значение по умолчанию — application/json.The default is application/json.По умолчанию в ответ на запросы миниатюрных фотографий пользователей возвращается image/jpeg.Requests for user thumbnail photos return image/jpeg by default.
РасположениеLocationВозвращается в ответах на запросы POST, которые создают в каталоге новый ресурс (объект).Returned in responses to POST requests that create a new resource (object) in the directory.Содержит URI вновь созданного ресурса.Contains the URI of the newly created resource.
ocp-aad-diagnostics-server-nameocp-aad-diagnostics-server-nameИдентификатор сервера, который выполняет запрашиваемую операцию.The identifier for the server that performed the requested operation.
ocp-aad-session-keyocp-aad-session-keyКлюч, который идентифицирует текущий сеанс в службе каталога.The key that identifies the current session with the directory service.

Для каждого запроса рекомендуется выполнять как минимум следующие действия:At a minimum, we recommend you do the following for each request:

  1. Зарегистрировать точное время подачи запроса.Log an accurate time stamp of the request submission.
  2. Отправить и зарегистрировать client-request-id.Send and log the client-request-id.
  3. Зарегистрировать код HTTP-ответа и request-id.Log the HTTP response code and request-id.

Предоставленные таким образом сведения помогут Майкрософт устранить неполадки при обращении за помощью или поддержкой.Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

Тексты запросов и ответов Request and response bodies

Тексты запросов POST, PUT и PATCH можно отправлять в полезных данных JSON или XML.Request bodies for POST, PATCH, and PUT requests can be sent in JSON or XML payloads.Ответы сервера могут возвращаться в полезных данных JSON или XML.Server responses can be returned in JSON or XML payloads.Полезные данные могут указываться в тексте запроса с помощью заголовка Content-Type, а в ответе — с помощью заголовка Accept.You can specify the payload in request bodies by using the Content-Type request header and in responses by using the Accept request header.

Мы настоятельно рекомендуем использовать полезные данные JSON в запросах и ответах в API Graph. Это связано с соображениями производительности, а также с тем, что в дальнейшем поддержка XML будет прекращена.We strongly recommend that you use JSON payloads in requests and responses with the Graph API. This is both for performance reasons and because XML will be deprecated in a future release.

Дополнительные функции Advanced features

В предыдущих разделах обсуждалось форматирование основных запросов и ответов в API Graph.The preceding sections discussed the formatting of basic requests and responses with the Graph API.Расширенные возможности могут добавить дополнительные параметры строк запроса или значительно отличаться в текстах запросов и ответов от основных операций, описанных ранее в этой статье.More advanced features may add additional query string parameters or have significantly different request and response bodies than the basic operations discussed previously in this topic.

Эти функции включают перечисленные ниже.These features include:

  • Пакетная обработка: API Graph поддерживает пакетную обработку.Batch Processing: The Graph API supports batching.Пакетная отправка запросов уменьшает циклы приема-передачи запросов на сервере, что позволяет сократить нагрузку на сеть и ускорить выполнение операций.Sending requests in batches reduces round trips to the server, which reduces network overhead and helps your operations complete more quickly.Дополнительные сведения о пакетной обработке в API Graph см. в статье Пакетная обработка.For more information about batch processing with the Graph API, see Batch Processing.
  • Разностный запрос: API Graph поддерживает выполнение разностных запросов.Differential Query: The Graph API supports performing differential queries.Разностный запрос позволяет возвращать изменения в определенных сущностях в клиенте, возникших между поданными в разное время запросами.Differential query allows you to return changes to specific entities in a tenant between requests issued at different times.Эта функция часто используется для синхронизации локального хранилища с изменениями в клиенте.This feature is often used to sync a local store with changes on the tenant.Дополнительные сведения о разностном запросе в API Graph см. в статье Разностный запрос.For more information about differential query with the Graph API, see Differential Query.

Дополнительные ресурсы Additional resources

© 2018 Microsoft