通用 CSV 连接器 - (预览版) 技术参考指南

本文介绍通用 CSV (GCSV) 连接器。 本文适用于以下产品：

• Microsoft Entra Connect 预配代理 (ECMA2Host)
• Microsoft 标识管理器 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连接预配代理 (ECMA2Host) Microsoft 标识管理器 2016 (MIM2016)
支持的 CSV 文件	此连接器支持通过配置最多三个 CSV 文件来管理用户 (所需的) 和组 (可选) ： 用户 CSV 文件 (例如 Users.csv) 组 CSV 文件 (例如 Groups.csv) 组成员 CSV 文件 (例如 Members.csv)
使用 PowerShell 进行操作前/后处理	此连接器支持配置最多 4 个 (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 Syncs 管理员 角色的帐户来执行以下任务：

• 从 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 (可分辨名称) 以唯一标识其连接器空间中的每个 User 或 Group 对象。 所有 DN 值使用以下格式表示： CN=[ANCHOR_VALUE]，Object=[User|组]，O=CSV。
• 对象确认 (正常) ：通常，同步引擎假定它可以在导出后的后续增量导入中再次检索对象。 这是同步引擎通常的工作方式，但并非所有连接的系统都以这种方式运行。 正常 设置可确保 后续导入中没有 exported-change-not-reimported 警告。
• 导出类型 (MultivaluedReferenceAttributeUpdate) ：导出类型指定如何在同步期间格式化对象并将其发送到目标系统。 MultivaluedReferenceAttributeUpdate 是一种设计用于Microsoft Entra ID的导出类型。 它仅发送已更改的属性。 对于值类型属性，它使用 AttributeReplace;对于引用属性，它使用 AttributeUpdate。
• 规范化 (无) ：规范化是指将数据标准化为一致的格式。 “无”表示未应用特定的规范化规则。 数据保持原样，连接器无需进行任何其他转换。

架构 1 (CSV 文件格式配置)

GCSV 连接器利用三种分隔符 (或分隔符) 来分隔和分析 CSV 字段及其值。

此页包含这些分隔符的字符值设置，以及用于将文件创建为 CSV 的编码类型。

下图是 架构 1 (CSV 文件格式配置) 页的图像。

以下部分列出了各个配置：

• 使用标头进行架构发现：选择此选项后，它会指示连接器将每个 CSV 文件的第一条记录视为标头记录，而不是标识数据记录。 如果未选择此选项，连接器将使用附加的唯一递增整数值 (例如 Attribute1、Attribute2 等 ) 分配名称Attribute，并将 的第一行视为标识数据记录。
• 值分隔符：此字符分隔 CSV 记录的值) 字段 (。 默认值为逗号 (，) ，但允许任何可以打印的字母数字字符。
• 多值分隔符：此类型的分隔符用于分隔多值字符串的单个值 (例如，代理地址) 或引用属性 (例如从属 ) 默认值为分号 (;) 但任何可打印的字母数字字符都是可接受的。
• 文本限定符：如果字符串值包含将 (解释为分隔符的字符（例如逗号) ），则需要限定该值，以便 CSV 分析程序可以将字符串正确解释为单个字段。 默认值为双引号 (“) ，但允许任何可以打印的字母数字字符。

注意

尽管 CSV 文件的架构可能不包含任何多值字段，也可能不包含任何需要字符串限定的值，但需要为每个分隔符类型指定唯一的可打印字符。

• 文件编码：此设置指示在“连接”选项卡中添加的 CSV 文件上使用的编码。确保它与 CSV 文件的编码匹配。

注意

如果不确定 CSV 文件的编码类型，应尝试使用默认的 Unicode 编码类型。 Unicode 是支持许多字符和符号的常见标准，因此它是跨大多数语言或字符集对文本数据进行编码的不错选择。

架构 2 (标识和引用字段配置)

定位点值是 CSV 文件中记录的唯一标识符。 它将一条记录与其他记录区分开来。 GCSV 连接器还使用此值创建可分辨名称 (用于标识相关连接器空间对象的 DN) 。

在此页上，为“连接”页上列出的每个 CSV 文件设置定位点属性设置。

下图是 架构 2 (标识和引用字段配置) 页的示例。

以下部分是此页上各个配置的列表：

• 用户
  • 用户定位点：用户文件中用作用户记录的定位点值的字段。 “用户”文件中的第一个标头字段是默认选项。
  • 用户定位点属性类型：这是所选定位点的属性类型。
• 组
  • 组定位点：组文件中用作组记录的定位点值的字段。 “组”文件中的第一个标头字段是默认选项。
  • 组定位点属性类型：这是所选定位点的属性类型。
• 成员
  • 父组 ID：成员文件中与组 CSV 文件中的父组具有相同 (定位点) 值的字段。 默认情况下，将使用成员文件中的第一个字段。
  • 成员 ID：成员文件中具有与用户或组 CSV 文件中相同的 (定位点) 值的字段。 默认情况下，“成员”文件中的第二个字段处于选中状态。
• 成员对象类型：包含“用户”或“组”字符串值的字段，用于指示成员的对象类型。 仅当成员文件包含两个以上的字段时，才需要此字段。 “对象类型”字段只能包含字符串值“User”或“Group”。如果缺少此字段，连接器将假定成员文件记录引用 User 对象成员。 默认情况下，在 Members 文件上找到的第三个字段处于选中状态。

重要

指定用作定位点的属性的名称在所有对象类型架构中必须是唯一的。 这包括组成员文件中指定的定位点。

架构 3 (用户文件属性架构配置)

此页用于指定和说明在用户 CSV 文件的架构中标识的每个字段的数据类型，以及它们是否可以具有多个值。

下图是 架构 3 (用户文件属性架构配置) 页的示例。

以下部分列出了进行属性数据类型分配时的注意事项。

支持的数据类型

GCSV 连接器支持使用以下节数据类型：

• 布尔值：可以是 true 或 false 的值。
• Binary：存储为字节序列的值，通常用于存储图像或其他文件等数据。
• Integer：一个整数值，不带任何小数位数。
• 字符串：一个值，该值是字符序列，通常用于存储文本数据。
• 引用：一个值，该值是对另一个用户对象的引用。 若要在 CSV 文件中指定引用值，请使用引用的用户对象的定位点值填充其字段。

重要

用户或组引用属性只能用于引用用户对象。 这不适用于 Group 对象的 Member 属性，只要指定了对象类型字段，该属性就可以包含用户或组引用。

支持的 Multiple-Value 数据类型

连接器仅支持对以下数据类型使用多值属性：

• String

注意

如果 User 和 Group 对象的架构都具有同名 (非定位点) 属性，则可能不会在它们之间分配不同的数据类型。 它们必须共享相同的数据类型。

架构 4 (组文件属性架构配置)

此页用于指定和说明在 Groups 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 连接器按照以下 LDAP 格式，为其连接器空间中的每个用户和组记录生成不同的可分辨名称 (DN) ：

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

下图是 “分区和层次结构 ”页的示例。

对象类型

GCSV 连接器要求至少选择“用户”对象类型。 Group 对象类型的选择是可选的。

下图是 “对象类型” 页的示例。

属性

此页显示所有选定对象类型架构中所有属性的规范化列表。

下图是 “属性” 页的示例。

注意

只有在选择了“组”时，Member 属性才存在，并且将包含对组成员 CSV 文件中维护的对象引用。

定位点

GCSV 连接器不支持使用与相应 CSV 文件的定位点 ID 字段不同的复杂定位点或定位点属性配置。

若要更改此页上显示的定位点指定，请返回到架构 2 (定位点配置) 。

下图是 “定位点 ”页的示例。

预配 CSV 记录

为了使 GCSV 连接器将新的用户或组对象添加到其相应的 CSV 文件中，必须为其预配新的连接器空间对象。

无论是使用 MIM 2016 声明性预配 还是编写自己的 MIM 同步规则扩展，新的连接器空间对象都必须具有以下格式构造的 DN：

CN=[ANCHOR_VALUE]，Object=User|组，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"

示例：分隔多值字符串

若要在一个字符串字段中提供多个字符串值，请使用 多值分隔符分隔值。 以下部分 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 文件中表示二进制值，必须将二进制值转换为使用与 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# 中的等效函数，它接受名为 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 脚本。