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') |
在 Azure AD Graph 中,所有实体资源类型都具有名为 objectId 的唯一标识符 (或主键) 。 对于大多数 (实体,除非另有说明,) 此标识符在 Microsoft Graph 中称为 ID 。
除了主键,某些实体还支持备用密钥标识符。 例如,Microsoft Graph 中的 application 和 servicePrincipal 资源支持其 appId 属性的备用密钥标识符。
最佳做法是仅请求应用真正需要的属性。
$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
若要详细了解::
- 用户和组资源的默认属性,请参阅 用户 和 组
- 参数
$select
和其他受支持的 ODATA 查询参数,请参阅 使用查询参数自定义响应。 - 其他建议的优化,请参阅 最佳做法。
关系 (或导航属性) 是 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
资源的引用。