如何使用 MS 圖形 API 以程式設計方式設定雲端同步

下列文件說明如何只使用 MS Graph API 從頭開始複寫同步處理設定檔。
複寫同步處理設定檔的結構包含下列步驟。 畫面如下：

• 如何使用 MS 圖形 API 以程式設計方式設定雲端同步
  • 基本設定
    • 啟用租用戶旗標
  • 建立服務主體
  • 建立同步作業
  • 更新目標網域
  • 在設定刀鋒視窗上啟用同步密碼雜湊
  • Exchange 混合回寫
  • 意外刪除
    • 啟用和設定閾值
    • 允許刪除
  • 啟動同步作業
  • 檢閱狀態
  • 後續步驟

使用這些 Microsoft Graph PowerShell 命令來啟用生產租用戶的同步處理功能。您必須這麼做，才能為該租用戶呼叫管理 Web 服務。

基本設定

啟用租用戶旗標

Connect-MgGraph -Scopes "DeviceManagementConfiguration.ReadWrite.All" ('-Environment <AzureEnvironment>')
$organizationId = (Get-MgOrganization).Id
$params = @{
	onPremisesSyncEnabled = $true
}
Update-MgBetaOrganization -OrganizationId $organizationId -BodyParameter $params

該 Cmdlet 會啟用租用戶的同步處理。 該命令會使用 Get-MgOrganization 來取得組織的識別碼。

建立服務主體

接下來，我們需要建立 AD2AAD 應用程式/服務主體

您必須使用此應用程式識別碼 1a4721b3-e57f-4451-ae87-ef078703ec94。 如果在入口網站中使用，則 displayName 是 AD 網域 URL (例如 contoso.com)，但可以為其指定其他名稱。

POST https://graph.microsoft.com/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 將同步處理作業新增至該服務主體。

您可以在這裡找到建立同步作業的文件。

如果您未記錄識別碼，請執行下列 MS Graph 呼叫來尋找服務主體。 您需要 Directory.Read.All 權限才能進行該呼叫：

GET https://graph.microsoft.com/beta/servicePrincipals

然後在輸出中尋找您的應用程式名稱。

執行下列兩個命令來建立兩個作業：一個用於使用者/群組佈建，另一個用於密碼雜湊同步。 這是使用不同範本識別碼提出兩次的相同要求。

呼叫下列兩個要求：

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADProvisioning"
} 

POST https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AD2AADPasswordHash"
}

若要建立兩者，則將需要兩個呼叫。

傳回值範例 (用於佈建)：

HTTP 201/Created
{
    "@odata.context": "https://graph.microsoft.com/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://graph.microsoft.com/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/沒有內容

在此，醒目提示的 "Domain" 值是要將項目佈建至 Microsoft Entra ID 的內部部署 Active Directory 網域名稱。

在設定刀鋒視窗上啟用同步密碼雜湊

本節討論如何為特定設定啟用同步密碼雜湊。 這種情況與啟用租用戶層級功能旗標的 AppKey 祕密不同。 此程序僅適用於單一網域/設定。您必須將應用程式金鑰設定為 PHS 金鑰，此程序才能端對端運作。

1. 擷取結構描述 (警告，這會相當大)：

   GET –https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

2. 取得此 CredentialData 屬性對應：

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

3. 在結構描述中尋找具有下列名稱的下列物件對應

   • 佈建 Active Directory 使用者
   • 佈建 Active Directory inetOrgPersons

   物件對應位於 schema.synchronizationRules[0].objectMappings 中 (目前您可以假設只有一個同步處理規則)

4. 從步驟 (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 項目)。您可能會收到衝突錯誤，或者預先存在和新的對應可能會結合在一起 (通常不是想要的結果)。 後端不會為您刪除重複項。

   請記得同時對使用者和 inetOrgpersons 執行這個動作。

5. 儲存您所建立的結構描述：

   PUT –
   https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ [AD2AADProvisioningJobId]/schema
   

在要求本文中新增結構描述。

Exchange 混合回寫 (公開預覽版)

本節說明如何以程式方式啟用/停用和使用 [Exchange 混合回寫]。

以程式設計方式啟用 Exchange 混合回寫需要兩個步驟。

1. 結構描述驗證
2. 建立 Exchange 混合回寫作業

結構描述驗證

在啟用和使用 Exchange 混合回寫之前，雲端同步需要確定內部部署的 Active Directory 是否已擴充以包含 Exchange 結構描述。

您可以使用 directoryDefinition:discover 來起始結構描述探索。

POST https://graph.microsoft.com/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://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs
Content-type: application/json
{
"templateId":"AAD2ADExchangeHybridWriteback"
}

意外刪除

本節討論如何以程式設計方式啟用/停用和使用意外刪除。

啟用和設定閾值

每個作業有兩個設定可供您使用，分別是：

• DeleteThresholdEnabled - 設定為 'true' 時，會啟用作業的意外刪除預防措施。 預設會設定為 'true'。
• DeleteThresholdValue：定義啟用意外刪除預防措施時，每次執行作業所允許的最大刪除數目。 預設會將此值設定為 500。 因此，如果將此值設定為 500，則每次執行所允許的最大刪除數目是 499。

刪除閾值設定是 SyncNotificationSettings 的一部分，而且可透過圖形來修改。

我們將需要更新此設定的目標 SyncNotificationSettings，因此請更新祕密。

PUT – https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/secrets

根據您嘗試執行的動作，在下列值陣列中新增下列金鑰/值組：

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

範例中的 "Enabled" 設定可在作業處於隔離狀態時，用於啟用/停用通知電子郵件。

目前，我們不支援對祕密提出 PATCH 要求，因此您必須在 PUT 要求本文中新增所有值 (如範例所示)，以保留其他值。

您可以利用下列方式來擷取所有祕密的現有值：

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/secrets 

允許刪除

若要在作業進入隔離狀態後允許進行刪除，您必須只使用 "ForceDeletes" 作為範圍來發出 restart。

Request:
POST https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/restart

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

啟動同步作業

您可以透過下列命令重新擷取作業：

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/

您可以在這裡找到擷取作業的文件。

若要啟動作業，請使用第一個步驟中所建立服務主體的 objectId，並且從建立作業的要求傳回的作業識別碼來發出此要求。

您可以在這裡找到如何啟動作業的文件。

POST  https://graph.microsoft.com/beta/servicePrincipals/8895955e-2e6c-4d79-8943-4d72ca36878f/synchronization/jobs/AD2AADProvisioning.fc96887f36da47508c935c28a0c0b6da/start

預期的回應為… HTTP 204/沒有內容。

其他用於控制作業的命令如這裡所述。

若要重新啟動作業，請使用：

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

檢閱狀態

透過下列程式碼來擷取作業狀態：

GET https://graph.microsoft.com/beta/servicePrincipals/[SERVICE_PRINCIPAL_ID]/synchronization/jobs/ 

在傳回物件的 [狀態] 區段下尋找相關的詳細資料

下一步

• 什麼是 Microsoft Entra 雲端同步？
• 轉換
• 同步處理 API