Table of contents

操作概述 |Graph API 概念Operations overview | Graph API concepts

Jimaco Brannian|上次更新日期: 2018/6/19
|
2 参与人员

Azure Active Directory (AD) Graph API 是与 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.Azure AD Graph API 公开要向其发送 HTTP 请求的 REST 终结点,以使用服务执行操作。Azure AD Graph API exposes REST endpoints that you send HTTP requests to in order to perform operations using the service.下面各节提供了关于以下内容的常规信息:如何对请求进行格式化;使用 Graph API 读取和写入目录资源、调用目录函数或操作,或针对目录执行查询时希望得到什么响应。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.有关执行特定操作目录资源的更多详细信息,请参阅 Azure AD Graph API 参考中的相应操作主题。For more detailed information about performing specific operations directory resources, see the appropriate operations topic in the Azure AD Graph API reference.

重要事项

强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.现在我们的开发工作将重点集中在 Microsoft Graph 上,没有计划对 Azure AD Graph API 进行进一步的改进。Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Azure AD Graph API 仍适用的方案数量非常有限;有关详细信息,请参阅 Office 开发人员中心中的博客文章 Microsoft Graph 或 Azure AD GraphThere 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.

对 Graph API 的成功请求必须发送到有效的终结点且格式正确,也就是说,它必须包含任何必需的标头,如有必要,在请求正文中包含 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.应用必须能够处理从 Graph API 收到的任何响应。The app must be able to handle any responses received from the Graph API.

本主题中的各节将有助于你了解请求的格式以及与 Graph API 一起使用时得到的响应。The sections in this topic will help you understand the format of requests and responses used with the Graph API.

身份验证和授权 Authentication and authorization

每个 Graph API 请求都必须具有通过附加的 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

Graph API 基于令牌中存在的 OAuth 2.0 权限范围执行授权。The Graph API performs authorization based on OAuth 2.0 permission scopes present in the token.有关 Graph API 公开的权限范围的详细信息,请参阅 Graph API Permission Scopes(Graph API 权限范围)For more information about the permission scopes that the Graph API exposes, see Graph API Permission Scopes.

为了使应用通过 Azure AD 进行身份验证并调用 Graph API,必须将其添加到租户中,并配置为需要 Windows Azure Active Directory 的权限(OAuth 2.0 权限范围)。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.有关添加和配置应用的信息,请参阅 Integrating Applications with 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.有关 Azure AD 中的 OAuth 2.0 的详细信息(包括支持的流和访问令牌),请参阅 OAuth 2.0 in Azure AD(Azure AD 中的 OAuth 2.0)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

若要使用 Graph API 执行操作,请采用支持的方法(通常为GET、POST、PATCH、PUT 或 DELETE)将 HTTP 请求发送至面向服务、资源集合、单个资源、资源的导航属性或由服务公开的函数或操作的终结点。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.

下面介绍了 Graph API 终结点的基本格式: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:

注意:在某些情况下,当读取资源集合时,可以将 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:

  • 通过租户对象 IDBy tenant object ID.这是创建租户时分配的 GUID。The GUID that was assigned when the tenant was created.它可以在 TenantDetail 对象的 objectId 属性中找到。This can be found in the objectId property of the TenantDetail object.以下 URL 介绍了如何通过使用租户对象 ID 对用户资源集合进行寻址: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.6https://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.它们可在 TenantDetail 对象的 verifiedDomains 属性中找到。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.6https://graph.windows.net/contoso.com/users?api-version=1.6.

  • 通过使用 myOrganization 别名By using the myOrganization alias.仅当使用 OAuth 授权码授权类型(3 重)身份验证时,此别名才可用;即当使用委托的权限范围时可用。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 中的对象 ID 或租户域。It replaces the object ID or tenant domain in the URL.使用此别名时,Graph API 将从附加到请求的令牌中提供的声明获取租户。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.6https://graph.windows.net/myorganization/users?api-version=1.6.

  • 通过使用 me 别名By using the me alias.仅当使用 OAuth 授权码授权类型(3 重)身份验证时,此别名才可用;即当使用委托的权限范围时可用。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 中的对象 ID 或租户域。It replaces the object ID or tenant domain in the URL.使用此别名时,Graph API 将从附加到请求的令牌中提供的声明获取用户。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.6https://graph.windows.net/me?api-version=1.6.

注意:使用 me 别名仅适用于针对已登录用户的操作。Note: You use me alias solely to target operations against the signed-in user.有关详细信息,请参阅已登录用户的操作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.

目标Target路径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 其实就是对象 IDFor 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.6https://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.6https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6.

图形 API 版本 {api-version} Graph API version {api-version}

可以使用 api-version 查询参数将 Graph API 的特定版本作为某操作的目标。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 面向使用 Graph API 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.

Graph API 支持以下 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

请参阅支持的查询、筛选和分页选项,以获取有关 Graph API 中支持的 OData 查询参数和及其限制的详细信息。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

下表显示了 Graph API 请求中使用的常见 HTTP 标头。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-Length如果存在请求正文则为必需。Required if request body is present.请求的长度(以字节为单位)。The length of the request in bytes.

下表显示了 Graph API 作为响应返回的常见 HTTP 标头。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-idSend and log the client-request-id.
  3. 记录 HTTP 响应代码和 request-idLog the HTTP response code and request-id.

当你请求提供帮助或支持时,此类日志中提供的信息将有助于 Microsoft 解决问题。Providing information in such logs will help Microsoft troubleshoot issues when you ask for help or support.

请求和响应正文Request and response bodies

可以在 JSON 或 XML 有效负载中发送 POST、PATCH 和 PUT 请求的请求主体。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.

我们强烈建议在图形 API 的请求和响应中使用 JSON 有效负载。这不仅出于性能原因,还因为 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

前面几节讨论了 Graph API 的基本请求的格式设置和响应。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:

  • 批处理:Graph API 支持批处理。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.有关 Graph API 批处理的详细信息,请参阅批处理For more information about batch processing with the Graph API, see Batch Processing.
  • 差异查询:Graph API 支持执行差异查询。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.有关 Graph API 差异查询的详细信息,请参阅差异查询For more information about differential query with the Graph API, see Differential Query.

其他资源 Additional resources

© 2018 Microsoft