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
若要详细了解：：
- 用户和组资源的默认属性，请参阅 用户 和 组
- 参数
$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 资源的引用。