使用英语阅读

通过


Azure AD Graph 与 Microsoft Graph 之间的请求差异

本文是步骤 1:查看应用迁移过程的 API 差异的一部分。

Microsoft Graph 和 Azure Active Directory (Azure AD) 图形 API 都是支持查询参数的 OData 约定的 REST API。 但是,语法在这两个 API 之间有所不同。

使用 Graph 资源管理器 针对你自己的数据尝试这些请求模式,并在更新代码之前了解请求和响应的差异。

基本请求

下表突出显示了两个 API 之间的main请求差异:

请求详细信息 Azure AD Graph Microsoft Graph
请求语法 https://graph.windows.net/{tenant_id}/{resource}?{version}&query-parameters https://graph.microsoft.com/{version}/{resource}?query-parameters
服务终结点:
-全球 https://graph.windows.net https://graph.microsoft.com
- US Gov L4 https://graph.microsoftazure.us https://graph.microsoft.us
- US Gov L5 (DOD) https://graph.microsoftazure.us https://dod-graph.microsoft.us
- 德国 (已停用) https://graph.cloudapi.de https://graph.microsoft.de
- 中国 (世纪互联) https://graph.chinacloudapi.cn https://microsoftgraph.chinacloudapi.cn
{tenant_id} 在请求中指定租户 ID 或域名。 可选。 租户 ID 是从访问令牌推断出来的。

如果指定租户 ID,请使用以下语法: https://graph.microsoft.com/{version}/{tenant_id}/{resource}?query-parameters
{version} 使用所需的查询参数在请求中指定 Azure AD Graph 的发布版本。 在请求中指定 Microsoft Graph 的发布版本,作为服务终结点后面的 URL 路径的一部分。

Microsoft Graph 和 Azure AD Graph 的查询参数语法相同。 但是,Microsoft Graph 比 Azure AD Graph 支持更多的查询参数和查询功能。

示例请求比较

假设需要 Contoso 租户中名称以“Dan”开头的所有用户的列表。 下表显示了 Azure AD Graph 与 Microsoft Graph 之间的请求差异。

Azure AD Graph Microsoft Graph
GET https://graph.windows.net/contoso.com/users?$filter=startswith(givenName,'Dan')&api-version=1.6 GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName,'Dan')

主键标识符:objectId 与 id

在 Azure AD Graph 中,所有实体资源类型都具有名为 objectId 的唯一标识符 (或主键) 。 对于大多数 (实体,除非另有说明,) 此标识符在 Microsoft Graph 中称为 ID

除了主键,某些实体还支持备用密钥标识符。 例如,Microsoft Graph 中的 applicationservicePrincipal 资源支持其 appId 属性的备用密钥标识符。

默认属性和$select

最佳做法是仅请求应用真正需要的属性。 $select在 GET 请求中使用查询参数将响应自定义为仅包含应用所需的属性。

在某些情况下,在 Microsoft Graph 中,例如,用户资源的 GETLIST 操作,仅返回所有属性的子集。 这些 默认属性 表示资源最常用的属性。 另一方面,Azure AD Graph 返回相应资源的所有属性的完整集。 如果资源仅返回默认属性,则应用需要使用查询参数显式请求其他属性 $select

为了说明差异,请使用 Graph 资源管理器运行以下请求并比较不同的响应。

GET https://graph.microsoft.com/v1.0/me/
GET https://graph.microsoft.com/beta/me/

请注意响应中的差异。 版本 /beta 返回的属性比 /v1.0 版本多。 例如,如果应用依赖于 streetAddress 属性,则需要更新请求 v1.0 ,以使用 $select 查询参数请求 streetAddress 属性以及应用所需的其他属性。 例如:

https://graph.microsoft.com/v1.0/me?$select=displayName,streetAddress,city,state,postalCode

若要详细了解::

关系和导航属性

关系 (或导航属性) 是 Azure AD Graph 和 Microsoft Graph 中的关键概念,可创建相关资源网络。 例如, managerdirectReports 属性扩展用户资源以提供组织层次结构。

关系还定义成员身份,例如用户所属的组、属于组或目录角色的成员,等等。

Azure AD Graph 请求使用 $links 指示资源之间的关系。 Microsoft Graph 改用 OData v4.01 $ref 表示法。

下表显示了几个示例:

任务 Azure AD Graph Microsoft Graph
添加成员 POST /groups/{id}/$links/members POST /groups/{id}/members/$ref
列出成员链接 GET /groups/{id}/$links/members GET /groups/{id}/members/$ref
列出成员 GET /groups/{id}/members GET /groups/{id}/members
删除成员 DELETE /groups/{id}/$links/members/{id} DELETE /groups/{id}/members/{id}/$ref

将应用迁移到 Microsoft Graph 时,请更新用于 $links 关联要使用的 $ref 资源的引用。

后续步骤