一般 CSV 連接器 - Technical Reference Guide (Preview)

本文說明一般 CSV (GCSV) Connector。 本文適用於下列產品：

• Microsoft Entra 連線佈建代理程式 (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

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

若要查看這個作用中的連接器，請參閱 Generic SQL Connector step-by-step (一般 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 連線佈建代理程式 (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 字串) 布爾值 – (為 True/False) 整數 字串 / 多重值字串 參考
CSV 欄位分隔符	支援逗號 (、) 或任何可列印的英數位元，以限定任何字串值的開頭和結尾。
字串限定性支援	支援雙引號 (「) 或任何可列印的英數位元，以限定任何字串值的開頭和結尾。
多重值字串支援	支援多重值字串
支援的連接器作業	連接器支援下列作業： 完整匯入 匯出 完整匯出
結構描述	架構探索是動態的，但需要手動設定來完成。 欄位會根據指定的分隔符 (或稱為「值分隔符」來動態識別。) 欄位數據類型會在設定期間手動指定。

必要條件

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

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

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

重要

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

建立新的連接器

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

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

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

連接性

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

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

此頁面會指定下列 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。
• 正規化 (無) ：正規 化是指將數據標準化為一致的格式。 無表示不會套用任何特定的正規化規則。 數據會依原狀維持不變，而不會由連接器進行任何其他轉換。

架構 1 (CSV 檔案格式組態)

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

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

下圖是 [ 架構 1 (CSV 檔案格式 組態) ] 頁面的影像。

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

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

注意

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

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

注意

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

架構 2 (身分識別和參考欄位組態)

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

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

下圖是 [架構 2 (身分識別和參考欄位組態] 頁面的範例) 。

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

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

重要

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

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

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

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

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

支援的資料類型

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

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

重要

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

支援的 Multiple-Value 數據類型

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

• String

注意

如果 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。

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

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

佈建階層

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

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

數據分割和階層

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

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

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

物件類型

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

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

屬性

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

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

注意

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

錨點

GCSV 連接器不支援使用複雜錨點，也不支援錨點屬性組態與其對應的 CSV 檔案錨點標識符字段不同。

若要變更此頁面顯示的錨點指定，請返回架構 2 (錨點組態) 。

下圖是 Anchors 頁面的範例。

布建 CSV 記錄

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

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

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

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

元件	備註
CN=[ANCHOR VALUE]	[一般名稱] (CN) 必須是唯一的值，而且將會寫入 CSV 檔案的指定錨點欄位中。
Object=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 範例中，[管理員] 字段包含其所參考之用戶記錄的錨點值：

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

範例：二進位欄位欄位

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

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

以下是 C# 中的對等函式，可接受稱為 text 的輸入參數，並在 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腳本。