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

發行項
05/30/2024

下列文件說明如何使用 MSGraph API 從頭開始復寫同步處理配置檔。
如何復寫同步處理配置檔的結構包含下列步驟。畫面如下：

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

使用這些 Microsoft Graph PowerShell 命令來啟用生產租使用者的同步處理，這是能夠針對該租使用者呼叫管理員 istration Web Service 的必要條件。

基本設定

啟用租用戶旗標

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 將 synchronizationJob 新增至該服務主體。

如需建立同步處理作業的檔，請參閱這裡。

如果您未記錄識別碼，您可以執行下列 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

我們需要更新此設定的目標網域，因此請更新此網域的秘密。

請確定您使用的功能變數名稱與您為內部部署域控制器設定的網址相同。

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

根據您試著執行的動作，在下列值陣列中新增下列索引鍵/值群組：

同時啟用 PHS 和同步租使用者旗標 { key： “AppKey”， value： “{”appKeyScenario“：”AD2AADPasswordHash“}” }
僅啟用同步處理租使用者旗標（不要開啟 PHS） { 機碼： “AppKey”， value： “{”appKeyScenario“：”AD2AADProvisioning“}” }

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

預期的回應為 ... HTTP 204/無內容

在這裡，醒目提示的「網域」值是要布建至 Microsoft Entra ID 之專案的來源內部部署的 Active Directory 定義域名稱。

在設定刀鋒視窗上啟用同步密碼哈希

本節涵蓋針對特定組態啟用同步處理密碼哈希。這種情況與啟用租用戶層級功能旗標的AppKey秘密不同。此程式僅適用於單一網域/組態。您必須將應用程式金鑰設定為 PHS 金鑰，此程式才能端對端工作。

擷取架構（警告，它相當大）：

GET –https://graph.microsoft.com/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": [
...
} 
```
從 Create AD2AADProvisioning 和 AD2AADPasswordHash 作業 步驟複製/貼上對應至 attributeMappings 陣列。

此陣列中的元素順序並不重要（後端會為您排序）。如果名稱已存在於數位中，請小心新增此屬性對應（例如，如果 attributeMappings 中已經有具有 targetAttributeName CredentialData 的專案）-您可能會發生衝突錯誤，或預先存在的和新的對應可能會合併在一起，通常不是所需的結果。後端不會為您推算。

請記得針對 Users 和 inetOrgpersons 執行此動作。

儲存您所建立的架構：

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

在要求主體中新增架構。

Exchange 混合式回寫（公開預覽）

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

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

架構驗證
建立 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 一部分，可透過圖形修改。

我們需要更新 SyncNotification 設定此設定的目標是，因此請更新秘密。

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}"
     }
  ]
}

此範例中的 [已啟用] 設定是用於在隔離作業時啟用/停用通知電子郵件。

目前，我們不支持密碼的 PATCH 要求，因此您必須在 PUT 要求主體中新增所有值，才能保留其他值。

您可以使用下列方式擷取所有秘密的現有值：

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

允許刪除

若要允許這些刪除在作業進入隔離區之後流經，您必須發出重新啟動，且只有「ForceDeletes」作為範圍。

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/

查看傳回物件的 [狀態] 區段，以取得相關詳細數據

共用方式為

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

基本設定

啟用租用戶旗標

建立服務主體

建立同步作業

更新目標網域

在設定刀鋒視窗上啟用同步密碼哈希

Exchange 混合式回寫（公開預覽）

架構驗證

建立 Exchange 混合式回寫作業

意外刪除

啟用和設定臨界值

允許刪除

啟動同步處理作業

檢閱狀態

下一步

意見反應

意見反應

其他資源

共用方式為

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

基本設定

啟用租用戶旗標

建立服務主體

建立同步作業

更新目標網域

在設定刀鋒視窗上啟用同步密碼哈希

Exchange 混合式回寫 （公開預覽）

架構驗證

建立 Exchange 混合式回寫作業

意外刪除

啟用和設定臨界值

允許刪除

啟動同步處理作業

檢閱狀態

下一步

意見反應

意見反應

其他資源

Exchange 混合式回寫（公開預覽）