API Graph Azure Active DirectoryAzure Active Directory Graph API

Важно!

Мы настоятельно рекомендуем использовать для доступа к ресурсам 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. Дополнительные сведения см. в записи блога Microsoft Graph or the Azure AD Graph (Microsoft Graph или Azure AD Graph) в Центре разработчика Office.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 Azure Active Directory обеспечивает программный доступ к Azure AD через конечные точки API-интерфейса Rest Azure AD.The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. Приложения могут использовать API Azure AD Graph для выполнения операций создания, чтения, обновления и удаления (CRUD) с данными и объектами каталогов.Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. Например, API Azure AD Graph поддерживает следующие операции для объекта-пользователя.For example, Azure AD Graph API supports the following common operations for a user object:

  • Создание нового пользователя в каталоге.Create a new user in a directory
  • Получение подробных свойств пользователя, например его группы.Get a user’s detailed properties, such as their groups
  • Обновление свойств пользователя, например его расположения и номера телефона, или изменение его пароля.Update a user’s properties, such as their location and phone number, or change their password
  • Проверка членства в группах для доступа на основе ролей.Check a user’s group membership for role-based access
  • Отключение или полное удаление учетной записи пользователя.Disable a user’s account or delete it entirely

Кроме того, вы можете выполнять те же операции с другими объектами, например группами или приложениями.Additionally, you can perform similar operations on other objects such as groups and applications. Для вызова API Azure AD Graph для каталога приложения должны быть зарегистрированы в Azure AD.To call Azure AD Graph API on a directory, your application must be registered with Azure AD. Приложение должно также иметь доступ к API Azure AD Graph.Your application must also be granted access to Azure AD Graph API. Обычно доступ обеспечивается с помощью потока согласия пользователя или администратора.This access is normally achieved through a user or admin consent flow.

Чтобы начать использовать API Graph Azure Active Directory, ознакомьтесь с кратким руководством по началу работы с API Azure AD Graph или просмотрите справочную документацию по API Azure AD Graph.To begin using the Azure Active Directory Graph API, see the Azure AD Graph API Quickstart Guide, or view the interactive Azure AD Graph API reference documentation.

ФункцииFeatures

API Azure AD Graph предоставляет следующие возможности.Azure AD Graph API provides the following features:

  • Конечные точки REST API. Служба API Azure AD Graph соответствует ограничениям REST. Она состоит из конечных точек, доступ к которым можно получить с помощью стандартных HTTP-запросов.REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. API Azure AD Graph поддерживает содержимое в формате XML или в виде нотаций объектов JavaScript (JSON) для запросов и ответов.Azure AD Graph API supports XML or Javascript Object Notation (JSON) content types for requests and responses. Дополнительные сведения см. в справочнике по Azure AD Graph REST API.For more information, see Azure AD Graph REST API Reference.
  • Аутентификация с помощью Azure AD. Каждый запрос API Azure AD Graph должен пройти аутентификацию путем добавления веб-маркеров JSON (JWT) в заголовок авторизации запроса.Authentication with Azure AD: Every request to Azure AD Graph API must be authenticated by appending a JSON Web Token (JWT) in the Authorization header of the request. Чтобы получить этот токен, нужно отправить запрос к конечной точке токена Azure AD и предоставить действительные учетные данные.This token is acquired by making a request to Azure AD’s token endpoint and providing valid credentials. Чтобы получить токен для вызова Graph, можно использовать поток клиентских учетных данных OAuth 2.0 или поток предоставления кода авторизации.You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. Дополнительные сведения см. в статье Авторизация доступа к веб-приложениям с помощью OAuth 2.0 и Azure Active Directory.For more information, OAuth 2.0 in Azure AD.
  • Ролевая авторизация (RBAC). Для реализации RBAC в API Azure AD Graph используются группы безопасности.Role-Based Authorization (RBAC): Security groups are used to perform RBAC in Azure AD Graph API. Например, чтобы определить, имеет ли пользователь доступ к определенному ресурсу, приложение может вызвать операцию Проверка членства в группе (транзитивно), которая возвращает значение true или false.For example, if you want to determine whether a user has access to a specific resource, the application can call the Check Group Membership (transitive) operation, which returns true or false.
  • Дифференциальный запрос. Если вы хотите проверить наличие изменений в каталоге в промежутке между двумя периодами времени, не отправляя частые запросы к API Azure AD Graph, вы можете сделать дифференциальный запрос.Differential Query: Differential query allows you to track changes in a directory between two time periods without having to make frequent queries to Azure AD Graph API. Этот тип запроса возвращает только изменения, внесенные в промежутке между предыдущим дифференциальным запросом и текущим запросом.This type of request will return only the changes made between the previous differential query request and the current request. Дополнительные сведения см. в статье Разностный запрос | Общие понятия API Graph.For more information, see Azure AD Graph API Differential Query.
  • Расширения каталога. Вы можете добавлять пользовательские свойства к объектам каталога без потребности во внешнем хранилище данных.Directory Extensions: ou can add custom properties to directory objects without requiring an external data store. Например, если приложению требуется свойство "Идентификатор Skype" для каждого пользователя, вы можете зарегистрировать новое свойство в каталоге, и оно будет доступно для каждого объекта-пользователя.For example, if your application requires a Skype ID property for each user, you can register the new property in the directory and it will be available for use on every user object. Дополнительные сведения см. в статье Расширения схемы каталогов | Общие понятия API Graph.For more information, see Azure AD Graph API Directory Schema Extensions.
  • Защита с помощью областей разрешений. API Azure AD Graph предоставляет области разрешений, которые обеспечивают безопасный доступ к данным Azure AD с помощью OAuth 2.0.Secured by permission scopes: Azure AD Graph API exposes permission scopes that enable secure access to Azure AD data using OAuth 2.0. Он поддерживает широкий набор типов клиентских приложений, включая:It supports a variety of client app types, including:

    • пользовательские интерфейсы, которым предоставляется делегированный доступ к данным с помощью разрешения, получаемого от пользователя, выполнившего вход (делегирование);user interfaces that are given delegated access to data via authorization from the signed-in user (delegated)
    • приложения-службы или управляющие программы, работающие в фоновом режиме без наличия вошедшего пользователя и использующие определяемое приложением управление доступом на основе ролей.service/daemon applications that operation in the background without a signed-in user being present and use application-defined role-based access control

      Обе эти области разрешений (с делегированием и приложениями) представляют привилегию, предоставляемую API Azure AD Graph, и могут запрашиваться клиентскими приложениями с помощью функций разрешений для зарегистрированных приложений на портале Azure.Both delegated and application permissions represent a privilege exposed by the Azure AD Graph API and can be requested by client applications through application registration permissions features in the Azure portal. Области разрешений API Azure AD Graph предоставляют сведения о том, что доступно клиентскому приложению.Azure AD Graph API Permission Scopes provides information on what's available for use by your client application.

СценарииScenarios

API Azure AD Graph поддерживает многие сценарии приложений.Azure AD Graph API enables many application scenarios. Ниже перечислены наиболее распространенные сценарии.The following scenarios are the most common:

  • Бизнес-приложение (однотенантное). В этом сценарии разработчик работает на предприятие, у которого есть подписка Office 365.Line of Business (Single Tenant) Application: In this scenario, an enterprise developer works for an organization that has an Office 365 subscription. Разработчик создает веб-приложение, взаимодействующее с Azure AD для выполнения задач, таких как назначение лицензии пользователю.The developer is building a web application that interacts with Azure AD to perform tasks such assigning a license to a user. Эта задача требует доступа к API Azure AD Graph, поэтому разработчик регистрирует одноклиентское приложение в Azure AD и настраивает разрешения чтения и записи для API Azure AD Graph.This task requires access to Azure AD Graph API, so the developer registers the single tenant application in Azure AD and configures read and write permissions for Azure AD Graph API. Затем приложение настраивается для использования собственных учетных данных или учетных данных пользователя, вошедшего в систему, чтобы получить маркер для вызова API Azure AD Graph.Then the application is configured to use either its own credentials or those of the currently sign-in user to acquire a token to call Azure AD Graph API.
  • Программное обеспечение как приложение-служба (мультитенантное). В этом сценарии независимый поставщик программного обеспечения разрабатывает и размещенное мультитенантное веб-приложение, которое предоставляет пользователю функции управления для других организаций, использующих Azure AD.Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. Для этих функций требуется доступ к объектам каталога, поэтому приложение должно вызвать API Azure AD Graph.These features require access to directory objects, and so the application needs to call Azure AD Graph API. Разработчик регистрирует приложение в Azure AD, настраивает его, чтобы оно требовало разрешения чтения и записи для API Azure AD Graph, а затем включает внешний доступ, чтобы другие организации могли давать согласие на использование приложения в своем каталоге.The developer registers the application in Azure AD, configures it to require read and write permissions for Azure AD Graph API, and then enables external access so that other organizations can consent to use the application in their directory. Когда пользователь в другой организации впервые проходит проверку подлинности в приложении, он видит диалоговое окно с разрешениями, которые запрашивает приложение.When a user in another organization authenticates to the application for the first time, they are shown a consent dialog with the permissions the application is requesting. Если пользователь предоставит согласие, приложение получит запрошенные разрешения для API Azure AD Graph в каталоге пользователя.Granting consent will then give the application those requested permissions to Azure AD Graph API in the user’s directory. Дополнительные сведения об инфраструктуре согласия см. в статье Интеграция приложений с Azure Active Directory.For more information on the consent framework, see Overview of the Consent Framework.

См. такжеSee Also

Краткое руководство по API Graph Azure ADAzure AD Graph API Quickstart Guide

Документация по REST для Azure AD GraphAzure AD Graph REST documentation

Руководство разработчика по Azure Active DirectoryAzure Active Directory developer's guide