本文是 步骤 1 的一部分:查看迁移应用的过程的 API 差异。
Microsoft Graph 中的许多功能的工作方式与 Azure AD (Azure AD) Graph 对应的 Azure Active Directory 类似。 但是,一些已更改或改进。 在这里,你将了解如何调整应用以利用这些差异。 通常,更改是次要的,但非常值得努力。
本文探讨 Microsoft Graph 如何处理:
- 目录架构扩展
- 差异查询
- 批处理
目录扩展
如果应用使用 Azure AD Graph 目录扩展,则可以继续使用与 Microsoft Graph 请求 URL 相同的基本 API () :
- 使用 extensionProperty 资源和关联的方法管理目录扩展定义。
- 使用 getAvailableExtensionProperties 操作获取可用扩展属性。
- 使用 GET 和用户读取扩展值,仅
$select通过v1.0终结点通过查询读取扩展值 - 使用 GET 搜索扩展值和
$filter - 使用 PATCH 更新扩展值
- 使用 PATCH (设置为 null) 删除扩展值
Microsoft Graph 提供增强的架构扩展开发人员体验,目前与 Azure AD Graph 目录扩展不向后兼容。 若要了解详细信息,请参阅 为应用程序选择扩展类型。
建议的迁移方法
如果 Azure AD Graph 应用使用目录扩展,请采用增量方法将应用迁移到 Microsoft Graph。
首先,将应用切换到使用 Microsoft 图形 API调用,但让应用继续利用 Azure AD Graph 目录扩展。
然后,可以切换到使用 Microsoft Graph 架构扩展。 在某些情况下,切换将不合适。 如果:
- 应用使用通过 AD Connect 创建的目录扩展
- 应用设置其他应用在令牌声明中使用的目录扩展值
- 应用设置动态成员身份规则中使用的目录扩展值
注意:尚不支持使用可选声明或动态成员身份规则将 Microsoft Graph 架构扩展属性用作令牌中的声明。
若要切换到较新的 Microsoft Graph 架构扩展模型,需要:
- 使用 Microsoft Graph 定义新的架构扩展定义。
- 更新应用以支持新的架构扩展定义。
- 将数据从 Azure AD 架构扩展属性迁移到新的 Microsoft Graph 架构扩展属性。 不支持自动迁移数据。
差异查询
使用 Azure AD Graph 和 Microsoft Graph 可以使用查询跟踪更改。 这两个 API 之间的高级方法类似,但语法不同。
Azure AD Graph 调用这些差异查询。 在 Microsoft Graph 中,它们是 增量查询。
下表突出显示了关键相似之处和差异:
| 增量请求 | Azure AD Graph | Microsoft Graph |
|---|---|---|
| 初始数据请求 | 使用查询参数:GET /groups?deltaLink= |
使用函数: GET /groups/delta |
| 获取新更改 | GET /groups?deltaLink={deltaToken} |
GET /groups/delta?$deltaToken={deltaToken} |
| 从现在起同步 | 使用自定义 HTTP 标头: ocp-aad-dq-include-only-delta-token: true |
使用查询参数: GET /groups/delta?$deltaToken=latest |
| 跟踪 directoryObjects 的更改 | 获取同一操作中多个资源 (用户和组) 的更改: GET /directoryObject?$filter=isof('User') or isof('Group')&deltaLink= |
对 Microsoft Graph 使用单独的查询,每个资源使用一个查询。 |
| 获取资源和关系更改 | 如果资源具有关系,则所有请求都将返回资源和关系更改。 | GET /groups/delta?$expand=members |
| 指示新项和已更改项的响应 | <ul><li>表示使用其标准表示形式新建的实例。</li><li>更新的实例的 ID 至少包含已 更新的属性。 可能包含其他属性。</li><li>关系表示为 directoryLinkChange 类型。</li></ul> |
<ul><li>表示使用其标准表示形式新建的实例。</li><li>更新的实例的 ID 至少包含已 更新的属性。 可能包含其他属性。</li><li>关系表示为标准资源表示形式的注释。 这些批注使用格式 propertyName@delta,例如 members@delta 组的成员身份更改。</li></ul> |
| 指示已删除项的响应 | 指示已删除的项,其中 aad.isDeleted 的附加属性设置为 true。 | 指示包含已删除批注的 @已删除项。 它还可能包含一个原因代码,该代码指示项目是否已删除,但可以还原或永久删除。 |
如果应用已存储状态数据,请考虑使用前面显示的“从现在开始同步”来帮助管理到增量查询的转换。
批处理
Azure AD Graph 使用名为多部分 MIME 消息的系统来管理批处理。 Microsoft Graph 使用 JSON 批处理 在单个批处理操作中最多允许 20 个请求。 JSON 批处理机制非常简单,尤其是与 JSON 分析库一起使用。 它还允许对批处理操作进行排序。 但是,它与 Azure AD Graph 批处理方法不向后兼容。
后续步骤
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 dkershaw10)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
