共用方式為

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 產品可能會提供指令碼來搭配此連接器使用，而該產品會提供這些指令碼的支援陳述式。 如果您要開發自己的腳本以搭配此連接器使用，您必須熟悉 可延伸連線管理代理程式 API 來開發和維護這些腳本。 如果您在生產環境中使用自己的腳本與第三方系統整合，建議您與第三方廠商或部署夥伴合作，以取得此整合的說明、指引和支援。

建立新的連接器

若要在同步處理服務中建立 Windows PowerShell 連接器，您必須提供一系列 Windows PowerShell 腳本，以執行同步處理服務所要求的步驟。 視您所連線的數據源和所需的功能而定，您必須實作的腳本會有所不同。 本節概述每一個可實作的腳本，以及何時需要這些腳本。

Windows PowerShell 連接器的設計目的是將每個腳本儲存在 Synchronization Service 資料庫內。 雖然可以執行儲存在文件系統上的腳本，但更容易將每個腳本的主體直接插入連接器的組態中。

若要建立 PowerShell 連接器，請在 [同步處理服務] 中選取 [Management Agent]，然後 [建立]。 選取 PowerShell（Microsoft） Connector。

建立連接器

連通性

提供連線到遠端系統的組態參數。 這些值會由同步處理服務安全地儲存，並在連接器執行時提供給您的 Windows PowerShell 腳本使用。

MIM 同步連接器組態連線設定頁面

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

連線性

參數 預設值 目的
伺服器 <空白> 連接器應該連接到的伺服器名稱。
網域 <空白> 在執行連接器時，用於儲存並使用的憑證所屬網域。
使用者 <空白> 執行連接器時要使用的憑證使用者名稱，需儲存起來以供使用。
密碼 <空白> 當連接器執行時，用來儲存和使用的認證密碼。
模擬連線器帳戶 否 如果為 true，同步處理服務會在所提供的認證內容中執行 Windows PowerShell 指令碼。 只要可能，建議將 $Credentials 參數傳遞給每個腳本，而不是使用模擬。 如需使用此選項所需之其他權限的詳細資訊，請參閱 仿真的其他組態。
模擬用戶時載入用戶設定檔 否 指示 Windows 在模擬期間載入連接器認證的使用者設定檔。 如果仿真的使用者有漫遊配置檔，連接器不會載入漫遊配置檔。 如需使用此參數所需之其他權限的詳細資訊，請參閱 仿真的其他組態。
模擬時的登入類型 沒有 模擬時的登入類型。 如需詳細資訊，請參閱 dwLogonType 文件。
僅限已簽署的指令碼 否 如果為 true，Windows PowerShell 連接器會驗證每個指令碼是否具有有效的數位簽章。 如果為 false，請確定同步處理服務伺服器的 Windows PowerShell 執行原則是 RemoteSigned 或不受限制。

通用模組
連接器可讓您在組態中儲存共用的 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 指令碼，可用來確保系統管理員所提供的連接器組態參數有效。 驗證伺服器、連線認證和連線參數是驗證腳本的常見用法。 在修改下列索引標籤和對話框之後，會啟用驗證腳本：

  • 連通性
  • 全域參數
  • 分割配置

驗證文稿會從連接器接收下列參數：

名稱 數據類型 說明
配置參數頁面 ConfigParameterPage 觸發驗證要求的組態索引標籤或對話框。
配置參數 KeyedCollection [string， ConfigParameter] 連接器的組態參數數據表。
憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。

驗證腳本應該會將單一 ParameterValidationResult 物件傳回至管線。

架構探索
架構探索腳本是必要的。 此文稿會傳回同步處理服務在設定屬性流程規則時所使用的物件類型、屬性和屬性條件約束。 架構探索文本會在連接器建立期間執行，並填入連接器的架構。 同步處理服務管理員中的重新整理架構動作也會使用它。

架構探索文稿會從連接器接收下列參數：

名稱 數據類型 說明
配置參數 KeyedCollection [string， ConfigParameter] 連接器的組態參數數據表。
憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。

腳本必須將單一 架構 對象傳回管線。 Schema 物件是由代表物件類型的 SchemaType 物件所組成（例如：使用者和群組）。 SchemaType 物件會保存一組 SchemaAttribute 對象，這些物件代表型別的屬性（例如：指定的名稱、姓氏和郵政位址）。

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

若要指定自定義組態設定，請以逗號 （、 ） 分隔每個參數的名稱。

若要從腳本存取自定義組態設定，您必須在名稱後加上底線（_）及參數的範圍（Global、Partition 或 RunStep）。 例如，若要存取全域 FileName 參數，請使用下列代碼段：$ConfigurationParameters["FileName_Global"].Value

能力

管理代理程式設計工具的功能索引標籤會定義連接器的行為和功能。 建立連接器後，無法修改此標籤上的選擇。 下表列出功能設定。

MIM 同步連接器組態功能索引標籤

能力 說明
辨別名稱樣式 指出連接器是否支援辨別名稱，如果支援，其樣式為何。
匯出類型 決定提供給匯出腳本的物件類型。
  • AttributeReplace – 在屬性變更時，包含多重值屬性的完整值集。
  • AttributeUpdate – 只有在屬性變更時，才會包含多重值屬性的差異。
  • MultivaluedReferenceAttributeUpdate - 包含非參考多重值屬性的完整值集，而且只包含多重值參考屬性的差異。
  • ObjectReplace – 在任何屬性變更時包含物件的所有屬性
    		•
    數據正規化 指示同步處理服務先將錨點屬性正規化再提供給指令碼。
    物件確認 在同步處理服務中設定暫止匯入行為。
  • 一般 – 預設行為，預期所有導出的變更都會透過匯入確認
  • NoDeleteConfirmation – 刪除物件時，不會產生擱置的匯入。
  • NoAddAndDeleteConfirmation – 建立或刪除物件時，不會產生任何擱置的匯入。
    		•
    使用 DN 做為錨點 如果 [辨別名稱樣式] 設定為 LDAP，則連接器空間的錨點屬性也是辨別名稱。
    數個連接器並行作業 核取時，可以同時執行多個 Windows PowerShell 連接器。
    分區 若勾選，連接器可支援多個分區和分區探索。
    等級制度 核取時，連接器可支援 LDAP 樣式的階層結構。
    啟用匯入 核取時，連接器會透過匯入指令碼匯入資料。
    啟用差異匯入 核取時，連接器可以要求匯入指令碼的差異。
    啟用匯出 核取時，連接器會透過匯出指令碼匯出資料。
    啟用完整匯出 核取時，導出腳本支援導出整個連接器空間。 若要使用此選項，還必須勾選 [啟用匯出]。
    第一次匯出過程中沒有參考值 核取時，會在第二個匯出階段匯出參考屬性。
    啟用物件重新命名 勾選時，您可以修改辨識名稱。
    刪除-新增以取代 勾選該選項時，刪除新增操作會被匯出為單一替換操作。
    啟用密碼作業 勾選時，支援密碼同步腳本。
    在第一個階段啟用匯出密碼 核取時，會在建立 物件時匯出布建期間設定的密碼。

    全域參數

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

    分區發現
    分割區是一個共享架構內的個別命名空間。 例如，在 Active Directory 中，每個網域都是一個樹系內的分割區。 分割區是匯入和匯出作業的邏輯群組。 匯入和導出具有分割區做為內容，而且所有作業都會在此內容中發生。 分割區應該代表LDAP中的階層。 數據分割的辨別名稱用於匯入，以確認所有傳回的物件都在數據分割的範圍內。 分割區識別名稱也會在從 Metaverse 設定到連接器空間的過程中使用，以判斷在匯出期間物件應該關聯到的分割區。

    資料分割搜尋腳本會從連接器接收以下參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。

    腳本必須將單一 Partition 物件或 Partition 物件的 List[T] 傳回管線。

    階層探索
    只有在辨別名稱樣式功能為LDAP時，才會使用階層探索腳本。 程式碼用於讓您瀏覽並選取一組容器，以決定是否納入或排除在匯入和匯出作業的範圍內。 腳本應該只提供一份節點清單，這些節點是提供給腳本之根節點的直接子系。

    階層探索文本會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    ParentNode（父節點） 階層節點 腳本應該傳回直接子系的階層根節點。

    程式碼應傳回單一子 HierarchyNode 物件或子 HierarchyNode 物件的列表 List[T] 給管線。

    進口

    支援匯入作業的連接器必須實作三個腳本。

    開始匯入
    開始匯入腳本會在匯入執行步驟的開頭執行。 在此步驟中，您可以建立與來源系統的連線，並在從聯機的系統匯入數據之前執行準備步驟。

    開始匯入文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    OpenImportConnectionRunStep OpenImportConnectionRunStep 通知文本匯入執行類型（差異或完整）、數據分割、階層、浮浮水印，以及預期的頁面大小。
    類型 架構 匯入之連接器空間的架構。

    腳本必須將單一 OpenImportConnectionResults 對象傳回管線，例如：Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)

    匯入資料
    連接器會呼叫匯入數據腳本，直到腳本指出沒有其他要匯入的數據為止。 Windows PowerShell 連接器的頁面大小為 9,999 個物件。 如果您的腳本傳回超過 9,999 個對象進行匯入，您必須支援分頁。 連接器會公開自定義數據屬性，您可以用來儲存浮水印，以便在每次呼叫匯入數據腳本時，腳本會繼續匯入離開的物件。

    匯入資料文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    GetImportEntriesRunStep ImportRunStep 儲存可在分頁匯入和差異匯入期間使用的浮水印（自定義資料，CustomData）。
    開啟匯入連接執行步驟 OpenImportConnectionRunStep 通知腳本匯入執行的類型（差異或完整）、分割區、階層、水印以及預期的頁面大小。
    類型 架構 匯入之連接器空間的架構。

    匯入數據腳本必須將 List[CSEntryChange] 物件寫入管線。 此集合是由代表所匯入之每個物件的 CSEntryChange 屬性所組成。 在完整匯入執行期間，此集合應該有一組完整的 CSEntryChange 對象，這些物件具有每個物件的所有屬性。 在 Delta 匯入過程中，CSEntryChange 物件應包含每個要匯入物件的屬性層級變化，或是顯示已變更物件的完整表示（Replace 模式）。

    結束匯入
    在匯入執行結束時，會執行結束匯入腳本。 此腳本應該執行任何必要的清除工作（例如，關閉系統連線並回應失敗）。

    端匯入文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[字串, ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    開啟導入連線運行步驟 OpenImportConnectionRunStep 通知腳本有關匯入類型（差異或完整）、分區、階層、水印以及預期的頁面大小。
    關閉匯入連接運行步驟 CloseImportConnectionRunStep 通知腳本匯入結束的原因。

    腳本必須將單一 CloseImportConnectionResults 對象傳回管線，例如：Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

    出口

    與連接器的匯入架構相同，支持導出的連接器必須實作三個腳本。

    開始匯出
    開始匯出腳本會在匯出執行步驟的開頭執行。 在此步驟中，您可以建立與來源系統的連線，並在將數據匯出至連線的系統之前，執行任何準備步驟。

    開始匯出文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    開啟匯出連接運行步驟 OpenExportConnectionRunStep 告知腳本有關導出執行類型（差異或完整）、分區、階層和預期頁面大小的信息。
    類型 架構 匯出之連接器空間的架構。

    腳本不應將任何輸出傳回至管線。

    匯出資料
    同步處理服務會視需要多次呼叫匯出數據腳本，以處理所有擱置的匯出。 如果連接器空間的導出數目超過連接器的頁面大小，則匯出數據腳本可能會多次呼叫，而且可能針對相同物件呼叫多次。

    匯出資料文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string，ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    CSEntries IListCSEntryChange 此階段期間要處理的待匯出的所有連接器空間物件清單。
    開啟匯出連線運行步驟 OpenExportConnectionRunStep 告知腳本關於匯出執行類型（增量或完整）、分割、階層和預期的頁面大小。
    類型 架構 匯出之連接器空間的架構。

    導出數據腳本必須將 putExportEntriesResults PutExportEntriesResults 物件傳回管線。 除非發生錨點屬性的錯誤或變更，否則這個物件不需要包含每個匯出連接器的結果資訊。 例如，若要將 PutExportEntriesResults 物件傳回管線：Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

    結束導出
    在匯出過程結束時，將執行結束匯出的腳本。 此腳本應該執行任何必要的清除工作（例如，關閉系統連線並回應失敗）。

    結束匯出文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    設定參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    OpenExportConnectionRunStep OpenExportConnectionRunStep 通知指令碼關於導出運行類型（增量或完整）、分區、階層和預期頁面大小的信息。
    關閉匯出連接運行步驟 CloseExportConnectionRunStep 通知文本導出結束的原因。

    腳本不應將任何輸出傳回至管線。

    密碼同步處理

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

    密碼文稿會從連接器接收下列參數：

    名稱 數據類型 說明
    配置參數 KeyedCollection[string， ConfigParameter] 連接器的組態參數數據表。
    憑據 PSCredential 包含系統管理員在 [連線能力] 索引標籤上輸入的任何認證。
    分區 分割區 CSEntry 位於的目錄分割區。
    CSEntry CSEntry 連接器空間條目針對密碼已變更或重設的目標物件。
    操作類型 字符串 指出作業是否為重設 （SetPassword） 或變更 （ChangePassword）。
    密碼選項 密碼選項 指定預期密碼重設行為的旗標。 只有在 OperationType SetPassword時，才能使用此參數。
    舊密碼 字符串 填入對象的舊密碼以進行密碼變更。 只有在 OperationType ChangePassword時，才能使用此參數。
    新密碼 字符串 填入文本應該設定的對象新密碼。

    密碼腳本不應該傳回任何結果給 Windows PowerShell 管線。 如果密碼文本發生錯誤，腳本應該擲回下列其中一個例外狀況，以通知同步處理服務發生問題：

    範例連接器

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

    其他注意事項

    模擬的額外設定

    授與被模擬的使用者在同步處理服務伺服器上的以下許可權：

    讀取下列註冊表機碼的讀取權限：

    • HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
    • HKEY_USERS\[SynchronizationServiceServiceAccountSID]\環境

    若要判斷同步處理服務服務帳戶的安全性識別碼 （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}

    以 {ConnectorName} 占位符取代 Windows PowerShell 連接器的名稱。

    故障排除