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 中的 application 和 servicePrincipal 资源支持其 appId 属性的备用密钥标识符。

默认属性和$select

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

在某些情况下，在 Microsoft Graph 中，例如，用户和组资源的 GET 或 LIST 操作，仅返回所有属性的子集。 这些 默认属性 表示资源最常用的属性。 另一方面，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 中的关键概念，可创建相关资源网络。 例如， manager 和 directReports 属性扩展用户资源以提供组织层次结构。

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

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 资源的引用。

后续步骤

再次查看迁移清单