一般 CSV 連接器 - 逐步參考指南 (Preview)

本文說明一般 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 同步處理 管理員 角色的帳戶來執行下列工作：

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

讓我們開始吧！

若要建立一般 CSV 連接器，請在 MIM 同步處理 Service Manager 選取[管理代理程式和建立]。 選取 [ 一般 CSV (Microsoft) 連接器]。

探查連接器的名稱 (例如： 一般 CSV) 然後按兩下 [ 下一步] 按鈕。

連接性

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

下圖是 [ 連線能力 ] 頁面的範例：

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

設定名稱	設定值	備註
用戶檔案	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 ] ([識別和參考字段組態] 頁面的範例) 。

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

設定名稱	設定值
[用戶記錄標識碼] 欄位	EmployeeID
用戶記錄識別符欄位屬性類型	字串
群組記錄標識符欄位	GroupID
群組記錄標識符欄位屬性類型	字串
父群組標識碼	ParentID
成員標識碼	MemberID
成員物件類型	ObjectType

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

架構 3 (使用者檔案屬性架構組態)

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

下圖是 [ 架構 3 ] ([使用者檔案屬性架構組態) ] 頁面的範例。

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

設定名稱	設定值	備註
DisplayName 屬性類型	字串	限定字串的範例在此欄位中
DisplayName 為多重值	false	--
AccountName 屬性類型	字串	--
AccountName 為多重值	false	--
CountryCode 屬性類型	整數	--
CountryCode 為多重值	false	--
管理員屬性類型	參考	包含指派的管理員用戶記錄 (錨點屬性值，例如 E001)
管理員為多重值	false	--
ProxyAddresses 屬性類型	字串	--
ProxyAddresses 為多重值	TRUE	包含如何分隔多重值字串的範例
IsActive 屬性類型	布林值	--
IsActive 為多重值	false	--
ProfilePic 屬性類型	二進位	--
ProfilePic 為多重值	false	--

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

架構 4 (群組檔案屬性架構組態)

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

下圖是 [ 架構 4 ] ([檔案屬性架構組態) ] 頁面的範例。

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

設定名稱	設定值	備註
DisplayName 屬性類型	字串	--
DisplayName 為多重值	false	提供限定字串值的範例。
描述屬性類型	字串	--
描述為多重值	false	--
擁有者屬性類型	參考	提供參考值的範例。
擁有者為多重值	false	--

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

PowerShell 腳本組態 (全域參數)

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

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

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

設定名稱	設定值	備註
預先匯入檔案	C:\GCSV\SCRIPTS\PRE-IMPORT.CSV	此腳本會在完整匯入之前執行
匯入後檔案	C:\GCSV\SCRIPTS\POST-IMPORT.CSV	此腳本會在完整匯入之後執行
匯出前檔案	C:\GCSV\SCRIPTS\PRE-EXPORT.CSV	此腳本會在完整匯出或 (差異) 匯出之前執行
匯出後檔案	C:\GCSV\SCRIPTS\POST-EXPORT.CSV	此腳本會在完整匯出或 (差異) 匯出之前執行

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

PowerShell 腳本執行

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

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

重要

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

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

同樣地，如果匯入后或匯出後作業遇到例外狀況，就會造成作業狀態失敗。

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

PowerShell 輸入參數：OperationType

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

輸入變數 OperationType 會有 [完整 ] 或 [ 差異 ] 值，以顯示 (運算類型，例如完整匯入、差異匯入、完整導出、 (Delta) 導出) 與腳本一起執行。 此值可讓腳本檢查它們是否在完整或差異匯入/匯出內容下執行，並據以執行其前置或後置處理工作。

佈建階層

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

下圖是 [ 布建階層] 頁面的範例。

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

數據分割和階層

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

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

下圖是 [ 數據分割和階層 ] 頁面的範例。

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

物件類型

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

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

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

屬性

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

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

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

注意

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

錨點

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

下圖是 Anchors 頁面的範例。

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

連接器篩選

本指南不會使用任何連接器篩選設定。 本節提供指南中的持續性。

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

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

聯結和投影規則

本指南不會使用任何聯結和投影規則設定。 本節提供指南中的持續性。

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

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

屬性流程

本指南不會使用任何屬性流程規則設定。 本節提供指南中的持續性。

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

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

Deprovisioning

本指南不會變更此連接器的預設取消布建設定。 本節提供指南中的持續性。

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

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

建立完整匯入執行配置檔

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

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

• 返回 同步處理 Service Manager。
• 選取 GCSV 管理代理程式。
• 以滑鼠右鍵按下它，然後選擇 [ 設定執行設定檔]。
• 按一下 [新增設定檔]。

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

將執行配置檔命名為

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

下圖是 [配置檔] 頁面的範例。

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

指定類型

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

連接器篩選在 GCSV 連接器中的運作方式與任何其他 ECMA 連接器的運作方式相同。

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

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

管理代理程式組態類型

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

保留其餘設定的預設值。 按兩下 [ 完成] 按鈕將會建立執行設定檔。

驗證結果

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

執行完整匯入

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

• 返回 同步處理 Service Manager。
• 選取 GCSV 管理代理程式。
• 以滑鼠右鍵按兩下它，然後選擇 [ 執行]。
• 選取 [完整匯入 ]，然後按兩下 [ 確定]。

驗證完整匯入作業結果

根據範例 CSV 檔案的內容，應該有五個 (5 個) 新增：

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

檢查 GCSV 連接器空間

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

• 返回 同步處理 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 輸入參數取得這些值，指出腳本是在完整或 Delta 作業期間執行。

附錄 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命令使用都會造成腳本的 Exection 失敗。

範例預先匯入 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