操作概述 |Graph API 概念

项目
03/24/2016

Azure Active Directory (AD) Graph API 是与 OData 3.0 兼容的服务，可用于读取和修改租户中的对象（如用户、组和联系人）。 Azure AD Graph API 公开要向其发送 HTTP 请求的 REST 终结点，以使用服务执行操作。下面各节提供了关于以下内容的常规信息: 如何对请求进行格式化；使用 Graph API 读取和写入目录资源、调用目录函数或操作，或针对目录执行查询时希望得到什么响应。有关执行特定操作目录资源的更多详细信息，请参阅 Azure AD Graph API 参考中的相应操作主题。

对 Graph API 的成功请求必须发送到有效的终结点且格式正确，也就是说，它必须包含任何必需的标头，如有必要，在请求正文中包含 JSON 有效负载。发出请求的应用必须包括从 Azure AD 收到的令牌，以便证明其有权访问请求的资源。应用必须能够处理从 Graph API 收到的任何响应。

本主题中的各节将有助于你了解请求的格式以及与 Graph API 一起使用时得到的响应。

重要

强烈建议使用 Microsoft Graph 代替 Azure AD Graph API 来访问 Azure Active Directory 资源。现在我们的开发工作将重点集中在 Microsoft Graph 上，没有计划对 Azure AD Graph API 进行进一步的改进。Azure AD Graph API 仍适用的方案数量非常有限；有关详细信息，请参阅 Office 开发人员中心中的博客文章 Microsoft Graph 或 Azure AD Graph。

身份验证和授权

每个 Graph API 请求都必须具有通过附加的 Azure Active Directory 颁发的持有者令牌。此令牌具有关于你的应用、已登录用户（有委派权限的情况下）、身份验证和你的应用有权执行的目录上的操作的信息。请求的 Authorization 标头中携带有此令牌。例如（为简洁起见已缩短令牌）：

Authorization: Bearer eyJ0eX ... FWSXfwtQ

Graph API 基于令牌中存在的 OAuth 2.0 权限范围执行授权。有关 Graph API 公开的权限范围的详细信息，请参阅 Graph API Permission Scopes（Graph API 权限范围）。

为了使应用通过 Azure AD 进行身份验证并调用 Graph API，必须将其添加到租户中，并配置为需要 Windows Azure Active Directory 的权限（OAuth 2.0 权限范围）。有关添加和配置应用的信息，请参阅 Integrating Applications with Azure Active Directory（将应用程序与 Azure Active Directory 集成）。

Azure AD 使用的是 OAuth 2.0 身份验证协议。有关 Azure AD 中的 OAuth 2.0 的详细信息（包括支持的流和访问令牌），请参阅 OAuth 2.0 in Azure AD（Azure AD 中的 OAuth 2.0）。

终结点寻址

若要使用 Graph API 执行操作，请采用支持的方法（通常为GET、POST、PATCH、PUT 或 DELETE）将 HTTP 请求发送至面向服务、资源集合、单个资源、资源的导航属性或由服务公开的函数或操作的终结点。终结点表示为 URL。

下面介绍了 Graph API 终结点的基本格式：

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

以下组件构成 URL：

服务根: 所有 Graph API 请求的服务根都是 https://graph.windows.net。
租户标识符 {tenant_id}: 接收请求的租户的标识符。
资源路径 {resource_path}: 接收请求的资源（例如，用户或组）的路径。
Graph API 版本 {api_version}: 请求面向的 Graph API 的版本。它表示为一个查询参数，并且是必需的。

注意: 在某些情况下，当读取资源集合时，可以将 OData 查询参数添加到请求以对结果集进行筛选、排序和分页。有关详细信息，请参阅本主题中的 OData 查询参数部分。

租户标识符 {tenant_id}

可以使用以下四种方法之一指定请求的目标租户：

通过租户对象 ID。这是创建租户时分配的 GUID。这可以在 TenantDetail 对象的 objectId 属性中找到。以下 URL 介绍了如何通过使用租户对象 ID 对用户资源集合进行寻址:
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6。
通过已验证（注册）的域名。这是为租户注册的域名之一。这些可在 TenantDetail 对象的 verifiedDomains 属性中找到。以下 URL 介绍了如何对域为 contoso.com 的租户的用户资源集合进行寻址:
https://graph.windows.net/contoso.com/users?api-version=1.6。
通过使用 myOrganization 别名。仅当使用 OAuth 授权码授权类型（3 重）身份验证时，此别名才可用；即当使用委托的权限范围时可用。此别名不区分大小写。它将替换 URL 中的对象 ID 或租户域。使用此别名时，Graph API 将从附加到请求的令牌中提供的声明获取租户。以下 URL 介绍了如何通过使用此别名对租户的用户资源集合进行寻址:
https://graph.windows.net/myorganization/users?api-version=1.6。
通过使用 me 别名。仅当使用 OAuth 授权码授权类型（3 重）身份验证时，此别名才可用；即当使用委托的权限范围时可用。此别名不区分大小写。它将替换 URL 中的对象 ID 或租户域。使用此别名时，Graph API 将从附加到请求的令牌中提供的声明获取用户。以下 URL 通过使用此别名对已登录用户进行寻址:
https://graph.windows.net/me?api-version=1.6。

注意: 使用 me 别名仅适用于针对已登录用户的操作。有关详细信息，请参阅已登录用户的操作。

资源路径 {resource_path}

你可以以不同的方式指定 {resource_path}，具体取决于你是面向资源集合、单独的资源、资源的导航属性、租户上公开的函数或操作，还是面向资源上公开的函数或操作。

目标	路径	说明
服务元数据	`/$metadata`	返回服务元数据文档。下例是针对使用 contoso.com 租户的服务元数据: `https://graph.windows.net/contoso.com/$metadata?api-version=1.6` 注意: 读取服务元数据不需要身份验证。
资源集合	`/{resource_collection}`	面向资源集合（如租户中的用户或组）。可使用此路径读取集合中的资源以及根据资源类型在租户中创建新的资源类型。在许多情况下，通过添加查询参数对结果进行筛选、排序和分页，可进一步优化读取返回的结果集。下例是针对用户集合: `https://graph.windows.net/myorganization/users?api-version=1.6`
单个资源	`/{resource_collection}/{resource_id}`	面向租户中的特定资源，例如用户、组织联系人或组。对于大多数资源而言，`resource_id` 其实就是对象 ID 但某些资源还允许使用其他说明符，例如，还可以通过用户主体名称 (UPN) 指定用户。根据具体的资源，可以使用此路径来获取该资源的声明属性，以修改其声明属性或删除资源。下例是针对用户 john@contoso.com: `https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6`
导航属性（对象）	`/{resource_collection}/{resource_id}/{property_name}`	面向特定资源的导航属性，如用户的经理、组成员身份或组成员。可以使用此路径返回目标导航属性所引用的一个或多个对象。下例是针对 john@contoso.com 的经理: `https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6` 注意: 这种格式的寻址仅适用于读取操作。
导航属性（链接）	`/{resource_collection}/{resource_id}/$links/{property_name}`	面向特定资源的导航属性，如用户的经理、组成员身份或组成员。可以使用这种格式的寻址读取和修改导航属性。读取时，属性引用的对象将作为响应正文中的一个或多个链接返回。写入时，这些对象将指定为请求正文中的一个或多个链接。下例是针对 john@contoso.com 的经理属性: `https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6`
租户上公开的函数或操作	`/{function_name}`	面向租户上公开的函数或操作。通常使用 POST 请求调用函数和操作，并且可能包括请求正文。下例是针对 isMemberOf 函数: `https://graph.windows.net/myorganization/isMemberOf?api-version=1.6`。
资源上公开的函数或操作。	`/{resource_collection}/{resource_id}/{function_name}`	面向资源上公开的函数或操作。通常使用 POST 请求调用函数和操作，并且可能包括请求正文。下例是针对 getMemberGroups 函数: `https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6`。

Graph API 版本 {api-version}

可以使用 api-version 查询参数将 Graph API 的特定版本作为某操作的目标。此参数是必需的。

api-version 参数的值可以是下列内容之一：

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

例如，以下 URL 面向使用 Graph API 1.6 版本的用户集合：

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

有关版本之间的版本和功能更改的详细信息，请参阅版本控制。

OData 查询参数

在许多情况下，当读取资源集时，可以通过将 OData 查询参数附加到请求中来对结果集进行筛选、排序和分页。

Graph API 支持以下 OData 查询参数：

$filter
$batch
$expand
$orderby
$top
$skiptoken 和 previous-page

请参阅支持的查询、筛选和分页选项，以获取有关 Graph API 中支持的 OData 查询参数和及其限制的详细信息。

请求和响应标头

下表显示了 Graph API 请求中使用的常见 HTTP 标头。并不意味着它是全面的。

请求标头	描述
授权	必需。 Azure Active Directory 颁发的持有者令牌。请参阅本主题中的身份验证和授权获取详细信息。
内容类型	如果存在请求正文则为必需。请求主体中内容的媒体类型。使用 application/json。媒体类型中可以包含参数。注意: 尽管支持 application/atom+xml 和 application/xml（用于链接），但出于性能原因以及考虑到以后的版本中还将弃用对 XML 的支持，因此不建议使用。
内容长度	如果存在请求正文则为必需。请求的长度（以字节为单位）。

下表显示了 Graph API 作为响应返回的常见 HTTP 标头。并不意味着它是全面的。

响应标头	描述
内容类型	响应正文中内容的媒体类型。默认为 application/json。默认情况下，对用户缩略图照片的请求将返回 image/jpeg。
位置	为响应 POST 请求（即在目录中新建资源（对象））而返回。包含最新创建的资源 URI。
ocp-aad-diagnostics-server-name	执行所请求操作的服务器的标识符。
ocp-aad-session-key	标识与目录服务进行的当前会话的键。

我们建议至少为每个请求执行以下操作：

记录请求提交的准确时间戳。
发送并记录 client-request-id。
记录 HTTP 响应代码和 request-id。

当你请求提供帮助或支持时，此类日志中提供的信息将有助于 Microsoft 解决问题。

请求和响应正文

可以在 JSON 或 XML 有效负载中发送 POST、PATCH 和 PUT 请求的请求主体。可以在 JSON 或 XML 有效负载中返回服务器响应。可以通过使用 Content-Type 请求标头在请求主体中指定有效负载，以及通过使用 Accept 请求标头作出响应。

我们强烈建议在 Graph API 的请求和响应中使用 JSON 有效负载。这不仅出于性能原因，还因为 XML 将在未来版本中弃用。

高级功能

前面几节讨论了 Graph API 的基本请求的格式设置和响应。与本主题中前面讨论的基础操作相比，更高级的功能还可以添加其他查询字符串参数或具有迥异的请求和响应正文。

这些功能包括：

批处理: Graph API 支持批处理。分批发送请求可以减少到服务器的往返行程，从而减少网络开销，并有助于更快速地完成操作。有关 Graph API 批处理的详细信息，请参阅批处理。
差异查询: Graph API 支持执行差异查询。差异查询使你可以在不同时间发出的请求之间将更改返回到租户中的特定实体。此功能通常用于将本地存储与租户上的更改进行同步。有关 Graph API 差异查询的详细信息，请参阅差异查询。

其他资源

Azure AD Graph API 参考