Azure Active Directory 图形 APIAzure Active Directory Graph API


从 2019 年 2 月开始,我们开始弃用某些旧版 Azure Active Directory Graph API,改为使用 Microsoft Graph API。As of February 2019, we started the process to deprecate some earlier versions of Azure Active Directory Graph API in favor of the Microsoft Graph API.

有关详细信息、更新和期限,请参阅 Office 开发人员中心的 Microsoft Graph 或 Azure AD GraphFor details, updates, and time frames, see Microsoft Graph or the Azure AD Graph in the Office Dev Center.

展望未来,应用程序将使用 Microsoft Graph API。Moving forward, applications should use the Microsoft Graph API.

本文适用于 Azure AD 图形 API。This article applies to Azure AD Graph API. 有关与 Microsoft Graph API 相关的类似信息,请参阅使用 Microsoft Graph APIFor similar info related to Microsoft Graph API, see Use the Microsoft Graph API.

Azure Active Directory 图形 API 通过 REST API 终结点提供对 Azure AD 的编程访问权限。The Azure Active Directory Graph API provides programmatic access to Azure AD through REST API endpoints. 应用程序可以使用 Azure AD 图形 API 对目录数据和对象执行创建、读取、更新和删除 (CRUD) 操作。Applications can use Azure AD Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. 例如,Azure AD 图形 API 支持对用户对象执行以下常见操作: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. 若要对目录调用 Azure AD 图形 API,必须向 Azure AD 注册应用程序。To call Azure AD Graph API on a directory, your application must be registered with Azure AD. 应用程序还必须有权访问 Azure AD 图形 API。Your application must also be granted access to Azure AD Graph API. 通常可以通过用户或管理员同意流来实现此访问。This access is normally achieved through a user or admin consent flow.

若要开始使用 Azure Active Directory 图形 API,请参阅 Azure AD 图形 API 快速入门指南,或查看交互式 Azure AD 图形 API 参考文档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.


Azure AD 图形 API 提供以下功能:Azure AD Graph API provides the following features:

  • REST API 终结点:Azure AD 图形 API 是一个 RESTful 服务,该服务由使用标准 HTTP 请求访问的终结点组成。REST API Endpoints: Azure AD Graph API is a RESTful service comprised of endpoints that are accessed using standard HTTP requests. Azure AD 图形 API 支持对请求和响应使用 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 进行身份验证:必须在请求的 Authorization 标头中追加 JSON Web 令牌 (JWT),以便对向 Azure AD 图形 API 发出的每个请求进行身份验证。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. 可以使用 OAuth 2.0 客户端凭据流或授权代码授予流来获取调用 Graph 所需的令牌。You can use the OAuth 2.0 client credentials flow or the authorization code grant flow to acquire a token to call the Graph. 有关详细信息,请参阅 Azure AD 中的 OAuth 2.0For more information, OAuth 2.0 in Azure AD.

  • 基于角色的授权 (RBAC) :安全组用于在 Azure AD 图形 API 中执行 RBAC。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.

  • 差异查询:如果要查看两个时间段之间对目录所做的更改,而不对 Azure AD 图形 API 进行频繁的查询,可以发出差异查询请求。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. 有关详细信息,请参阅 Azure AD 图形 API 差异查询For more information, see Azure AD Graph API differential query.

  • 目录扩展:可将自定义属性添加到目录对象,而无需外部数据存储。Directory Extensions: You can add custom properties to directory objects without requiring an external data store. 例如,如果应用程序需要每个用户的 Skype ID 属性,则可以在目录中注册新属性,即可在每个用户对象上获取该属性。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. 有关详细信息,请参阅 Azure AD 图形 API 目录架构扩展For more information, see Azure AD Graph API directory schema extensions.

  • 受权限范围保护:Azure AD 图形 API 公开权限范围,支持使用 OAuth 2.0 对 Azure AD 数据进行安全访问。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 operate in the background without a signed-in user being present and use application-defined role-based access control

      委派和应用程序权限范围都代表 Azure AD 图形 API 公开的特权,且客户端应用程序可通过 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. Azure AD 图形 API 权限范围提供有关可供客户端应用程序使用的内容的信息。Azure AD Graph API permission scopes provides information on what's available for use by your client application.


Azure AD 图形 API 可实现许多应用程序方案。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 交互的 Web 应用程序,用于执行将许可证分配给用户等任务。The developer is building a web application that interacts with Azure AD to perform tasks such as assigning a license to a user. 此任务需要访问 Azure AD 图形 API,因此开发人员在 Azure AD 中注册单租户应用程序,并为 Azure AD 图形 API 配置读取和写入权限。This task requires access to the 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. 然后,将应用程序配置为使用其自己的凭据或当前登录用户的凭据来获取调用 Azure AD 图形 API 所需的令牌。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 the Azure AD Graph API.
  • 服务型软件应用程序(多租户) :在此方案中,独立软件供应商 (ISV) 将开发一个托管多租户 Web 应用程序,该应用程序为使用 Azure AD 的其他组织提供用户管理功能。Software as a Service Application (Multi-Tenant): In this scenario, an independent software vendor (ISV) is developing a hosted multi-tenant web application that provides user management features for other organizations that use Azure AD. 这些功能需要访问目录对象,因此该应用程序需要调用 Azure AD 图形 API。These features require access to directory objects, so the application needs to call the Azure AD Graph API. 开发人员在 Azure AD 中注册该应用程序,将它配置为需要对 Azure AD 图形 API 的读取和写入权限,然后启用了外部访问,这样其他组织便可以同意在其目录中使用该应用程序。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. 然后,授予许可将为该应用程序提供对用户目录中的 Azure AD 图形 API 的请求权限。Granting consent will then give the application those requested permissions to Azure AD Graph API in the user’s directory. 有关许可框架的详细信息,请参阅许可框架概述For more information on the consent framework, see Overview of the consent framework.

后续步骤Next steps

若要开始使用 Azure Active Directory 图形 API,请参阅以下主题:To begin using the Azure Active Directory Graph API, see the following topics: