Windows PowerShell 連接器技術參考

本文說明 Windows PowerShell 連接器。 本文適用於下列產品：

• Microsoft Identity Manager 2016 (MIM2016)

針對MIM2016，連接器可從 Microsoft 下載中心下載。

PowerShell 連接器概觀

PowerShell 連接器可讓您整合同步處理服務與可提供 Windows PowerShell 型 API 的外部系統。 此連接器會在呼叫型可延伸連線管理代理程式 2 (ECMA2) 架構和 Windows PowerShell 的功能之間提供橋樑。 如需 ECMA 架構的詳細資訊，請參閱 可延伸的連線 2.2 管理代理程式參考。

必要條件

在您使用連接器之前，請確定同步處理伺服器上有下列項目：

• Microsoft .NET 4.6.2 Framework 或更新版本
• Windows PowerShell 2.0、3.0 或 4.0

同步處理服務伺服器上的執行原則必須設定為允許連接器執行 Windows PowerShell 指令碼。 除非連接器執行的指令碼是經過數位簽署的，否則請執行下列命令來設定執行原則：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

部署此連接器需要一或多個 PowerShell 腳本。 有些 Microsoft 產品可能會提供腳本來搭配此連接器使用，而該產品會提供這些腳本的支持聲明。 如果您要開發自己的腳本來與此連接器搭配使用，則必須熟悉 Extensible Connectivity Management Agent API 來開發和維護這些腳本。 如果您要在生產環境中使用自己的腳本與第三方系統整合，建議您與第三方廠商或部署合作夥伴合作，以取得此整合的說明、指引和支援。

建立新的連接器

若要在同步處理服務中建立 Windows PowerShell 連接器，您必須提供一系列 Windows PowerShell 指令碼來執行同步處理服務所要求的步驟。 根據您所連接的資料來源和所需的功能，您必須實作的指令碼會有所不同。 本節概述可以實作的每個指令碼以及何時需要用到它們。

Windows PowerShell 連接器是設計用來儲存同步處理服務資料庫內的每個指令碼。 雖然您可以執行儲存在檔案系統的指令碼，但將每個指令碼的主體直接插入連接器組態會更為容易。

若要建立 PowerShell 連接器，請在 [同步處理服務] 中選取 [管理代理程式] 和 [建立]。 選取 [PowerShell (Microsoft)] 連接器。

連接性

提供用來連接至遠端系統的組態參數。 這些值會由同步處理服務妥善保存，並在連接器執行時提供給 Windows PowerShell 指令碼。

您可以設定下列連線參數：

連線能力

通用模組
連接器可讓您在組態中儲存共用的 Windows PowerShell 模組。 連接器在執行指令碼時，會將 Windows PowerShell 模組擷取到檔案系統，使其可供每個指令碼匯入。

針對匯入、匯出和密碼同步處理指令碼，會將一般模組擷取到連接器的 MAData 資料夾。 針對結構描述、驗證、階層和資料分割探索指令碼，則會將一般模組擷取到 %TEMP% 資料夾。 在這兩種情況下，所擷取的一般模組指令碼會根據一般模組指令碼名稱設定進行命名。

若要從 MAData 資料夾中載入名稱為 FIMPowerShellConnectorModule.psm1 的模組，請使用下列陳述式： Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")

若要從 %TEMP% 資料夾中載入名稱為 FIMPowerShellConnectorModule.psm1 的模組，請使用下列陳述式： Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")

參數驗證
驗證指令碼是選擇性的 Windows PowerShell 指令碼，可用來確保系統管理員所提供的連接器組態參數有效。 驗證伺服器、連接認證，以及連線參數是驗證指令碼的常見用途。 下列索引標籤和對話方塊若有修改，就會呼叫驗證指令碼：

• 連接性
• 全域參數
• 資料分割組態

驗證指令碼會接收連接器中的下列參數：

驗證指令碼應該將單一 ParameterValidationResult 物件傳回至管線中。

架構探索
結構描述探索指令碼是必要項目。 此指令碼會傳回物件類型、屬性，以及同步處理服務在設定屬性流程規則時使用的屬性條件約束。 結構描述探索指令碼會在連接器建立期間執行，並填入連接器的結構描述。 同步處理服務管理員中的重新整理結構描述動作也會使用該指令碼。

結構描述探索指令碼會接收連接器中的下列參數：

指令碼必須傳回單一結構描述物件到管線中。 結構描述物件是由代表物件類型 (例如：使用者和群組) 的 SchemaType 物件所組成。 SchemaType 物件會保存代表該類型屬性 (例如：名字、姓氏和郵寄地址) 的 SchemaAttribute 物件集合。

其他參數
除了標準組態設定以外，您還可以定義連接器執行個體特定的其他自訂組態設定。 這些參數可以指定於連接器、資料分割或執行步驟層級，並從相關的 Windows PowerShell 指令碼進行存取。 自訂組態設定可以純文字格式儲存在同步處理服務資料庫中，或可以進行加密。 同步處理服務會在必要時自動加密和解密安全的組態設定。

若要指定自訂組態設定，請使用逗號 (,) 分隔每個參數的名稱。

若要從腳本存取自定義組態設定，您必須將名稱後綴為底線 ( _ ) ，以及參數範圍 (Global、Partition 或 RunStep) 。 例如，若要存取全域檔案名稱參數，請使用此程式碼片段： $ConfigurationParameters["FileName_Global"].Value

功能

Management Agent Designer 的 [功能] 索引標籤會定義連接器的行為和功能。 建立連接器後，就無法修改在此索引標籤上所做的選擇。 此表格列出功能設定。

全域參數

[管理代理程式設計工具] 中的 [全域參數] 索引標籤可讓您設定連接器所執行的 Windows PowerShell 指令碼。 您也可以針對 [連線能力] 索引標籤上定義的自訂組態設定設定全域值。

資料分割探索
資料分割是一個共用結構描述內的個別命名空間。 例如在 Active Directory 中，每個網域就是一個樹系內的資料分割。 資料分割是匯入和匯出作業的邏輯群組。 匯入和匯出將資料分割做為內容，而且所有作業會在此內容中發生。 資料分割應該代表 LDAP 中的階層。 匯入作業會使用資料分割的辨別名稱，以確認所有傳回的物件都在資料分割的範圍內。 在從 Metaverse 佈建到連接器空間的期間，也會使用資料分割辨別名稱來判斷物件應該在匯出期間相關聯的資料分割。

資料分割探索指令碼會接收連接器中的下列參數：

指令碼必須傳回單一Partition物件或資料分割物件的 List[T] 到管線中。

階層探索
只有在辨別名稱樣式功能是 LDAP 時，才會使用階層探索指令碼。 此指令碼可用來讓您瀏覽並選取一組被視為在匯入和匯出作業範圍之內或之外的容器。 此指令碼只應提供所提供給指令碼之根節點直接子系的節點清單。

階層探索指令碼會接收連接器中的下列參數：

指令碼必須傳回單一 HierarchyNode 子物件或 HierarchyNode 子物件 List[T] 至管線中。

匯入

支援匯入作業的連接器必須實作三個指令碼。

開始匯入
開始匯入指令碼會在匯入執行步驟開始時執行。 在此步驟中，您可以建立對來源系統的連線，並進行預備步驟，再從連接的系統匯入資料。

開始匯入指令碼會接收連接器中的下列參數：

指令碼必須傳回單一 OpenImportConnectionResults 物件到管線中，例如：Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)

匯入資料
連接器會呼叫匯入資料指令碼，直到指令碼指出已沒有資料要匯入為止。 Windows PowerShell 連接器的頁面大小為 9,999 個物件。 如果您的指令碼在匯入時傳回超過 9,999 個物件，您必須支援分頁功能。 連接器會公開自訂資料屬性供您用來儲存浮水印，以便在每次呼叫匯入資料指令碼時，指令碼會繼續從中斷處開始匯入物件。

匯入資料指令碼會接收連接器中的下列參數：

匯入資料指令碼必須將 List[CSEntryChange] 物件寫入到管線中。 這個集合是由代表每個所匯入物件的 CSEntryChange 屬性所組成。 在執行完整匯入時，這個集合應該有一組完整的 CSEntryChange 物件，而這些物件擁有每個物件的所有屬性。 在差異匯入期間，CSEntryChange 物件應該包含要匯入之每個物件的屬性層級差異，或已變更之物件的完整表示 (取代模式)。

結束匯入
在匯入執行結束時，便會執行結束匯入指令碼。 此指令碼應該會執行任何必要的清除工作 (例如中斷系統連線和回應失敗)。

結束匯入指令碼會接收連接器中的下列參數：

指令碼必須傳回單一 CloseImportConnectionResults 物件到管線中，例如：Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

匯出

與連接器的匯入架構相同，支援匯出的連接器必須實作三個指令碼。

開始匯出
開始匯出指令碼會在匯出執行步驟開始時執行。 在此步驟中，您可以建立對來源系統的連接，並進行預備步驟，再將資料匯出到連接的系統。

開始匯出指令碼會接收連接器中的下列參數：

指令碼不應傳回任何輸出到管線。

匯出資料
同步處理服務一直呼叫匯出資料指令碼，直到處理完所有擱置中的匯出為止。 如果連接器空間有比連接器頁面大小還多的擱置中匯出，則可能會多次呼叫匯出資料指令碼，並可能針對相同的物件呼叫許多次。

匯出資料指令碼會接收連接器中的下列參數：

匯出資料指令碼必須傳回 PutExportEntriesResults 物件到管線中。 此物件不需要包含每個匯出連接器的結果資訊，除非發生錨點屬性錯誤或變更。 例如，將 PutExportEntriesResults 物件傳回至管線： Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

結束匯出
在匯出執行結束時，便會執行結束匯出指令碼。 此指令碼應該會執行任何必要的清除工作 (例如中斷系統連線和回應失敗)。

結束匯出指令碼會接收連接器中的下列參數：

指令碼不應傳回任何輸出到管線。

密碼同步處理

Windows PowerShell 連接器可以做為密碼變更/重設的目標。

密碼指令碼會接收連接器中的下列參數：

密碼指令碼預期不會傳回任何結果到 Windows PowerShell 管線。 如果密碼指令碼中發生錯誤，指令碼應該會擲回下列其中一個例外狀況，以告知同步處理服務此問題：

• PasswordPolicyViolationException – 如果密碼不符合所連接系統中的密碼原則便會擲回。
• PasswordIllFormedException – 所連接系統不接受密碼時便會擲回。
• PasswordExtension – 密碼指令碼中發生其他所有錯誤時便會擲回。

範例連接器

如需可用範例連接器的完整概觀，請參閱 Windows PowerShell 連接器範例連接器集合。

其他注意事項

模擬的其他組態

對模擬的使用者授與同步處理服務伺服器上的下列權限：

下列登錄機碼的讀取權限：

• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Environment

若要判斷同步處理服務之服務帳戶的安全性識別碼 (SID)，請執行下列 PowerShell 命令：

$account = New-Object System.Security.Principal.NTAccount "<domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value

下列檔案系統資料夾的讀取權限：

• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}

用 Windows PowerShell 連接器的名稱替換 {ConnectorName} 預留位置。

疑難排解

• 如需如何啟用記錄來疑難排解連接器的資訊，請參閱 如何啟用連接器的 ETW 追蹤。