使用 PowerShell 指令碼的 API 驅動輸入佈建

本教學課程說明如何使用PowerShell腳本來實作Microsoft Entra ID API導向的輸入布建。 使用本教學課程中的步驟，您可以將包含 HR 數據的 CSV 檔案轉換成大量要求承載，並將其傳送至 Microsoft Entra 布建 /bulkUpload API 端點。 本文也提供如何搭配任何記錄系統使用相同整合模式的指導內容。

整合案例

商務需求

記錄系統會定期產生包含背景工作角色資料的 CSV 檔案匯出。 您想要實作整合，以從 CSV 檔案讀取資料，並在目標目錄中自動佈建使用者帳戶 (適用於混合式使用者的內部部署 Active Directory，以及純雲端使用者的 Microsoft Entra ID)。

實作需求

從實作的觀點來看：

• 您想要使用無人參與的 PowerShell 指令碼，從 CSV 檔案匯出讀取資料，並將其傳送至輸入佈建 API 端點。
• 在 PowerShell 指令碼中，您不想實作在記錄系統和目標目錄之間比較身分識別資料的複雜邏輯。
• 您想要使用 Microsoft Entra 佈建服務來套用 IT 受控佈建規則，以在目標目錄 (內部部署 Active Directory 或 Microsoft Entra ID) 中自動建立/更新/啟用/停用帳戶。

整合案例變化

雖然本教學課程使用 CSV 檔案作為記錄系統，但您可以自訂範例 PowerShell 指令碼，以從任何記錄系統讀取資料。 以下是企業整合案例變化的清單，其中 API 驅動的輸入佈建可以使用 PowerShell 指令碼來實作。

讀取源數據之後，套用前置處理規則，並將記錄系統的輸出轉換成批量請求，以傳送至 Microsoft Entra 配置 bulkUpload API 端點。

如何使用本教學課程

Microsoft Entra 輸入布建 GitHub 存放庫 中發佈的 PowerShell 範例腳本會自動執行數項工作。 其邏輯可用來處理大型 CSV 檔案，並將大量要求區塊化，以在每個要求中傳送 50 筆記錄。 以下說明如何測試它，並根據您的整合需求進行自訂。

下載 PowerShell 指令碼

1. 存取 GitHub 存放庫 entra-id-inbound-provisioning。
2. 使用 [ 程序代碼>複製 ] 或 [ 程式代碼>下載 ZIP ] 選項，將此存放庫的內容複製到本機資料夾。
3. 流覽至 PowerShell/CSV2SCIM資料夾。 它會建立下列目錄結構：
   • src
     • CSV2SCIM.ps1 (主要指令碼)
     • ScimSchemaRepresentations (資料夾包含驗證 AttributeMapping.psd1 檔案的標準 SCIM 結構描述定義)
       • EnterpriseUser.json、Group.json、Schema.json、User.json
   • 範例
     • AttributeMapping.psd1 (CSV 檔案中資料行與標準 SCIM 屬性的範例對應)
     • csv-with-2-records.csv (包含 2 筆記錄的 CSV 檔案範例)
     • csv-with-1000-records.csv (包含 1000 筆記錄的 CSV 檔案範例)
     • Test-ScriptCommands.ps1 （範例使用方式命令）
     • UseClientCertificate.ps1 (用來產生自我簽署憑證的指令碼，並將其上傳為服務主體認證以用於 OAuth 流程)
     • Sample1 (資料夾包含 CSV 檔案資料行如何對應至 SCIM 標準屬性的更多範例。如果您為員工、承包商、實習生取得不同的 CSV 檔案，您可以為每個實體建立個別的 AttributeMapping.psd1 檔案。)
4. 下載並安裝最新版的 PowerShell。
5. 執行命令以啟用執行遠端簽署指令碼：

   set-executionpolicy remotesigned
   

6. 安裝下列必要條件模組：

   Install-Module -Name Microsoft.Graph.Applications,Microsoft.Graph.Reports
   

使用標準結構描述產生大量要求承載

本節說明如何從 CSV 檔案產生具有標準 SCIM 核心使用者和企業使用者屬性的大量要求承載。 為了說明程序，讓我們使用 CSV 檔案 Samples/csv-with-2-records.csv。

1. 在 Notepad++ 或 Excel 中開啟 CSV 檔案 Samples/csv-with-2-records.csv，以檢查檔案裡的資料行。

2. 在 Notepad++ 或 Visual Studio Code 之類的原始程式碼編輯器中，開啟 PowerShell 資料檔案 Samples/AttributeMapping.psd1 ，讓 CSV 檔案資料行對應至 SCIM 標準結構描述屬性。 現成隨附的檔案已預先設定 CSV 檔案資料行對應至對應的 SCIM 結構描述屬性。

       @{
       externalId   = 'WorkerID'
       name         = @{
           familyName = 'LastName'
           givenName  = 'FirstName'
       }
       active       = { $_.'WorkerStatus' -eq 'Active' }
       userName     = 'UserID'
       displayName  = 'FullName'
       nickName     = 'UserID'
       userType     = 'WorkerType'
       title        = 'JobTitle'
       addresses    = @(
           @{
               type          = { 'work' }
               streetAddress = 'StreetAddress'
               locality      = 'City'
               postalCode    = 'ZipCode'
               country       = 'CountryCode'
           }
       )
       phoneNumbers = @(
           @{
               type  = { 'work' }
               value = 'OfficePhone'
           }
       )
       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
           employeeNumber = 'WorkerID'
           costCenter     = 'CostCenter'
           organization   = 'Company'
           division       = 'Division'
           department     = 'Department'
           manager        = @{
               value = 'ManagerID'
           }
       }
   }
   

3. 開啟 PowerShell 並變更至 目錄CSV2SCIM\src。

4. 執行下列命令來初始化 AttributeMapping 變數。

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

5. 執行下列命令來驗證 AttributeMapping 檔案是否具有有效的 SCIM 結構描述屬性。 如果驗證成功，此命令會傳回 True 。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

6. AttributeMapping假設檔案具有名為 userId 的無效 SCIM 屬性，然後ValidateAttributeMapping模式會顯示下列錯誤。

   

7. 驗證 AttributeMapping 檔案是否有效之後，請執行下列命令，以在有包含 CSV 檔案中兩筆記錄的檔案 BulkRequestPayload.json 中產生大量要求。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping > BulkRequestPayload.json
   

8. 您可以開啟檔案 BulkRequestPayload.json 的內容，以確認是否根據檔案 AttributeMapping.psd1 中所定義的對應設定 SCIM 屬性。

9. 您可以使用 Graph Explorer 或 cURL，將上述產生的 as-is 檔案上傳至與您的布建應用程式相關的 /bulkUpload API 端點。 參考：

   • Graph Explorer 快速入門
   • cURL 快速入門

10. 若要使用相同的 PowerShell 指令碼直接將產生的承載上傳至 API 端點，請參閱下一節。

設定服務主體驗證的客戶端憑證

1. 執行下列 PowerShell 指令碼來產生新的自我簽署憑證。 如果您已購買由知名憑證授權機構單位簽署的憑證，則可以略過此步驟。

   $ClientCertificate = New-SelfSignedCertificate -Subject 'CN=CSV2SCIM' -KeyExportPolicy 'NonExportable' -CertStoreLocation Cert:\CurrentUser\My
   $ThumbPrint = $ClientCertificate.ThumbPrint
   

   產生的憑證會儲存 目前的使用者\個人\憑證。 您可以使用 [控制面板>管理使用者憑證 ] 選項來檢視它。
2. 若要將此憑證與有效的服務主體產生關聯，請以應用程式管理員身分登入您的 Microsoft Entra 系統管理中心。
3. 開啟您在 [應用程式註冊] 下設定的服務主體。
4. 從 概觀 面板複製 對象標識符。 使用值來取代字串 <AppObjectId>。 複製 應用程式 （用戶端） 識別碼。我們稍後會使用它，並將它參考為 <AppClientId>。
5. 執行下列命令，將您的憑證上傳至已註冊的服務主體。

   Connect-MgGraph -Scopes "Application.ReadWrite.All"
   Update-MgApplication -ApplicationId '<AppObjectId>' -KeyCredentials @{
      Type = "AsymmetricX509Cert"
      Usage = "Verify"
      Key = $ClientCertificate.RawData
   }
   

   您應該會在已註冊應用程式的 [ 憑證與秘密 ] 面板中看到憑證。
6. 將下列兩個 應用程式 許可權範圍新增至服務主體應用程式： Application.Read.All 和 Synchronization.Read.All。 PowerShell 指令碼需要這些權限範圍，才能透過 ServicePrincipalId 查閱佈建應用程式，並擷取佈建 JobId。

使用客戶端憑證驗證上傳大量要求承載

本節說明如何使用受信任的用戶端憑證，將產生的大量要求承載傳送至您的輸入佈建 API 端點。

1. 開啟您 設定的 API 驅動佈建應用程式。 複製與您的佈建應用程式相關聯的ServicePrincipalId，其位於佈建應用程式>屬性>中的物件識別碼。

   

2. 為 ServicePrincipalId、ClientId 和 TenantId 提供正確的值，以執行下列命令。

   $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
   $ThumbPrint = $ClientCertificate.ThumbPrint
   
   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -TenantId "contoso.onmicrosoft.com" -ServicePrincipalId "<ProvisioningAppObjectId>" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint)
   

3. 請造訪布建應用程式的 [ 布建記錄 ] 面板，以確認上述要求的處理。

產生有自訂 SCIM 結構描述的大量要求

本節說明如何使用由 CSV 檔案中的欄位組成的自訂 SCIM 結構描述命名空間產生大量請求。

1. 在 Notepad++ 或 Visual Studio Code 之類的原始程式碼編輯器中，開啟 PowerShell 資料檔案 Samples/AttributeMapping.psd1 ，讓 CSV 檔案資料行對應至 SCIM 標準結構描述屬性。 現成隨附的檔案已預先設定 CSV 檔案資料行對應至對應的 SCIM 結構描述屬性。

2. 開啟 PowerShell 並變更至 目錄CSV2SCIM\src。

3. 執行下列命令來初始化 AttributeMapping 變數。

   $AttributeMapping = Import-PowerShellDataFile '..\Samples\AttributeMapping.psd1'
   

4. 執行下列命令來驗證 AttributeMapping 檔案是否具有有效的 SCIM 結構描述屬性。 如果驗證成功，此命令會傳回 True 。

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ValidateAttributeMapping
   

5. 除了 SCIM 核心使用者和企業使用者屬性之外，若要在自訂 SCIM 結構描述命名空間 urn:ietf:params:scim:schemas:extension:contoso:1.0:User 底下取得所有 CSV 欄位的一般清單，請執行下列命令。

    .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -AttributeMapping $AttributeMapping -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"  > BulkRequestPayloadWithCustomNamespace.json
   

   CSV 欄位會顯示在自訂 SCIM 結構描述命名空間底下。

擴充佈建工作描述

HR 小組傳送的資料檔案通常包含更多屬性，這些屬性在標準 SCIM 結構描述中沒有直接代表項目。 若要聲明這類屬性，建議您建立 SCIM 延伸結構描述，並在這個命名空間下新增屬性。

CSV2SCIM 指令碼提供稱為 UpdateSchema 的執行模式，它會讀取 CSV 檔案中的所有資料行、在延伸結構描述命名空間下新增它們，以及更新佈建應用程式結構描述。

為了說明此程式，我們將使用Samples/csv-with-2-records.csv資料夾中存在的 CSV 檔案。

1. 在 Notepad、Excel 或 TextPad 中開啟 CSV 檔案 Samples/csv-with-2-records.csv，以檢查檔案裡的資料行。

   

2. 執行以下命令：

   .\CSV2SCIM.ps1 -Path '..\Samples\csv-with-2-records.csv' -UpdateSchema -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -ScimSchemaNamespace "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"
   

3. 您可以開啟 [屬性對應] 頁面並存取 [進階選項] 底下的 [API 編輯屬性清單] 選項，以確認布建應用程式架構的更新。

4. [屬性清單] 會顯示新命名空間底下的屬性。

取得最新同步週期的佈建記錄

傳送大量要求之後，您可以查詢 Microsoft Entra ID 所處理的最新同步處理週期記錄。 您可以使用 PowerShell 指令碼擷取同步統計資料和處理詳細資料，並加以儲存以供分析。

1. 若要檢視主控台上的記錄詳細資料和同步統計資料，請執行下列命令：

   .\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs -NumberOfCycles 1
   

   

   注意

   NumberOfCycles 預設為 1。 指定一個數字，以擷取更多同步週期。

2. 若要檢視主控台上的同步統計資料，並將記錄詳細資料儲存至變數，請執行下列命令：

   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId <servicePrincipalId> -TenantId "contoso.onmicrosoft.com" -GetPreviousCycleLogs
   

   若要使用用戶端憑證驗證執行命令，請為 ServicePrincipalId、ClientId 和 TenantId提供正確的值來執行命令：

   $ClientCertificate = Get-ChildItem -Path cert:\CurrentUser\my\ | Where-Object {$_.Subject -eq "CN=CSV2SCIM"}  
   $ThumbPrint = $ClientCertificate.ThumbPrint
   
   $logs=.\CSV2SCIM.ps1 -ServicePrincipalId "<ProvisioningAppObjectId>" -TenantId "contoso.onmicrosoft.com" -ClientId "<AppClientId>" -ClientCertificate (Get-ChildItem Cert:\CurrentUser\My\$ThumbPrint) -GetPreviousCycleLogs -NumberOfCycles 1
   

   • 若要查看特定記錄的詳細資料，我們可以重複執行集合迴圈，或選取它的特定索引，例如： $logs[0]

     

   • 我們也可以使用 where-object 陳述式，使用 sourceID 或 DisplayName 搜尋特定記錄。 在 ProvisioningLogs 屬性中，我們可以找到針對該特定記錄完成之作業的所有詳細數據。

     $user = $logs | where sourceId -eq '1222'
     $user.ProvisioningLogs | fl
     

     

   • 我們可以在 ModifiedProperties 屬性上看到特定的使用者受影響的屬性。 $user.ProvisioningLogs.ModifiedProperties

     

附錄

CSV2SCIM PowerShell 使用方式詳細資訊

以下是 CSV2SCIM PowerShell 指令碼所接受的命令行參數清單。

PS > CSV2SCIM.ps1 -Path <path-to-csv-file> 
[-ScimSchemaNamespace <customSCIMSchemaNamespace>] 
[-AttributeMapping $AttributeMapping] 
[-ServicePrincipalId <spn-guid>] 
[-ValidateAttributeMapping]
[-UpdateSchema]
[-ClientId <client-id>]
[-ClientCertificate <certificate-object>]
[-RestartService]

AttributeMapping

此檔案可用來將 CSV 檔案中的資料行對應至標準 SCIM 核心使用者和企業使用者屬性結構描述元素。 檔案也會以大量要求承載的形式產生適當的 CSV 檔案內容代表項目。

在下一個範例中，我們已將 CSV 檔案中的下列資料行對應至其對應的 SCIM 核心使用者和企業使用者屬性。

    @{
    externalId   = 'WorkerID'
    name         = @{
        familyName = 'LastName'
        givenName  = 'FirstName'
    }
    active       = { $_.'WorkerStatus' -eq 'Active' }
    userName     = 'UserID'
    displayName  = 'FullName'
    nickName     = 'UserID'
    userType     = 'WorkerType'
    title        = 'JobTitle'
    addresses    = @(
        @{
            type          = { 'work' }
            streetAddress = 'StreetAddress'
            locality      = 'City'
            postalCode    = 'ZipCode'
            country       = 'CountryCode'
        }
    )
    phoneNumbers = @(
        @{
            type  = { 'work' }
            value = 'OfficePhone'
        }
    )
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" = @{
        employeeNumber = 'WorkerID'
        costCenter     = 'CostCenter'
        organization   = 'Company'
        division       = 'Division'
        department     = 'Department'
        manager        = @{
            value = 'ManagerID'
        }
    }
}

下一步

• 排除入站佈建 API 的問題
• API 驅動輸入布建概念
• API 驅動入站佈建的常見問題