如何:使用 Azure AD 图形 APIHow to: Use the Azure AD Graph API

Azure Active Directory (Azure AD) 图形 API 通过 OData REST API 终结点提供对 Azure AD 的编程访问权限。The Azure Active Directory (Azure AD) Graph API provides programmatic access to Azure AD through OData 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, you can use Azure AD Graph API to create a new user, view or update user’s properties, change user’s password, check group membership for role-based access, disable, or delete the user. 有关 Azure AD 图形 API 功能和应用方案的详细信息,请参阅 Azure AD 图形 APIAzure AD 图形 API 先决条件For more information on Azure AD Graph API features and application scenarios, see Azure AD Graph API and Azure AD Graph API Prerequisites.

本文适用于 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.

如何构造图形 API URLHow to construct a Graph API URL

在 Graph API 中,若要访问要对其执行 CRUD 操作的目录数据和对象(即资源或实体),可以使用基于开放数据 (OData) 协议的 URL。In Graph API, to access directory data and objects (in other words, resources or entities) against which you want to perform CRUD operations, you can use URLs based on the Open Data (OData) Protocol. 图形 API 中使用的 URL 包括四个主要部分:服务根、租户标识符、资源路径和查询字符串选项: https://graph.chinacloudapi.cn/{tenant-identifier}/{resource-path}?[query-parameters]The URLs used in Graph API consist of four main parts: service root, tenant identifier, resource path, and query string options: https://graph.chinacloudapi.cn/{tenant-identifier}/{resource-path}?[query-parameters]. 以下面的 URL 为例: https://graph.chinacloudapi.cn/contoso.com/groups?api-version=1.6Take the example of the following URL: https://graph.chinacloudapi.cn/contoso.com/groups?api-version=1.6.

  • 服务根:在 Azure AD 图形 API 中,服务根始终是 https://graph.chinacloudapi.cnService Root: In Azure AD Graph API, the service root is always https://graph.chinacloudapi.cn.
  • 租户标识符:此部分可以是已验证(注册)的域名,在前面示例中为 contoso.com。Tenant identifier: This section can be a verified (registered) domain name, in the preceding example, contoso.com. 也可以是租户对象 ID 或者“myorganization”或“me”别名。It can also be a tenant object ID or the “myorganization” or “me” alias. 有关详细信息,请参阅对 Azure AD 图形 API 中的实体和操作进行寻址For more information, see Addressing entities and operations in Azure AD Graph API.
  • 资源路径:URL 的此部分标识要交互的资源(用户、组、特定用户或特定组,等等)。在上面的示例中,它是用于对资源集寻址的顶级“组”。Resource path: This section of a URL identifies the resource to be interacted with (users, groups, a particular user, or a particular group, etc.) In the example above, it is the top level “groups” to address that resource set. 也可以对特定的实体寻址,例如“users/{objectId}”或“users/userPrincipalName”。You can also address a specific entity, for example “users/{objectId}” or “users/userPrincipalName”.
  • 查询参数:问号 (?) 用于分隔资源路径部分与查询参数部分。Query parameters: A question mark (?) separates the resource path section from the query parameters section. 需要对 Azure AD 图形 API 中的所有请求提供“api-version”查询参数。The “api-version” query parameter is required on all requests in Azure AD Graph API. Azure AD 图形 API 还支持以下 OData 查询选项: $filter$orderby$expand$top$formatAzure AD Graph API also supports the following OData query options: $filter, $orderby, $expand, $top, and $format. 当前不支持以下查询选项: $count$inlinecount$skipThe following query options are not currently supported: $count, $inlinecount, and $skip. 有关详细信息,请参阅 Azure AD 图形 API 支持的查询、筛选和分页选项For more information, see Supported Queries, Filters, and Paging Options in Azure AD Graph API.

图形 API 版本Graph API versions

可以在“api-version”查询参数中指定图形 API 请求的版本。You specify the version for a Graph API request in the “api-version” query parameter. 对于版本 1.5 及更高版本,使用数字版本值:api-version=1.6。For version 1.5 and later, you use a numerical version value; api-version=1.6. 对于早期版本,使用遵循 YYYY-MM-DD 格式的日期字符串;例如,api-version=2013-11-08。For earlier versions, you use a date string that adheres to the format YYYY-MM-DD; for example, api-version=2013-11-08. 对于预览功能,使用字符串“beta”;例如,api-version=beta。For preview features, use the string “beta”; for example, api-version=beta. 若要详细了解图形 API 版本之间的差异,请参阅 Azure AD 图形 API 版本控制For more information about differences between Graph API versions, see Azure AD Graph API versioning.

图形 API 元数据Graph API metadata

要返回Azure AD 图形 API 元数据文件,请在 URL 中的租户标识符后面添加“$metadata”段。例如,以下 URL 将返回演示公司元数据:https://graph.chinacloudapi.cn/GraphDir1.partner.onmschina.cn/$metadata?api-version=1.6To return the Azure AD Graph API metadata file, add the “$metadata” segment after the tenant-identifier in the URL For example, the following URL returns metadata for a demo company: https://graph.chinacloudapi.cn/GraphDir1.partner.onmschina.cn/$metadata?api-version=1.6. 可以在 Web 浏览器的地址栏中输入此 URL 来查看元数据。You can enter this URL in the address bar of a web browser to see the metadata. 返回的 CSDL 元数据文档描述了实体和复杂类型及其属性,以及请求的 Graph API 版本公开的函数和操作。The CSDL metadata document returned describes the entities and complex types, their properties, and the functions and actions exposed by the version of Graph API you requested. 省略 api-version 参数将返回最新版本的元数据。Omitting the api-version parameter returns metadata for the most recent version.

常见查询Common queries

Azure AD 图形 API 常见查询列出了可与 Azure AD Graph 配合使用的常见查询,包括可用于访问目录中顶层资源的查询,以及用于在目录中执行操作的查询。Azure AD Graph API common queries lists common queries that can be used with the Azure AD Graph, including queries that can be used to access top-level resources in your directory and queries to perform operations in your directory.

例如, https://graph.chinacloudapi.cn/contoso.com/tenantDetails?api-version=1.6 返回目录 contoso.com 的公司信息。For example, https://graph.chinacloudapi.cn/contoso.com/tenantDetails?api-version=1.6 returns company information for directory contoso.com.

https://graph.chinacloudapi.cn/contoso.com/users?api-version=1.6 列出目录 contoso.com 中的所有用户对象。Or https://graph.chinacloudapi.cn/contoso.com/users?api-version=1.6 lists all user objects in the directory contoso.com.

使用 Azure AD 图形资源管理器Using the Azure AD Graph Explorer

生成应用程序时,可以使用 Azure AD 图形 API 的 Azure AD 图形资源管理器来查询目录数据。You can use the Azure AD Graph Explorer for the Azure AD Graph API to query the directory data as you build your application.

以下屏幕截图是导航到 Azure AD 图形资源管理器,登录并输入 https://graph.chinacloudapi.cn/GraphDir1.partner.onmschina.cn/users?api-version=1.6 以显示已登录用户目录中的所有用户时会看到的输出:The following screenshot is the output you would see if you were to navigate to the Azure AD Graph Explorer, sign in, and enter https://graph.chinacloudapi.cn/GraphDir1.partner.onmschina.cn/users?api-version=1.6 to display all the users in the signed-in user's directory:

Azure AD Graph API Explorer 中的示例输出

加载 Azure AD 图形资源管理器:若要加载该工具,请导航到 https://developer.microsoft.com/zh-cn/graph/graph-explorer-china/Load the Azure AD Graph Explorer: To load the tool, navigate to https://developer.microsoft.com/zh-cn/graph/graph-explorer-china/. 单击“登录” ,并使用 Azure AD 帐户凭据登录,以针对租户运行 Azure AD 图形资源管理器。Click Login and sign-in with your Azure AD account credentials to run the Azure AD Graph Explorer against your tenant. 如果针对自己的租户运行 Azure AD 图形资源管理器,则你或管理员需要在登录期间表示同意。If you run Azure AD Graph Explorer against your own tenant, either you or your administrator needs to consent during sign-in. 如果拥有 Office 365 订阅,则会自动拥有 Azure AD 租户。If you have an Office 365 subscription, you automatically have an Azure AD tenant. 用于登录 Office 365 的凭据事实上就是 Azure AD 帐户,可以在 Azure AD 图形资源管理器中使用这些凭据。The credentials you use to sign in to Office 365 are, in fact, Azure AD accounts, and you can use these credentials with Azure AD Graph Explorer.

运行查询:若要运行查询,请在请求文本框中键入查询,然后单击“获取” 或单击 Enter 键。Run a query: To run a query, type your query in the request text box and click GET or click the enter key. 结果将显示在响应框中。The results are displayed in the response box. 例如,https://graph.chinacloudapi.cn/myorganization/groups?api-version=1.6 将列出已登录用户目录中的所有组对象。For example, https://graph.chinacloudapi.cn/myorganization/groups?api-version=1.6 lists all group objects in the signed-in user's directory.

请注意,Azure AD 图形资源管理器具有以下功能与限制:Note the following features and limitations of the Azure AD Graph Explorer:

  • 对资源集的自动完成功能。Autocomplete capability on resource sets. 若要查看此功能,请单击请求文本框(公司 URL 出现的位置)。To see this functionality, click on the request text box (where the company URL appears). 可以从下拉列表中选择资源集。You can select a resource set from the dropdown list.
  • 请求历史记录。Request history.
  • 支持“me”和“myorganization”寻址别名。Supports the “me” and “myorganization” addressing aliases. 例如,可以使用 https://graph.chinacloudapi.cn/me?api-version=1.6 来返回登录用户的用户对象,或者使用 https://graph.chinacloudapi.cn/myorganization/users?api-version=1.6 来返回已登录用户目录中的所有用户。For example, you can use https://graph.chinacloudapi.cn/me?api-version=1.6 to return the user object of the signed-in user or https://graph.chinacloudapi.cn/myorganization/users?api-version=1.6 to return all users in the signed-in user's directory.
  • 支持使用 POSTGETPATCHDELETE 对自己的目录执行完整的 CRUD 操作。Supports full CRUD operations against your own directory using POST, GET, PATCH and DELETE.
  • 响应标头部分。A response headers section. 此部分可用来帮助排查运行查询时所发生的问题。This section can be used to help troubleshoot issues that occur when running queries.
  • 具有展开和折叠功能的 JSON 响应查看器。A JSON viewer for the response with expand and collapse capabilities.
  • 不支持显示或上传缩略图照片。No support for displaying or uploading a thumbnail photo.

使用 Fiddler 写入目录Using Fiddler to write to the directory

在本快速入门指南中,可以使用 Fiddler Web 调试器来练习对 Azure AD 目录执行“写入”操作。For the purposes of this Quickstart guide, you can use the Fiddler Web Debugger to practice performing ‘write’ operations against your Azure AD directory. 例如,可以获取和上传用户的个人资料照片(无法使用 Azure AD 图形资源管理器实现此目的)。For example, you can get and upload a user's profile photo (which is not possible with Azure AD Graph Explorer). 若要了解更多信息并安装 Fiddler,请参阅 https://www.telerik.com/fiddlerFor more information and to install Fiddler, see https://www.telerik.com/fiddler.

以下示例使用 Fiddler Web 调试器在 Azure AD 目录中创建一个新的安全组“MyTestGroup”。In the example below, you use Fiddler Web Debugger to create a new security group ‘MyTestGroup’ in your Azure AD directory.

获取访问令牌:若要访问 Azure AD Graph,客户端需要先成功地向 Azure AD 进行身份验证。Obtain an access token: To access Azure AD Graph, clients are required to successfully authenticate to Azure AD first. 有关详细信息,请参阅 Azure AD 的身份验证方案For more information, see Authentication scenarios for Azure AD.

撰写和运行查询:完成以下步骤:Compose and run a query: Complete the following steps:

  1. 打开 Fiddler Web 调试器并切换到“编辑器” 选项卡。Open Fiddler Web Debugger and switch to the Composer tab.

  2. 由于要创建新的安全组,因此请从下拉菜单中选择“发布” 作为 HTTP 方法。Since you want to create a new security group, select Post as the HTTP method from the pull-down menu. 有关对组对象的操作和权限的详细信息,请参阅 Azure AD Graph REST API 参考中的For more information about operations and permissions on a group object, see Group within the Azure AD Graph REST API reference.

  3. 在“发布” 旁边的字段中,键入以下请求 URL:https://graph.chinacloudapi.cn/{mytenantdomain}/groups?api-version=1.6In the field next to Post, type in the following request URL: https://graph.chinacloudapi.cn/{mytenantdomain}/groups?api-version=1.6.

    Note

    必须将 {mytenantdomain} 替换成自己的 Azure AD 目录的域名。You must substitute {mytenantdomain} with the domain name of your own Azure AD directory.

  4. 在紧靠在“发布”下拉列表下面的字段中,键入以下 HTTP 标头:In the field directly below Post pull-down, type the following HTTP header:

    Host: graph.chinacloudapi.cn
    Authorization: Bearer <your access token>
    Content-Type: application/json
    

    Note

    将 <your access token> 替换为你的 Azure AD 目录的访问令牌。Substitute your <your access token> with the access token for your Azure AD directory.

  5. 在“请求正文” 字段中键入以下 JSON:In the Request body field, type the following JSON:

        {
            "displayName":"MyTestGroup",
            "mailNickname":"MyTestGroup",
            "mailEnabled":"false",
            "securityEnabled": true
        }
    

    有关创建组的详细信息,请参阅 创建组For more information about creating groups, see Create Group.

有关 Graph 公开的 Azure AD 实体和类型的详细信息,以及有关可以使用 Graph 对它们执行的操作的信息,请参阅 Azure AD Graph REST API 参考For more information on Azure AD entities and types that are exposed by Graph and information about the operations that can be performed on them with Graph, see Azure AD Graph REST API reference.

后续步骤Next steps