通用 CSV 連接器 - 逐步參考指南（預覽）

本文說明一般 CSV 連接器。 本文適用於下列產品：

• Microsoft Identity Manager 2016 （MIM2016）

對於 MIM 2016，可以從 Microsoft 下載中心下載連接器。

注意

Azure AD 布建 服務現在提供輕量化代理程式解決方案，可將使用者布建至 CSV 檔案，而不需要進行完整的 MIM 同步部署。 建議您評估它是否符合您的需求。 深入瞭解。

準備範例 CSV 檔案

在執行 MIM 同步處理伺服器的伺服器上，建立資料夾 C：\GCSV，並將 附錄 A – 範例 CSV 檔案 中找到的下列 CSV 檔案複製到其中。 請務必將 MIM 同步處理服務帳戶的讀取和寫入許可權授與該資料夾。

將下列 CSV 複製到 C：\GCSV\SCRIPTS 資料夾中：

• 範例使用者 CSV 檔案 （Users.csv）
• 範例群組 CSV 檔案 （Groups.csv）
• 範例成員 CSV 檔案 （Members.csv）

注意

本指南假設 CSV 檔案位於 MIM 同步處理伺服器上的下列路徑：C：\GCSV，並使用指定的檔名加以儲存。 如果您在不同的位置安裝它們或重新命名這些檔案，您必須透過本指南的重設進行適當的變更。

準備範例 PowerShell 腳本

在執行 MIM 同步處理伺服器的伺服器上，建立 C：\GCSV\SCRIPTS 的資料夾，並將 位於附錄 B - 範例 PowerShell 檔案 的範例 PowerShell 腳本複製到其中。 請確定 MIM 同步處理服務帳戶具有適當的 PowerShell ExecutePolicy 許可權，才能執行腳本。

將下列 PowerShell 腳本複製到 C：\GCSV\SCRIPTS 資料夾中：

• 範例預先匯入腳本 （Pre-Import.ps1）
• 匯入後文稿範例 （Post-Import.ps1）
• 匯出前腳本範例 （Pre-Export.ps1）
• 匯出後文稿範例 （Post-Export.ps1）

注意

本指南假設 CSV 檔案位於 MIM 同步處理伺服器上的下列路徑：C：\GCSV\SCRIPTS。 如果您在不同的位置安裝它們，您必須透過本指南的重設進行適當的變更。

重要

MIM 同步處理服務帳戶需要 MIM 同步處理伺服器上的適當 PowerShell ExecutePolicy 許可權，才能執行範例 PowerShell 腳本。

建立新的連接器

下列清單是本指南中所述步驟的高階概觀。 為了執行這些任務，必須使用具有 MIM Syncs Admin 角色的帳戶：

• 從 MIM Sync Service Manager開啟 [建立新的管理代理程式 (MA)] 視窗。
• 選取 一般 CSV 連接器 作為連接器類型。
• 提供要匯入或匯出之 CSV 檔案的檔案路徑和名稱。
• 指定 CSV 檔案的檔案編碼、值分隔符、多重值分隔符和文字限定符。
• 選擇是否要使用第一個數據列中的值作為標頭欄位。
• 選取要從 CSV 檔案匯入或導出的物件類型和屬性。
• 設定 MA 的分區、執行設定檔和對應詳細資訊。
• 如果有的話，請提供 PowerShell 腳本的腳本路徑和參數。
• 執行MA來執行匯入、同步或匯出作業。
• 評估結果。

讓我們開始吧！

若要建立一般 CSV 連接器，請在 [MIM 同步處理服務管理員] 選取 [管理代理程式]，然後 [建立]。 選取 [Microsoft 一般 CSV] 連接器。

[建立連接器] 頁面

為連接器提供名稱（例如：一般 CSV），然後按 [下一步] 按鈕。

連接性

[連線] 頁面包含連接器可以找到使用者、群組和群組成員 CSV 檔案的檔案路徑。

下圖是 Connectivity 頁面的範例：

以下是此頁面設定中應提供的值清單：

設定名稱	設定值	筆記
使用者檔案	C:\GCSV\USERS.CSV	（使用的完整路徑和檔名。）
群組文件	C:\GCSV\GROUPS.CSV	（使用的完整路徑和檔名。）
成員檔案	C:\GCSV\MEMBERS.CSV	（使用的完整路徑和檔名。）

確認設定符合提供的值之後，請按一下 下一步 按鈕。

能力

此頁面描述連接器的功能。 GCSV 連接器功能已修正且無法修改。

下圖是「能力」頁面的範例：

如需這些功能設定的詳細描述，請參閱 一般 CSV 連接器 – 技術參考指南。

檢閱上述設定之後，按一下 下一步 按鈕。

架構 1 （CSV 檔案格式組態）

泛型 CSV （GCSV） 連接器會利用三種分隔符（或分隔符）來分隔和剖析 CSV 字段及其值：值分隔符、多重值分隔符，以及 文字限定符。 如需這些分隔符類型的詳細說明，請參閱 一般 CSV 連接器 – 技術參考指南

此頁面包含這些分隔符的字元值設定，以及用來建立檔案為 CSV 的編碼類型。

下圖是 架構 1 （CSV 檔案格式組態） 頁面的範例：

下一節是個別組態的清單：

• 使用標頭進行架構探索：如果選取此選項，它會指示連接器忽略每個 CSV 檔案的第一筆記錄做為數據記錄，並將它當做標頭記錄使用（也就是具有每個字段的名稱）。如果未選取此選項，連接器會為每個欄位提供一個泛型名稱（例如 Attribute1、Attribute2 等），並使用第一個數據列作為數據記錄。
• 值分隔符：此字元會分隔 CSV 記錄的欄位（也就是值）。 逗號（，）是預設值，但允許任何可顯示的英數字元。
• 多重值分隔符：此分隔符類型可用來分隔多重值字串的個別值（例如 Proxy 位址）或參考屬性（例如次級。默認值為分號（;)，但可以接受任何可列印的英數位元。
• 文字限定符：如果字串值包含將否則解譯為分隔符的字元（例如逗號），則需要限定值，讓 CSV 剖析器可以正確地將字元串解譯為單一字段。 雙引號（"）是預設值，但也允許任何可以列印的英數字元。
• 檔案編碼：此設定表示在 [連線能力] 索引標籤中新增的 CSV 檔案上使用的編碼方式。請確定它符合 CSV 檔案的編碼方式。

注意

如果您不確定 CSV 檔案的編碼類型，您應該嘗試使用預設 Unicode 編碼類型。 Unicode 是支援許多字元和符號的通用標準，因此使用大部分語言或字元集來編碼文字數據是不錯的選擇。

架構 2 （身分識別與參考欄位組態）

錨點值是 CSV 檔案中記錄的唯一標識碼。 它會區分一筆記錄與其他記錄。 GCSV 連接器也會使用此值來建置可唯一識別其連接器空間對象的辨別名稱 （DN）。

在此頁面上，錨點屬性設定會針對 [連線能力] 頁面上所列的每個 CSV 檔案進行設定。

下圖是 架構 2 （身分識別與參考字段組態） 頁面的範例。

下表是應該指派給此頁面上每個設定的個別值：

設定名稱	設定值
用戶記錄ID欄位	員工編號
用戶記錄識別符字段屬性類型	字串
群組記錄ID欄位	群組ID
群組記錄標識符字段屬性類型	字串
父群組標識碼	ParentID
成員標識碼	MemberID
成員物件類型	ObjectType

在確認設定符合提供的值之後，請按下一步 按鈕。

架構 3 （使用者檔案屬性架構組態）

此頁面是用來指派使用者 CSV 檔案架構中每個屬性的數據類型，以及他們是否可以有多個值。

下圖是 架構 3 （使用者檔案屬性架構組態） 頁面的範例。

下表是應該指派給此頁面上每個設定的個別值：

設定名稱	設定值	筆記
DisplayName 屬性類型	字串	限定字串的範例在此欄位中
DisplayName 是多重值	false	--
AccountName 屬性類型	字串	--
AccountName 是多重值	false	--
CountryCode 屬性類型	整數	--
CountryCode 是多重取值	false	--
Manager 屬性類型	參考	包含其指派管理員用戶記錄的錨點屬性值（例如，E001）
管理員是多重值	false	--
ProxyAddresses 屬性類型	字串	--
ProxyAddresses 是多重值	真	包含如何分隔多重值字串的範例
IsActive 屬性類型	布爾值	--
IsActive 是多重值	錯誤	--
ProfilePic 屬性類型	二進位	--
ProfilePic 是多重值	假	--

確認設定符合提供的值之後，請按一下 下一步 按鈕。

架構 4 （群組檔案屬性架構組態）

此頁面可用來指派群組 CSV 檔案架構中每個屬性的數據類型，以及它們是否可以有多個值。

下圖是 架構 4 （群組檔案屬性架構組態） 頁面的範例。

下表是應該指派給此頁面上每個設定的個別值：

設定名稱	設定值	筆記
DisplayName 屬性類型	字串	--
DisplayName 是多重值	錯誤	提供限定字串值的範例。
Description 屬性類型	字串	--
描述是多重值	false	--
擁有者屬性類型	參考	提供參考值的範例。
擁有者有多個值	false	--

確認設定符合提供的值之後，請按一下 下一步 按鈕。

全域參數 （PowerShell 腳本設定）

此頁面允許設定在匯入和/或匯出作業之前和/或之後執行的 PowerShell 腳本。 此輸入參數的值可讓您在身分識別使用者和群組記錄上執行各種不同的前置和後置處理動作。

下圖是 全域參數 頁面的範例。

的螢幕快照

下表是應該指派給此頁面上每個設定的個別值：

設定名稱	設定值	筆記
預先匯入檔案	C:\GCSV\SCRIPTS\PRE-IMPORT.CSV	此腳本會在完整匯入之前執行
匯入後檔案	C:\GCSV\SCRIPTS\POST-IMPORT.CSV	此腳本會在完整匯入之後執行
匯出前檔案	C:\GCSV\SCRIPTS\PRE-EXPORT.CSV	此腳本會在完整導出或（delta）導出之前執行
匯出後檔案	C:\GCSV\SCRIPTS\POST-EXPORT.CSV	此文稿會在完整匯出或 （delta） 匯出之前執行

確認設定符合提供的值之後，請點選下一步按鈕。

PowerShell 腳本執行

GCSV 連接器會在自己的會話中執行每個已設定的 PowerShell 腳本，而且不支援在腳本執行之間傳遞變數。

此外，GCSV 連接器會在檔案內執行 PowerShell 腳本，而不是 Cmdlet。 這表示輸入參數無法透過將其附加到路徑語句的結尾來傳遞至腳本。 這樣做會導致腳本執行失敗。

重要

GCSV 連接器不支援在執行 PowerShell 腳本時使用傳遞輸入參數。

如果預先匯入或匯出前腳本執行擲回例外狀況，為了避免匯入或匯出不當處理的使用者或群組記錄，GCSV 連接器將會中止並停止整個執行配置檔的執行。

同樣地，如果匯入后或匯出後作業發生例外狀況，則會導致作業狀態失敗。

PowerShell 文稿執行期間發生的錯誤會記錄到 MIM 同步處理伺服器的 *事件 *記錄檔中。

PowerShell 輸入參數：OperationType

雖然不支援使用輸入參數，但 GCSV 連接器會傳遞一個輸入參數來執行每個 PowerShell 腳稿：OperationType。

輸入變數 OperationType 會有值 Full 或 Delta，以顯示與腳本一起執行的作業類型（例如，完整匯入、差異匯入、完整導出、差異導出）。 這個值可讓腳本檢查它們是否在完整或差異匯入/匯出環境下執行，來執行相應的前置或後置處理工作。

配置層級

因為 CSV 檔案不會將資訊儲存在階層式結構中;一般 CSV 連接器不支援任何階層式佈建組態。

下圖是 佈建階層 頁面的範例。

確認設定符合提供的值之後，按一下 下一步 按鈕。

分區和階層

一般 CSV 連接器會為其連接器空間中的每個使用者和群組記錄建置不同的辨別名稱 （DN），並遵循此 LDAP 格式：

CN=[ANCHOR_VALUE],Object=User|Group,O=CSV

下圖是 分割區與階層 頁面的範例。

在確認設定符合提供的值之後，請按一下 下一步 按鈕。

物件類型

泛型 CSV 連接器至少需要指定 User 物件類型。 Group 物件類型的選擇是選擇性的。

下圖是 [物件類型] 頁面的範例。

確認設定符合提供的值之後，請按 下一步 按鈕。

屬性

此頁面會顯示所有所選物件類型架構中所有屬性的標準化清單。

下圖是 [屬性] 頁面的範例。

確認設定符合提供的值之後，請按一下 下一步 按鈕。

注意

一律需要錨點屬性，才能讓 GCSV 連接器正常運作。

錨

一般 CSV 連接器不支援使用與對應物件的 CSV 檔案錨點標識符字段指定不同的複雜錨點或錨點屬性組態。 這就是為什麼錨點選取欄位已鎖定的原因。 若要變更錨點屬性指定，請返回 [架構 2 [識別與參考字段組態] 頁面。

下圖是 Anchors 頁面的範例。

螢幕快照

檢閱頁面上的預設設定之後，按一下 [下一步] 按鈕。

連接器篩選

本指南不會使用任何連接器篩選組態。 本節旨在提供指南的連貫性。

下圖是 連接器篩選 頁面的範例。

檢閱頁面上的預設設定之後，按一下 下一步 按鈕。

聯結和投影規則

本指南不會使用任何聯結和投影規則組態。 本節在這裡確保指南的連貫性。

下列圖片是 [聯結和投影規則] 頁面的範例。

檢閱頁面上的預設設定之後，按一下 下一步 按鈕。

屬性流程

本指南不會使用任何屬性流程規則設定。 本節旨在確保指南的連貫性。

下圖是 屬性流程 頁面的範例。

的螢幕快照

在確認設定符合預設值之後，請按一下 下一步 按鈕。

撤銷資源

本指南中，我們不會更改此連接器的預設取消布建設定。 本節的目的是在指南中保持連貫性。

下圖是 取消布建 頁面的範例。

的螢幕快照

確認設定符合預設值之後，請按一下 下一步 按鈕。

建立完整匯入執行配置檔

需要完整匯入執行配置檔，才能將 CSV 記錄中的使用者和群組身分識別數據匯入連接器空間物件。

使用下列步驟建立新的完整匯入執行設定檔：

• 返回 Synchronization Service Manager。
• 選取 GCSV 管理代理程式。
• 以滑鼠右鍵點擊它，然後選擇 [配置執行檔案。
• 點選 新增設定檔。

[設定執行設定檔] 視窗隨即出現。

將執行配置檔命名為

在 [配置檔名稱] 頁面中，輸入 完整匯入 名稱

以下的圖像是個人資料頁面的範例。

在確認設定符合提供的值之後，按下一步按鈕。

指定類型

在 [設定步驟] 頁面中，選取類型：完整匯入。

GCSV 連接器中的篩選操作與其他任何 ECMA 連接器相同。

以下圖片是 [連接器篩選] 頁面的範例。

確認設定符合提供的值之後，請按一下 下一步 按鈕。

管理代理程式組態類型

在 [管理代理程式組態類型] 頁面上，確定已選取 [O=CSV 分割區]。

的螢幕快照

保留其餘設定的預設值。 單擊[完成] 按鈕將會建立執行配置檔。

驗證結果

本節詳細說明驗證建立新 GCSV 連接器結果以及從範例 CSV 檔案匯入使用者和群組記錄所需的步驟。

執行完整匯入

建立執行設定檔之後，請使用下列步驟來執行這個新的完整匯入執行設定檔：

• 返回 Synchronization Service Manager。
• 選取 GCSV 管理代理程式。
• 在其上按右鍵，然後選擇 執行。
• 選取 完整匯入 並按下 確定。

驗證完整匯入作業結果

根據範例 CSV 檔案的內容，應該有五（5）個增補項目：

下圖是成功匯入範例 CSV 檔案內容的結果範例：

檢查 GCSV 連接器空間

建立執行設定檔之後，請使用下列步驟來執行這個新的完整匯入執行設定檔：

• 請返回到 Synchronization Service Manager。
• 選取 GCSV 連接器 管理代理程式。
• 以滑鼠右鍵按下它，然後選擇 [搜尋連接器空間]。
• 將範圍保留為其預設值 子樹，然後按一下 搜尋 按鈕。

下圖是可能會出現的 搜尋連接器空間 窗口的範例。

驗證用戶物件

選取其中一個用戶對象進行檢查。 下圖是使用者 GCSV 連接器空間物件的範例：

的螢幕快照

[DisplayName] 字段的檢查顯示了合格字串如何被正確剖析。

按一下 ProxyAddresses 條目中的按鈕，可查看多重值字串也正確地解析為個別值：

的螢幕快照

驗證群組物件

選取其中一個要檢查的群組物件。 下圖是群組 GCSV 連接器空間物件的範例：

的螢幕快照

點擊 成員 條目的按鈕，會顯示如何將相關記錄群組檔案的成員記錄正確地載入到成員檔案中：

的螢幕快照

驗證 PowerShell 執行記錄

本指南中提供的範例 PowerShell 腳本設計用來將 CSV 條目新增至中央記錄，以顯示其成功執行。

此記錄預設位置為 C:\GCSV\PS_Run_Ledger.csv。

開啟記錄會顯示：

"DateTime","Stage","Name","Type","Description"

"3/17/2024 1:05:44 PM","Pre","Import","Full","The Pre-Import PowerShell script was executed successfully."
"3/17/2024 1:05:46 PM","Pre","Import","Full","The Post-Import PowerShell script was executed successfully."

這兩筆記錄表示預先匯入和匯入后 PowerShell 腳本都已成功執行。 注意 [類型] 字段指出這些 PowerShell 腳本是在完整匯入期間執行。 它會從 OperationType PowerShell 輸入參數取得這些值，指出腳本是在完整或差異作業期間執行。

附錄 A - 範例 CSV 檔案

下列各節包含本指南中使用的 CSV 檔案。

範例使用者 CSV 檔案

在連接器的設定中，本指南假設檔名為 USERS.CSV。

EmployeeID,DisplayName,AccountName,CountryCode,Manager,ProxyAddresses,IsActive,ProfilePic
E001,"Smith, John",JS001,1,,SMTP:john.smith@contoso.com;smtp:js001@contoso.com,True,SgBTADAAMAAxAA==
E002,"Doe, Jane",JD003,1,E001,SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com,True,SgBEADAAMAAyAA==
E003,"Perez, Juan",JP003,1,E001,SMTP:juan.perez@contoso.com;smtp:jp003@contoso.com,False,SgBEADAAMAAyAA==

範例群組 CSV 檔案

在連接器的組態中，本指南假設檔名為 GROUPS.CSV。

GroupID,DisplayName,Description,Owner
G001,Test Group (G001),"This group is for teams A, B, and C",E002
G002,Test Group (G002),"This group is for teams D, E, and F",E003

範例成員 CSV 檔案

在連接器的組態中，本指南假設檔名為 MEMBERS.CSV。

ParentID,MemberID,ObjectType
G001,E001,USER
G001,E002,USER
G001,E003,USER
G002,E001,USER
G002,E002,USER
G002,E003,USER
G002,G001,GROUP
G003,E001,USER
G003,E002,USER
G003,E003,USER
G003,G001,GROUP

附錄 B - 範例 PowerShell 檔案

本附錄包含本指南中使用的範例 PowerShell 腳本集合。 下列各節詳細說明應在何時進行的一些考慮

重要

在 PowerShell 腳本中執行 write-host命令會導致腳本的執行失敗。

範例預先匯入 PowerShell 腳本

在連接器的設定中，本指南假設 PRE-IMPORT.PS1的檔名。

param ([string]$OperationType)

[string]$stage = "Pre"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

匯入後的 PowerShell 腳本範例

在連接器的組態中，本指南假設 POST-IMPORT.PS1 的檔名。

param ([string]$OperationType)

[string]$stage = "Post"
[string]$operation = "Import"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

匯出前 PowerShell 腳本範例

在連接器的設定中，本指南假設 PRE-EXPORT.PS1的檔名。

param ([string]$OperationType)

[string]$stage = "Pre"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed before a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append

匯出後PowerShell腳本範例

在連接器的組態中，本指南假設 POST-EXPORT.PS1的檔名。

param ([string]$OperationType)

[string]$stage = "Post"
[string]$operation = "Export"
[string]$filePath = "C:\GCSV\PS_Run_Ledger.csv"

# Create a new record
$record = [PSCustomObject]@{
    "DateTime" = (Get-Date).ToString()
    "Stage" = $stage
    "Type" = $OperationType
    "Name" = $operation
    "Description" = "The $stage-$operation PowerShell script was successfully executed after a $OperationType-$operation."
}

$record | Export-Csv -Path $FilePath -NoTypeInformation -Append