一般 CSV 連接器 - 技術參考指南 （預覽）

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

• Microsoft Entra Connect 佈建代理 (ECMA2Host)
• Microsoft Identity Manager 2016 （MIM2016）

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

若要查看此連接器的運作方式，請參閱 一般 SQL 連接器逐步操作 一文。

註記

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

一般 CSV 連接器概觀

一般 CSV （GCSV） 連接器可讓您整合 CSV 檔案中維護的使用者和群組身分識別數據與Microsoft產品，例如 Microsoft Entra Connect 布建代理程式 （ECMA2Host） 和 Microsoft Identity Manager 2016 （MIM2016）。

它具有各種功能，例如協調使用PowerShell來管理匯入或匯出作業前後的身分識別數據。 它支援多個數據類型，包括二進位和參考、支援限定字串值，以及多重值字串。

本文說明一般 CSV 連接器的功能，以及如何設定 MIM 2016 的功能。

下表列出連接器目前版本從高階觀點支援的功能：

特徵	詳細資訊
多個產品支援	下列Microsoft產品支援使用此連接器： Microsoft Entra Connect 佈建代理程式 （ECMA2Host） Microsoft Identity Manager 2016 （MIM2016）
支援的 CSV 檔案	此連接器支援透過最多三個 CSV 檔案的設定來管理使用者（必要）和群組（選擇性）： 使用者 CSV 檔案 （例如 Users.csv） 群組 CSV 檔案 （例如 Groups.csv） 群組成員 CSV 檔案 （例如 Members.csv）
使用 PowerShell 進行作業前/後處理	此連接器支援最多 4 個 PowerShell 腳本的設定，以利在匯入或匯出之前或之後處理使用者和群組身分識別數據。
支援的 CSV 檔案編碼	連接器支援所有預設（或已安裝）伺服器編碼類型：（例如 Unicode、UTF-8、UTF-7、ASCII 等）
支援的 CSV 欄位資料類型	連接器支援下列屬性資料類型： 二進位 – （以 base64 字串形式） 布爾值 – （為 真/假） 整數 字串 / 多重值字串 參考
CSV 欄位分隔符	支援逗號 （，，） 或任何可列印的英字字元，以限定任何字串值的開頭和結尾。
字串限定性支援	支援雙引號 （“） 或任何可列印的英數位元，以限定任何字串值的開頭和結尾。
多重值字串支援	支援多重值字串
受支援的連接器操作	連接器支援下列作業： 完整匯入 出口 完整匯出
圖式	架構探索是動態的，但需要手動設定來完成。 欄位會根據指定的分隔符動態識別（或稱為「值分隔符」）。 欄位數據類型會在設定期間手動指定。

先決條件

在使用連接器之前，請確保您在同步伺服器上具備以下項目：

• Microsoft .NET 4.6.2 Framework 或更新版本
• 包含下列身分識別類型的所需架構的 CSV 檔案：
  • 使用者檔案 （必要）
  • 群組（選擇性）
  • 群組成員（如果使用群組時是必要的）
• （選擇性）用來管理下列作業類型事件的前置和後置處理的 PowerShell 腳稿：
  • 預先匯入 – 執行匯入作業之前，會執行此腳本。
  • 匯入後 – 此腳本會在匯入作業運行之後被運行。
  • 匯出前 – 此文稿會在執行匯出作業之前執行。
  • 匯出后 – 執行匯出作業之後，就會執行此腳本。

MIM 同步處理服務帳戶許可權

重要

MIM 2016 同步處理服務帳戶是在安全性環境中執行對 CSV 檔案的檔案作業，並執行前置與後置處理的 PowerShell 腳本。 此服務帳戶需要所有已設定之 CSV 和 PowerShell 檔案的讀取/寫入許可權。 它也需要適當的 PowerShell ExecutePolicy 許可權 來執行任何已設定的腳本。

建立新的連接器

下列清單是本指南中所述步驟的高階概觀。 若要開始，必須使用具有 MIM Syncs Admin 角色的帳戶來執行下列工作：

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

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

建立連接器第 1 頁

連線

[連線] 頁面包含 [使用者]、[群組] 和 [群組成員] CSV 檔案的檔案位置。

下圖是 Connectivity 頁面的範例。

此頁面會指定下列 CSV 檔案的位置：

• 使用者檔案：CSV 檔案的完整路徑，其中包含用戶記錄及其屬性值。 需要此檔案。
• 群組檔案：包含群組記錄之 CSV 檔案的完整路徑。 此檔案是選擇性的。
• 成員檔案：包含群組成員參考記錄的 CSV 檔案的完整路徑。

重要

MIM 同步處理服務帳戶必須具有 讀取，並 寫入所有指定 CSV 檔案的許可權。 如先前所述，只有用戶設定時，就不需要群組和成員檔案。

當您建立新的一般 SQL 連接器時，連線畫面是第一個。 您必須先提供下列區段資訊：

能力

此頁面描述連接器的功能。 連接器功能已修正且無法變更，但此處會加以說明，以提供連接器運作方式的相關信息。

下圖是 功能 頁面的範例。

下一節列出個別組態及其意義：

• 辨別名稱樣式 （LDAP）：GCSV 連接器會使用LDAP（輕量型目錄存取通訊協定）語法來建構 DN （辨別名稱） 以唯一識別其連接器空間中的每個使用者或群組物件。 所有 DN 值都會以下列格式表示：CN=[ANCHOR_VALUE]，Object=[User|Group]，O=CSV。
• 物件確認（一般）：一般來說，同步處理引擎會假設它可以在匯出後的下一次差異匯入中再次擷取物件。 這是同步處理引擎通常運作的方式，但並非所有連線的系統都會以這種方式運作。 此 標準 設定可確保後續匯入中沒有 exported-change-not-reimported 警告。
• 匯出類型 （MultivaluedReferenceAttributeUpdate）：匯出類型會指定物件在同步處理期間如何格式化及傳送至目標系統。 MultivaluedReferenceAttributeUpdate 是一種設計用於與 Microsoft Entra ID 配合工作的匯出類型。 它只會傳送已變更的屬性。 對於實值型別屬性，它會使用 AttributeReplace 和參考屬性，它會使用 AttributeUpdate。
• 正規化 （None）：正規化是指將數據標準化為一致格式。 無表示不會套用任何特定的正規化規則。 數據會維持 as-is，而不需要連接器進行任何其他轉換。

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

GCSV 連接器會利用三種分隔符（或分隔符）來分隔和剖析 CSV 字段及其值。

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

下圖是 架構 1 （CSV 檔案格式組態） 頁面的影像。

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

• 使用標頭進行架構探索：選取此選項時，它會指示連接器將每個 CSV 檔案的第一筆記錄視為標頭記錄，而不是識別數據記錄。 如果未選取此選項，連接器會使用附加的唯一遞增整數值來指派名稱 Attribute（例如，Attribute1、Attribute2等），並將 的第一個數據列視為識別數據記錄。
• 值分隔符：此字元會分隔 CSV 記錄的欄位（也就是值）。 逗號（，）是預設值，但允許任何可以列印的字母和數字字符。
• 多重值分隔符：此分隔符類型可用來分隔多重值字串的個別值（例如 Proxy 位址）或參考屬性（例如次級。默認值為分號（;)，但可以接受任何可列印的英數位元。
• 文字限定符：當字串值包含將其他解譯為分隔符的字元時（例如逗號），它需要限定值，讓 CSV 剖析器可以正確地將字元串解譯為單一字段。 雙引號（"）是預設值，但允許使用任何可以顯示的英數字符。

注意

雖然 CSV 檔案的架構不能包含任何多重值欄位，或不能包含任何需要字串限定的值，但需要為每個分隔符類型指定唯一可列印的字元。

• 檔案編碼：此設定表示在 [連線能力] 索引標籤中新增的 CSV 檔案上使用的編碼方式。請確定它符合 CSV 檔案的編碼方式。

注意

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

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

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

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

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

下一節是此頁面上個別組態的清單：

• 使用者
  • User Anchor：[使用者] 檔案中的欄位，做為用戶記錄的錨點值。 [使用者] 檔案中的第一個標頭字段是預設選擇。
  • User Anchor 屬性類型：這是所選取錨點的屬性類型。
• 群組
  • 群組錨點：群組檔案中的欄位，做為群組記錄的錨點值。 群組檔案中的第一個標頭欄位是預設選擇。
  • 群組錨點屬性類型：這是所選取錨點的屬性類型。
• 成員
  • 父群組標識符：成員檔案中與群組 CSV 檔案中父群組具有相同 （錨點） 值的欄位。 預設會使用 Members 檔案中的第一個字段。
  • 成員標識碼：成員檔案中與使用者或群組 CSV 檔案中具有相同 （錨點） 值的欄位。 默認會選取 [成員] 檔案中的第二個字段。
• 成員物件類型：包含 「User」 或 「Group」 字串值的欄位，表示成員的物件類型。 只有當 Member 檔案包含兩個以上的欄位時，才需要此欄位。 [物件類型] 欄位只能包含字串值 「User」 或 「Group」。如果遺漏此欄位，連接器會假設 Members 檔案記錄參考 User 物件成員。 默認會選取 [成員] 檔案上找到的第三個字段。

重要

指定為錨點的屬性名稱在所有物件類型架構中都必須是唯一的。 這包括群組成員檔案中指定的錨點。

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

此頁面用於指定及說明使用者 CSV 檔案架構中所識別之每個欄位的數據類型，以及是否可以有多個值。

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

下一節列出進行屬性數據類型指派時的考慮。

支援的數據類型

GCSV 連接器支援使用下列區段資料類型：

• 布爾值：可以是 true 或 false 的值。
• Binary：儲存為位元組序列的值，通常用來儲存影像或其他檔案等數據。
• 整數：整數值，不含小數位。
• String：值，這個值是字元序列，通常用來儲存文字數據。
• Reference：這是另一個使用者對象的參考值。 若要在 CSV 檔案中指定參考值，請使用所參考使用者物件的錨點值填入其欄位。

重要

使用者或群組參考屬性只能用來參考用戶物件。 這不適用於 Group 物件的 Member 屬性，只要指定物件類型欄位，就可以同時包含使用者或群組參考。

支援的 Multiple-Value 數據類型

連接器僅支援針對下列資料類型使用多重值屬性：

• 字串

注意

如果 User 和 Group 物件的架構都有相同名稱的 （非錨點） 屬性，則不同的數據類型之間可能不會指派。 兩者都必須共用相同的數據類型。

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

此頁面用於指定和說明群組 CSV 檔案架構中所識別之每個欄位的數據類型，以及它們是否可以有多個值。

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

架構 3 中提供的指引（使用者檔案屬性組態 也適用於本節。 .

執行初始完整匯入作業之後，連接器空間看起來會類似下圖：

全域參數 （PowerShell 腳本設定）

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

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

的螢幕快照

下一節列出此頁面上的個別組態設定：

• 文稿逾時（分鐘）：腳本在自動中止之前將執行的分鐘數。 此設定的預設值 100，而且需要大於零（0） 的值。
• 預先匯入腳本檔案：匯入之前應該執行之 PowerShell 腳本的完整路徑。 此設定是選擇性的，不需要值。
• 匯入後腳本檔案：匯入后應該執行之 PowerShell 腳本的完整路徑。 此設定是選擇性的，不需要值。
• 匯出前腳本檔案：匯出之前應該執行之 PowerShell 腳本的完整路徑。 此設定是選擇性的，不需要值。
• 匯出後腳本檔案：匯出后應該執行之 PowerShell 腳本的完整路徑。 此設定是選擇性的，不需要值。

PowerShell 腳本執行和輸入參數

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

連接器會將一個輸入參數傳遞至名為 OperationType 的每個腳本。 此參數的值會根據執行的執行設定檔作業而有所不同，而且它可以是三個值之一：

重要

不支援在匯入或匯出作業之前動態建立 CSV 檔案。 在執行任何執行配置檔之前，所有的 CSV 檔案都必須完全存在。

PowerShell 輸入參數：OperationType

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

• 完整 – 此值是在「完整匯入」或「完整匯出」作業期間提供。
• Delta – 此值會在匯出作業期間提供。

此參數值可以在 PowerShell 腳本的邏輯內使用，以判斷要採取的適當前置/後置處理作業或動作。  

配置階層

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

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

區隔與層級

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

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

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

物件類型

GCSV 連接器至少需要選取 [使用者] 物件類型。 Group 物件類型的選擇是選擇性的。

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

[物件類型] 頁面

屬性

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

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

注意

只有在選取 [群組] 時，[成員] 屬性才會存在，並將包含在群組成員 CSV 檔案中維護的對象的參考。

錨

GCSV 連接器不支援使用複雜錨點，也不支援錨點屬性設定與其對應的 CSV 檔案的錨點 ID 欄位不同。

若要變更此頁面上顯示的錨點指定，請返回架構 2 （錨點設定）。

下圖是 Anchors 頁面的範例。

螢幕快照

提供 CSV 記錄

為了讓 GCSV 連接器將新的使用者或群組物件新增至其對應的 CSV 檔案，必須為其佈建新的連接器空間物件。

無論是使用 MIM 2016 宣告式佈建 還是撰寫您自己的 MIM 同步處理規則延伸模組，新的連接器空間物件都必須使用下列格式建構 DN：

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

下表提供每個元件值的詳細資料：

元件	筆記
CN=[ANCHOR VALUE]	一般名稱（CN）必須是一個唯一的值，並且將會寫入 CSV 檔案指定的錨欄位中。
物件=使用者/群組	此元件表示這個連接器的物件類型。 僅支援 「User」 或 「Group」。
O=CSV	所有 GCSV 連接器空間物件通用的根元件。

下圖是 同步處理規則，示範如何在將新的 User 物件布建至 GCSV 連接器時正確建構 DN：

的螢幕快照

下列程式代碼示範使用metaverse規則延伸模組 的對等布建邏輯。

void IMVSynchronization.Provision(MVEntry mventry)
{
	if (mventry["employeeID"].IsPresent)
	{
		ConnectedMA GCSVConnector = = mventry.ConnectedMAs["Generic CSV Conenctor"];

		if (GCSVConnector.Connectors.Count == 0)
		{
			CSEntry csentry = GCSVConnector.Connectors.StartNewConnector("user");

			//Sets DN to "CN=[ANCHOR_VALUE],OBJECT=[User|Group],O=CSV"
			csentry.DN = GCSVConnector.EscapeDNComponent("CN=" + mventry["employeeID"].Value).Concat("OBJECT=User,O=CSV");

			csentry["AccountName"].StringValue = mventry["accountName"].StringValue;
			csentry["CountryCode"].IntegerValue = 1;
			csentry["DisplayName"].Value = mventry["displayName"].Value;
			csentry["ProxyAddresses"].Value = mventry["proxyAddressCollection"].Value;
			csentry["IsActive"].BooleanValue = true;
			csentry["Manager"].Value = mventry["manager"].Value;
			csentry["ProfilePic"].Value = mventry["pic"].Value;

			csentry.CommitNewConnector();
		}
	}
}

在上一個影像中，請注意使用 EcapeDNComponent() 函式來確保錨點值已正確逸出，使其符合其LDAP語法。

重要

建構 DN 時，不正確地逸出錨點值會導致 invalid‑dn 錯誤。

CSV 欄位格式範例

下列各節列出如何在 CSV 檔案中格式化不同數據類型的範例。 下列所有範例：下一節假設使用連接器的預設欄位分隔符設定：

• 值分隔：逗號（，）
• 多重值分隔符：Semi-Colon （;)
• 文字限定元：雙引號 （“）

範例：文字限定性

如果字串值包含字元，否則會解譯為分隔符（例如逗號），則它需要限定值，讓 CSV 剖析器可以正確地將字串解譯為單一欄位。

以下部分的 CSV 範例顯示了 DisplayName 欄位的值如何被格式化為合格的文本：

EmployeeID,DisplayName
E001,"Smith, John"
E002,"Doe, Jane"
E003,"Perez, Juan"

範例：分隔多重值字串

若要在一個字串字位中提供多個字串值，請使用 Multivalue 分隔符來分隔值，。 下列區段 CSV 範例示範 ProxyAddress 字段如何具有多個值：

EmployeeID,DisplayName,ProxyAddresses
E001,"Smith, John",SMTP:john.smith@contoso.com;smtp:js001@contoso.com
E002,"Doe, Jane",SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com

注意

多重值字串也支援使用字串限定值。 文字限定值可能會以多重值分隔符分隔。

範例：參考欄位

若要在 CSV 檔案中指定參考值，請使用所參考使用者物件的錨點值填入其欄位。 在下列區段 CSV 範例中，Manager 字段包含其所參考之用戶記錄的錨點值：

EmployeeID,DisplayName,Manager
E001,"Smith, John",
E002,"Doe, Jane",E001
E003,"Doe, Jane", 
E004,"Perez, Juan",

範例：二進位欄位

若要在 CSV 檔案中表示二進位值，必須將它們轉換成使用與 CSV 檔案相同編碼類型的base64字串。 下一節 PowerShell 函式示範如何將字串值編碼為 Unicode 中的 base64 編碼字串：

function ConvertTo-Base64([string]$text) 
{
    $bytes = [System.Text.Encoding]::Unicode.GetBytes($text)
    $encodedText = [System.Convert]::ToBase64String($bytes)
    return $encodedText
}

以下是 C# 中的對等函式，可接受稱為文字的輸入參數，並在 Unicode 中傳回 base64 編碼字串。

public static string ConvertToBase64(string text)
{
    byte[] bytes = System.Text.Encoding.UTF8.GetBytes(text);
    string encodedText = System.Convert.ToBase64String(bytes);
    return encodedText;
}

範例：布爾欄位

包含布爾值欄位的 CSV 檔案應該使用 True 或 False 文字來指出其值。 下一節是

EmployeeID,DisplayName,IsActive
E001,"Smith, John",true
E002,"Doe, Jane",true
E003,"Perez, Juan",false

已知限制

下列清單包含 GCSV 連接器的已知限制。

• 參考屬性
  • 除了群組 Member 屬性之外，不支援多重值參考屬性。
  • 參考值必須參考用戶物件。 不支援對群組物件的引用。
• 錨點
  • 不支援使用者和群組對象之間的重複錨點值。
  • 錨點屬性的名稱在使用者和群組架構之間必須是唯一的。
• PowerShell
  • 不支援將輸入變數傳遞至PowerShell腳本。