Azure AD Connect 同步 V2 终结点 API(公共预览版)Azure AD Connect sync V2 endpoint API (public preview)

Microsoft 已部署新的 Azure AD Connect 终结点 (API),可提高 Azure Active Directory 的同步服务操作性能。Microsoft has deployed a new endpoint (API) for Azure AD Connect that improves the performance of the synchronization service operations to Azure Active Directory. 通过利用新的 V2 终结点,导出或导入 Azure AD 时的性能会有显著提升。By utilizing the new V2 endpoint, you will experience noticeable performance gains on export and import to Azure AD. 这一新终结点支持以下功能:This new endpoint supports the following:

  • 同步具有最多 25 万名成员的组syncing groups with up to 250k members
  • 提高导出和导入到 Azure AD 的性能performance gains on export and import to Azure AD

备注

目前,新终结点对写回的 Microsoft 365 组没有已配置的组大小限制。Currently, the new endpoint does not have a configured group size limit for Microsoft 365 groups that are written back. 这可能会影响 Active Directory 和同步周期延迟。This may have an effect on your Active Directory and sync cycle latencies. 建议以递增方式增加组大小。It is recommended to increase your group sizes incrementally.

先决条件Pre-requisites

为使用新的 V2 终结点,需要使用 Azure AD Connect 1.5.30.0 或更高版本,并按照以下部署步骤为 Azure AD Connect 服务器启用 V2 终结点。In order to use the new V2 endpoint, you will need to use Azure AD Connect version 1.5.30.0 or later and follow the deployment steps provided below to enable the V2 endpoint for your Azure AD Connect server.

备注

目前,此公共预览版仅适用于 Azure 全球云,不适用于国家云Currently, this public preview is only available in the Azure global cloud and not available for national clouds.

公共预览版限制Public preview limitations

尽管此版本已经过大量测试,但仍然可能会遇到问题。While this release has undergone extensive testing, you may still encounter issues. 此公共预览版的目标之一就是查找并修复任何此类问题。One of the goals of this public preview release is to find and fix any such issues.

重要

尽管为此公共预览版提供了支持,但 Microsoft 可能并不能每次都能够立即解决你可能遇到的所有问题。While support is provided for this public preview release, Microsoft may not always be able to fix all issues you may encounter immediately. 因此,建议先做出最佳判断,然后再在生产环境中部署此版本。For this reason, it is recommended that you use your best judgement before deploying this release in your production environment.

部署指南Deployment guidance

需要部署 Azure AD Connect 1.5.30.0 或更高版本才能使用 V2 终结点。You will need to deploy Azure AD Connect version 1.5.30.0 or later to use the V2 endpoint. 使用提供的链接进行下载。Use the link provided to download.

建议按照交叉迁移方法在环境中推出新的终结点。It is recommended that you follow the swing migration method for rolling out the new endpoint in your environment. 这将在事件中提供清晰的应变计划,即主要回滚必不可少。This will provide a clear contingency plan in the event, that a major rollback is necessary. 以下示例说明如何在这种情况下使用交叉迁移。The following example illustrates how a swing migration can be used in this scenario. 有关交叉迁移部署方法的详细信息,请参考提供的链接。For more information on the swing migration deployment method, refer to the link provided.

用于部署 V2 终结点的交叉迁移Swing migration for deploying V2 endpoint

以下步骤将指导你完成使用交叉方法部署 v2 终结点。The following steps will guide you through deploying the v2 endpoint using the swing method.

  1. 在当前过渡服务器上部署 V2 终结点。Deploy the V2 endpoint on the current staging server. 在以下步骤中,此服务器将称为 V2 服务器。This server will be known as the V2 server in the steps below. 当前活动服务器将继续使用 V1 终结点处理生产工作负载,该服务器将称为 V1 服务器。The current active server will continue to process the production workload using the V1 endpoint, which will be called the V1 server below.
  2. 验证 V2 服务器是否仍按预期处理导入。Validate that the V2 server is still processing imports as expected. 在此阶段,不会将大型组预配到 Azure AD 或本地 AD,但可以验证升级是否不会对现有同步过程造成其他任何意外影响。At this stage, large groups will not be provisioned to Azure AD or on-prem AD, but you will be able to verify that the upgrade did not result in any other unexpected impact to the existing synchronization process.
  3. 验证完成后,将 V2 服务器切换为活动服务器,将 V1 服务器切换为过渡服务器 。Once validation is complete, switch the V2 server to be the active server and the V1 server to be the staging server. 此时,如果启用了组写回功能,则在要同步的范围内的大型组将预配到 Azure AD,并且大型 Microsoft 365 统一组将预配到 AD。At this time, large groups that are in scope to be synced will be provisioned to Azure AD, as well as large Microsoft 365 unified groups will be provisioned to AD, if group writeback is enabled.
  4. 验证 V2 服务器是否可以成功执行和处理大型组。Validate that the V2 server is performing and processing large groups successfully. 可以选择停留在此步骤,并监视同步过程一段时间。You may choose to stay at this step and monitor the synchronization process for a period.

备注

如果需要转换回之前的配置,可以从 V2 服务器交叉迁移回 V1 服务器 。If you need to transition back to your previous configuration, you can perform a swing migration from the V2 server back to the V1 server . 由于 V1 终结点不支持成员数超过 5 万的组,因此随后将删除 Azure AD 或本地 AD 中由 Azure AD Connect 预配的任何大型组。Since the V1 endpoint does not support groups with over 50k members, any large group that was provisioned by Azure AD Connect, in either Azure AD or on-prem AD, will be subsequently deleted. 4. 确定要使用 V2 终结点时,升级 V1 服务器以开始使用 V2 终结点。Once you are confident in using the V2 endpoint, upgrade the V1 server to begin using the V2 endpoint.

性能影响的预期Expectations of performance impact

使用 V2 终结点时,性能提升取决于同步组的数量、大小及其改动(将用户添加为组成员以及将用户从组成员中删除而产生的活动)。When using the V2 endpoint, performance gains are a function of the number of synced groups, size of those groups, and their group churn (the activity resulting from adding and removing users as members of the group). 在不增加同步组数量、大小或改动的情况下,使用新的终结点应该可以缩短导出和导入到 Azure AD 所需的时间。Using the new endpoint, without increasing the number, size, or churn of the synced groups, should result in shorter times for export and import to Azure AD.

但同步大型组时,所需的额外处理可能会抵消性能提升。However, the performance gains can be negated by the additional processing required when syncing large groups. 在同步过程中添加过多大型组,最终可能会增加整体同步时间。You could end up increasing the overall sync time by adding a too many large groups to the sync process.

为更好地了解添加新组将如何影响同步性能,建议先只同步成员数少于 10 万的少量大型组。To gain a better understanding of how the addition of the new groups will impact your sync performance, it is recommended that you start by syncing only a few large groups with less than 100k members. 然后,可以通过 OU、属性或最大组大小筛选来引入更多的组,增加组的数量和大小。You can then increase the number and size of groups by bringing more of them in scope, through OU, attribute, or max group size filtering. Azure AD 连接器(而不是本地 AD 连接器)的导出和导入任务将实现性能改进。The performance improvements will be realized on the export and import tasks for the Azure AD connector, not the on-premises AD connector.

逐步部署Deployment step by step

以下三个阶段是部署新 V2 终结点的详细示例。The following three phases are an in-depth example of deploying the new V2 endpoint. 使用这些阶段作为部署指南。Use the phases as a guideline for your deployment.

阶段 1 - 安装和验证 Azure AD ConnectPhase 1 - install and validate Azure AD Connect

建议先安装或升级到 Azure AD Connect 1.5.30.0 或更高版本并验证同步过程,然后开始第二阶段,启用 V2 终结点。It is recommended that you first perform the steps to install or upgrade to Azure AD Connect version 1.5.30.0 or later and validate the sync process before you go to the second phase where you will enable the V2 endpoint. 在 Azure AD Connect 服务器上:On the Azure AD Connect server:

  1. [可选] 执行数据库备份[Optional] Take database backup
  2. 安装或升级到 Azure AD Connect 1.5.30.0 或更高版本。Install or upgrade to Azure AD Connect version 1.5.30.0 or later.
  3. 验证安装Validate the installation

阶段 2 - 启用 V2 终结点Phase 2 - enable the V2 endpoint

下一步是启用 V2 终结点。The next step is to enable the V2 endpoint.

备注

为服务器启用 V2 终结点后,可以看到现有工作负载有一些性能改进。After you have enabled the V2 endpoint for your server you will be able to see some performance improvements for your existing workload. 不过,你仍将无法同步成员数超过 5 万的组。You will not yet be able to sync groups with more that 50K members though.

要切换到 V2 终结点,请执行以下步骤:To switch to the V2 endpoint, use the following steps:

  1. 以管理员身份打开 PowerShell 命令提示符。Open a PowerShell prompt as administrator.
  2. 确认没有同步操作正在运行后,禁用同步计划程序:Disable the sync scheduler after verifying that no synchronization operations are running:

Set-ADSyncScheduler -SyncCycleEnabled $false

  1. 导入新模块:Import the new module:

Import-Module 'C:\Program Files\Azure AD Sync\Extensions\AADConnector.psm1'

  1. 切换到 v2 终结点:Switch to the v2 endpoint:

Set-ADSyncAADConnectorExportApiVersion 2

Set-ADSyncAADConnectorImportApiVersion 2

PowerShell

你现在已为服务器启用了 V2 终结点。You have now enabled the V2 endpoint for your server. 请花一些时间验证启用 V2 终结点后是否存在意外结果,然后再进行下一阶段,提高组大小限制。Take some time to verify that there are no unexpected results after enabling the V2 endpoint before you move to the next phase where you will increase the group size limit.

备注

根据安装 Azure AD Connect 时所获得的安装路径,文件/模块路径可能会使用不同的驱动器号。The file / module paths may use a different drive letter, depending on the installation path provided when installing Azure AD Connect.

阶段 3 - 提高组成员身份限制Phase 3 - increase the group membership limit

确认服务正在运行且未出现意外结果之后,可以继续提高组成员身份限制。After you have verified that the service is running without unexpected results, you can proceed to raising the group membership limit. 建议先将成员身份限制提高到稍高的值It is recommended to first raise the membership limit to a slightly higher value, e g. (例如 7.5 万成员),以查看较大的组同步到 Azure AD 时的情况。75K members, to see the larger groups syncing to Azure AD. 如果对结果满意,可以进一步提高成员限制。Once you are satisfied with the results you can further raise the member limit.

最大限制为每组 25 万个成员。The maximum limit is 250K members per group.

可以按以下步骤提高成员身份限制:The following steps can be used to increase the membership limit:

  1. 打开 Azure AD 同步规则编辑器Open Azure AD Synchronization Rules Editor

  2. 在编辑器中,选择方向“出站”In the editor, choose Outbound for Direction

  3. 单击“出站到 AAD - 组加入”同步规则Click on the Out to AAD - Group Join sync rule

  4. 单击“编辑”按钮此屏幕截图显示了“查看和管理同步规则”,其中已选中“出站到 AAD - 组加入”。Click the Edit button Screenshot that shows the "View and manage your synchronization rules" with "Out to AAD - Group Join" selected.

  5. 单击“确定”按钮,禁用默认规则并创建可编辑的副本。Click the Yes button to disable the default rule and create an editable copy. 此屏幕截图显示了“编辑保留规则确认”窗口,其中已选中“是”按钮。Screenshot that shows the "Edit Reserved Rule Confirmation" window with the "Yes" button selected.

  6. 在“说明”页的弹出窗口中,将优先级设置为 1 到 99 之间的可用值 此屏幕截图显示了“编辑出站同步规则”窗口,其中突出显示了“优先级”。In the pop-up window on the Description page, set the precedence to an available value between 1 and 99 Screenshot that shows the "Edit outbound synchronization rule" window with "Precedence" highlighted.

  7. 在“转换”页面上,更新“成员”转换的“源”值,将 50000 替换为介于 50001 和 250000 之间的值 。On the Transformations page, update the Source value for the member transformation, replacing ‘50000’ with a value between 50001 and 250000. 此替换会增加将同步到 Azure AD 的组的最大成员身份大小。This replacement will increase the maximum membership size of groups that will sync to Azure AD. 建议从 10 万开始,以了解同步大型组将对同步性能产生的影响。We suggest starting with a number of 100k, to understand the impact that syncing large groups will have on your sync performance.

示例Example

IIF((ValueCount("member")> 75000),Error("Maximum Group member count exceeded"),IgnoreThisFlow)

编辑同步规则

  1. 点击“保存”(Save)Click Save
  2. 打开管理员 PowerShell 提示符Open admin PowerShell prompt
  3. 重新启用同步计划程序Re-enable the Sync Scheduler

Set-ADSyncScheduler -SyncCycleEnabled $true

备注

如果未启用 Azure AD Connect Health,请将 Windows 应用程序事件日志设置更改为存档日志,而不是覆盖日志。If Azure AD Connect Health is not enabled, change the windows application event log settings to archive the logs, instead of overwriting them. 这些日志可能有助于后续的故障排除工作。The logs may be used to assist in future troubleshooting efforts.

备注

启用新的终结点之后,AAD 连接器上可能会显示名为“dn-attributes-failure”的其他导出错误。After enabling the new endpoint, you may see additional export errors on the AAD connector with name ‘dn-attributes-failure’. ID 为 6949 的每个错误都有相应的事件日志条目。There will be a corresponding event log entry for each error with id 6949, . 这些错误是信息性的,并不表示存在安装问题,而是表示由于成员对象本身未同步到 Azure AD,因此同步过程无法将某些成员添加到 Azure AD 中的组。The errors are informational and do not indicate a problem with your installation, but rather that the sync process could not add certain members to a group in Azure AD because the member object itself was not synced to Azure AD.

新的 V2 终结点代码处理某些导出错误类型的方式与 V1 代码的处理方式稍有不同。The new V2 endpoint code handles some types of export errors slightly different from how the V1 code did. 使用 V2 终结点时,可能会显示更多的信息性错误消息。You may see more of the informational error messages when you use the V2 endpoint.

备注

升级 Azure AD Connect 时,确保重新运行阶段 2 中的步骤,因为在升级过程中不会保留这些更改。When upgrading Azure AD Connect, ensure that the steps in Phase 2 are rerun, as the changes are not preserved through the upgrade process.

随后会在“出站到 AAD - 组加入”同步规则中提高组成员限制,在此期间,不需要完全同步,因此可以通过在 PowerShell 中运行以下命令来选择取消完全同步。During subsequent increases to the group member limit in the Out to AAD - Group Join sync rule, a full sync is not necessary, so you can elect to suppress the full sync by running the following command in PowerShell.

Set-ADSyncSchedulerConnectorOverride -FullSyncRequired $false -ConnectorName "<AAD Connector Name>"

备注

如果 Microsoft 365 统一组的成员超过 5 万,则这些组将读取到 Azure AD Connect 中,并且如果启用了组写回功能,这些组将写入到本地 AD 中。If you have Microsoft 365 unified groups that have more than 50k members, the groups will be read into Azure AD Connect, and if group writeback is enabled, they will be written to your on-premises AD.

回退Rollback

如果启用了 v2 终结点并且需要回滚,请执行以下步骤:If you have enabled the v2 endpoint and need to rollback, follow these steps:

  1. 在 Azure AD Connect 服务器上:a.On the Azure AD Connect server: a. [可选] 执行数据库备份[Optional] Take database backup
  2. 打开管理员 PowerShell 提示符:Open an admin PowerShell prompt:
  3. 确认没有同步操作正在运行后,禁用同步计划程序Disable the sync scheduler after verifying that no synchronization operations are running

Set-ADSyncScheduler -SyncCycleEnabled $false

  1. 切换到 V1 终结点*Switch to the V1 endpoint *

Import-Module 'C:\Program Files\Azure AD Sync\Extensions\AADConnector.psm1'

Set-ADSyncAADConnectorExportApiVersion 1

Set-ADSyncAADConnectorImportApiVersion 1

  1. 打开 Azure AD 同步规则编辑器Open Azure AD Synchronization Rules Editor
  2. 删除“出站到 AAD - 组加入”同步规则的可编辑副本Delete the editable copy of the Out to AAD - Group Join sync rule
  3. 启用“出站到 AAD - 组加入”同步规则的默认副本Enable the default copy of the Out to AAD - Group Join sync rule
  4. 打开管理员 PowerShell 提示符Open an admin PowerShell prompt
  5. 重新启用同步计划程序Re-enable the Sync Scheduler

Set-ADSyncScheduler -SyncCycleEnabled $true

备注

从 V2 切换回 V1 终结点时,在运行完全同步后,将删除与 5 万名以上的成员同步的组(适用于预配到 Azure AD 的 AD 组和预配到 AD 的 Microsoft 365 统一组)。When switching back from the V2 to V1 endpoints, groups synced with more than 50k members will be deleted after a full sync is run, for both AD groups provisioned to Azure AD and Microsoft 365 unified groups provisioned to AD.

常见问题Frequently asked questions

问: 客户是否可以在生产中使用此功能?  Q: Can a customer use this feature in production?
是,可以在生产环境中使用此功能,如前文所述。Yes, this can be used in production environments, with the caveat as mentioned before.

问: 如果出现问题,客户可以联系谁?  Q: Who can the customer contact when things go wrong?
如果使用此功能时需要支持,则应打开支持案例。If you need support when using this feature you should open a support case.

问: 能否经常更新公共预览版?  Q: Can I expect frequent updates to the public preview?
公开预览期间更改次数有限。There is a limited degree of ongoing changes during a Public Preview. 在生产中部署公共预览版功能时,应评估此风险。 You should assess this risk when deploying Public Preview features in production.

问: 何时改版?  Q: Time to next milestone?
改版之前,可能会取消并重新设计公共预览版功能。Public Preview capabilities may be withdrawn and possibly redesigned before reaching further milestones.

后续步骤Next steps