如何使用 MS Graph API 以编程方式配置云同步

以下文档介绍如何仅使用 MSGraph API 从头开始复制同步配置文件。
复制同步配置文件的结构包括以下步骤。它们分别是：

如何使用 MS Graph API 以编程方式配置云同步

使用这些 Microsoft Graph PowerShell 命令为生产租户启用同步，这是能够为该租户调用管理 Web 服务的先决条件。

基本设置

启用租户标志

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes "Organization.ReadWrite.All"
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

此 cmdlet 为租户启用同步功能。它使用 Get-MgOrganization 来获取组织的 ID。

创建服务主体

接下来，我们需要创建 AD2AAD 应用程序/服务主体

需要使用此应用程序 ID 1a4721b3-e57f-4451-ae87-ef078703ec94。显示名称是在门户中使用的 AD（Active Directory）域的 URL（例如，contoso.com），但它也可能会被命名为其他名称。

POST https://microsoftgraph.chinacloudapi.cn/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-type: application/json
{
    displayName: [your app name here]
}

创建同步作业

上述命令的输出返回已创建的服务主体的 objectId。对于此示例，objectId 为 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb。使用 Microsoft Graph 向该服务主体添加 synchronizationJob。

有关创建同步作业的文档，可在此处找到。

如果未记录 ID，可以通过运行以下 MS Graph 调用来查找服务主体。需要 Directory.Read.All 权限才能进行该调用：

GET https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals

然后在输出中查找应用名称。

运行以下两个命令来创建两个作业：一个用于用户/组预配，另一个用于密码哈希同步。这两次请求相同，但具有不同的模板 ID。

调用以下两个请求：

POST https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
}

POST https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

如果需要创建两个，则要进行两次调用。

示例返回值（用于预配）：

HTTP 201/Created
{
    "@odata.context": "https://microsoftgraph.chinacloudapi.cn/beta/$metadata#servicePrincipals('aaaaaaaa-0000-1111-2222-bbbbbbbbbbbbc')/synchronization/jobs/$entity",
    "id": "AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da",
    "templateId": "ADDCInPassthrough",
    "schedule": {
        "expiration": null,
        "interval": "PT40M",
        "state": "Disabled"
    },
    "status": {
        "countSuccessiveCompleteFailures": 0,
        "escrowsPruned": false,
        "code": "Paused",
        "lastExecution": null,
        "lastSuccessfulExecution": null,
        "lastSuccessfulExecutionWithExports": null,
        "quarantine": null,
        "steadyStateFirstAchievedTime": "0001-01-01T00:00:00Z",
        "steadyStateLastAchievedTime": "0001-01-01T00:00:00Z",
        "troubleshootingUrl": null,
        "progress": [],
        "synchronizedEntryCountByType": []
    }
}

更新目标域

对于此租户，服务主体的对象标识符和应用程序标识符如下所示：

ObjectId: bbbbbbbb-1111-2222-3333-cccccccccccc
AppId: 00001111-aaaa-2222-bbbb-3333cccc4444
DisplayName: testApp

我们需要更新此配置面向的域，因此请更新此域的机密。

请确保使用的域名与为本地域控制器设置的 URL 相同。

PUT - https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

根据要执行的操作，在以下值数组中添加以下键/值对：

启用 PHS 和同步租户标志 { key： “AppKey”， value： “{”appKeyScenario“：”AD2AADPasswordHash“}” }
仅启用同步租户标志（不启用 PHS） { key： “AppKey”， value： “{”appKeyScenario“：”AD2AADProvisioning“}” }

Request body -
{
   "value": [
              {
                "key": "Domain",
                "value": "{\"domain\":\"ad2aadTest.com\"}"
              }
            ]
}

预期响应为... HTTP 204/无内容

此处，突出显示的“域”值是要从中将条目预配到 Microsoft Entra ID 的本地 Active Directory 域的名称。

在配置面板上启用同步密码哈希

本部分介绍如何为特定配置启用同步密码哈希。这与启用租户级功能标记的 AppKey 密钥不同。此过程仅适用于单个域/配置。需要将应用程序密钥设置为 PHS，以便此过程以端到端工作。

获取示例（警告，它很大）：

GET -https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

获取此 CredentialData 属性映射：

{
"defaultValue": null,
"exportMissingReferences": false,
"flowBehavior": "FlowWhenChanged",
"flowType": "Always",
"matchingPriority": 0,
"targetAttributeName": "CredentialData",
"source": {
"expression": "[PasswordHash]",
"name": "PasswordHash",
"type": "Attribute",
"parameters": []
}

在架构中查找具有以下名称的以下对象映射
- 创建 Active Directory 用户
- 配置 Active Directory inetOrgPersons
对象映射位于 schema.synchronizationRules[0].objectMappings 中（目前可以假定只有一个同步规则）
从步骤（2）获取 CredentialData 映射，并将其插入到步骤（3）中的对象映射中

对象映射如下所示：
```
{
"enabled": true,
"flowTypes": "Add,Update,Delete",
"name": "Provision Active Directory users",
"sourceObjectName": "user",
"targetObjectName": "User",
"attributeMappings": [
...
} 
```
将 “创建 AD2AADProvisioning”和 AD2AADPasswordHash 作业 步骤中的映射复制/粘贴到 attributeMappings 数组中。

此数组中的元素顺序并不重要（后端会为你排序）。如果数组中已存在名称，请谨慎添加此属性映射。例如，如果 attributeMappings 中已有一个具有 targetAttributeName CredentialData 的项，则可能遇到冲突错误，或者预先存在的映射和新映射可能合并在一起。通常，这不是所需的结果。后端不会为你去重。

请记得对 Users 和 inetOrgpersons 执行此操作。

保存创建的架构：

PUT -
https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema

在请求正文中添加架构。

Exchange 混合写回功能（公共预览版）

本部分介绍如何以编程方式启用/禁用和使用 Exchange 混合写回。

以编程方式启用 Exchange 混合写回需要两个步骤。

架构验证
创建 Exchange 混合写回作业

架构验证

在启用和使用 Exchange 混合写回之前，云同步需要确定是否已扩展本地 Active Directory 以包含 Exchange 架构。

可以使用 directoryDefinition：discover 启动架构发现。

POST https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/[AD2AADProvisioningJobId]/schema/directories/[ADDirectoryID]/discover

预期响应为... HTTP 200/OK

响应应类似于以下输出：

HTTP/1.1 200 OK
Content-type: application/json
{
  "objects": [
    {
      "name": "user",
      "attributes": [
        {
          "name": "mailNickName",
          "type": "String"
        },
        ...
      ]
    },
    ...
  ]
}

现在检查 mailNickName 属性是否存在。如果是，那么您的架构已经过验证，并包含 Exchange 属性。如果没有，请查看 Exchange 混合写回的先决条件。

创建 Exchange 混合写回作业

验证架构后，即可创建作业。

POST https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

意外删除

本部分介绍如何以编程方式启用/禁用和使用意外删除。

启用和设置阈值

每个作业设置有两个可以使用，它们是：

DeleteThresholdEnabled - 当设置为“true”时，启用任务的防止意外删除功能。默认情况下设置为“true”。
DeleteThresholdValue - 定义启用意外删除防护时每次执行作业中允许的最大删除次数。默认情况下，该值设置为 500。因此，如果该值设置为 500，则每次执行中允许的最大删除次数为 499。

删除阈值设置是其中的一部分 SyncNotificationSettings ，可以通过图形进行修改。

由于需要更新此配置所针对的 SyncNotificationSettings，因此请更新密钥。

PUT - https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

根据要执行的操作，在以下值数组中添加以下键/值对：

Request body -
{
  "value":[
    {
      "key":"SyncNotificationSettings",
      "value": "{\"Enabled\":true,\"Recipients\":\"foobar@xyz.com\",\"DeleteThresholdEnabled\":true,\"DeleteThresholdValue\":50}"
     }
  ]
}

示例中的“已启用”设置用于在隔离作业时启用/禁用通知电子邮件。

目前不支持对机密的 PATCH 请求。因此，需要添加 PUT 请求正文中的所有值，如示例中所示，以保留其他值。

可以使用以下命令检索所有机密的现有值：

GET https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/{id}/synchronization/secrets

允许删除

若要使这些删除操作在作业进入隔离区后继续传播，您需要发起一次将范围仅设置为“ForceDeletes”的重启。

Request:
POST https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

Request Body:
{
  "criteria": {"resetScope": "ForceDeletes"}
}

启动同步作业

您可以使用以下命令再次检索作业：

GET https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

可在此处找到用于检索作业的文档。

若要启动作业，请使用在第一步中创建的服务主体的 objectId 以及从创建作业的请求返回的作业标识符发出此请求。

有关如何启动作业的文档，可在此处找到。

POST  https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

预期响应为... HTTP 204/无内容。

此处记录了用于控制作业的其他命令。

若要重启作业，请使用：

POST  https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/restart
{
  "criteria": {
    "resetScope": "Full"
  }
}

审查状态

通过以下方式检索作业状态：

GET https://microsoftgraph.chinacloudapi.cn/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

在返回对象的“status”部分下查看相关详细信息

后续步骤

Last updated on 2026-03-27

通过