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

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

• Microsoft 标识管理器 2016 (MIM2016)

对于 MIM 2016，可从 Microsoft 下载中心下载连接器。

注意

Azure AD 预配服务现在提供基于轻型代理的解决方案，用于将用户预配到 CSV 文件中，而无需进行完整的 MIM 同步部署。 建议评估它是否满足你的需求。 了解详细信息。

准备示例 CSV 文件

在运行 MIM 同步服务器的服务器上，创建文件夹 C：\GCSV ，并将 附录 A – 示例 CSV 文件 中找到的以下 CSV 文件复制到其中。 请务必向 MIM Synchronization Service 帐户授予对该文件夹的读写权限。

将以下 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	(used 的完全限定路径和文件名。)
组文件	C:\GCSV\GROUPS.CSV	(used 的完全限定路径和文件名。)
成员文件	C:\GCSV\MEMBERS.CSV	(used 的完全限定路径和文件名。)

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

功能

本页介绍连接器的功能。 GCSV 连接器功能是固定的，无法修改。

下图是 “功能 ”页的示例：

有关这些功能设置的详细说明，请参阅 通用 CSV 连接器 - 技术参考指南。

查看配置后，单击“ 下一步 ”按钮。

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

泛型 CSV (GCSV) 连接器利用三种类型的分隔符 (或分隔符) 来分隔和分析 CSV 字段及其值： 值分隔符、 多值分隔符和 文本限定符。 有关这些分隔符类型的更多详细信息，请参阅 通用 CSV 连接器 - 技术参考指南

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

下图是 架构 1 (CSV 文件格式配置) 页的示例：

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

• 使用标头进行架构发现：如果选择此选项，它会指示连接器忽略每个 CSV 文件的第一条记录作为数据记录，并将其用作标头记录， (即具有每个字段的名称。) 如果未选择此选项，连接器会为每个字段提供一个通用名称 (，例如， Attribute1、Attribute2 等 ) 并使用第一行作为数据记录。
• 值分隔符：此字符分隔 CSV 记录的值) 字段 (。 默认值为逗号 (，) ，但允许任何可以打印的字母数字字符。
• 多值分隔符：此类型的分隔符用于分隔多值字符串的单个值 (例如，代理地址) 或引用属性 (例如从属 ) 默认值为分号 (;) 但任何可打印的字母数字字符都是可接受的。
• 文本限定符：如果字符串值包含将 (解释为分隔符的字符（例如逗号) ），则需要限定该值，以便 CSV 分析程序可以将字符串正确解释为单个字段。 默认值为双引号 (“) ，但允许任何可以打印的字母数字字符。
• 文件编码：此设置指示在“连接”选项卡中添加的 CSV 文件上使用的编码。确保它与 CSV 文件的编码匹配。

注意

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

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

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

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

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

下表是应分配给本页上每个设置的各个值：

设置名称	设置值
用户记录 ID 字段	EmployeeID
用户记录 ID 字段属性类型	字符串
组记录 ID 字段	GroupID
组记录 ID 字段属性类型	字符串
父组 ID	ParentID
成员 ID	MemberID
成员对象类型	ObjectType

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

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

此页面用于为 Users CSV 文件的架构中的每个属性分配数据类型，以及它们是否可以具有多个值。

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

下表是应分配给本页上每个设置的各个值：

设置名称	设置值	备注
DisplayName 属性类型	字符串	限定字符串的示例位于此字段中
DisplayName 为多值	false	--
AccountName 属性类型	字符串	--
AccountName 为多值	false	--
CountryCode 属性类型	整数	--
CountryCode 为多值	false	--
管理器属性类型	引用	包含其分配的经理用户记录 (的定位点属性值，例如 E001)
管理器是多值	false	--
ProxyAddresses 属性类型	字符串	--
ProxyAddresses 是多值	TRUE	包含有关如何分隔多值字符串的示例
IsActive 属性类型	布尔值	--
IsActive 是多值	false	--
ProfilePic 属性类型	二进制	--
ProfilePic 是多值	false	--

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

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

此页面用于为 Groups 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 的值为 Full 或 Delta ，以显示 (操作类型，例如，使用脚本运行的完全导入、增量导入、完全导出 (Delta) Export) 。 如果脚本在完整或增量导入/导出上下文中运行，则此值允许它们检查，并相应地执行其预处理或后处理任务。

预配层次结构

因为 CSV 文件不以分层结构存储信息;通用 CSV 连接器不支持任何分层预配配置。

下图是 “预配层次结构 ”页的示例。

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

分区和层次结构

泛型 CSV 连接器在其连接器空间中为每个用户和组记录生成不同的可分辨名称 (DN) ，遵循以下 LDAP 格式：

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

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

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

对象类型

泛型 CSV 连接器要求至少指定 User 对象类型。 Group 对象类型的选择是可选的。

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

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

属性

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

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

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

注意

要使 GCSV 连接器正常运行，始终需要定位点属性。

定位点

泛型 CSV 连接器不支持使用与其相应对象的 CSV 文件的定位点 ID 字段指定不同的复杂定位点或定位点属性配置。 这就是锁定定位点选择字段的原因。 若要更改定位点属性指定，请返回到 架构 2 (标识和引用字段配置) 页。

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

查看页面上的默认设置后，单击“ 下一步 ”按钮。

连接器筛选器

本指南不会使用任何连接器筛选器配置。 本部分旨在提供指南中的连续性。

下图是 “连接器筛选器” 页的示例。

查看页面上的默认设置后，单击“ 下一步 ”按钮。

联接和投影规则

本指南不会使用任何联接和投影规则配置。 本部分旨在提供指南中的连续性。

下图是“ 联接和投影规则” 页的示例。

查看页面上的默认设置后，单击“ 下一步 ”按钮。

属性流

本指南不会使用任何属性流规则配置。 本部分旨在提供指南中的连续性。

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

验证设置是否与默认值匹配后，单击“ 下一步 ”按钮。

取消设置

本指南不会更改此连接器的默认取消预配设置。 本部分旨在提供指南中的连续性。

下图是 “取消预配 ”页的示例。

验证设置是否与默认值匹配后，单击“ 下一步 ”按钮。

创建完整导入运行配置文件

需要完整导入运行配置文件才能将用户和组标识数据从 CSV 记录导入连接器空间对象。

使用以下步骤创建新的完整导入运行配置文件：

• 返回同步Service Manager。
• 选择 GCSV 管理代理。
• 右键单击它，然后选择 “配置运行配置文件”。
• 单击“ 新建配置文件”。

将显示“配置运行配置文件”窗口。

命名运行配置文件

在“配置文件名称”页中，输入名称“完整导入”

下图是“配置文件”页的示例。

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

指定类型

在“配置步骤”页中，选择“类型： 完整导入”。

连接器筛选在 GCSV 连接器中的运行方式与任何其他 ECMA 连接器相同。

下图是 “连接器筛选器” 页的示例。

验证设置是否与提供的值匹配后，单击“ 下一步 ”按钮。

管理代理配置类型

在“管理代理配置类型”页上，确保选择 O=CSV 分区。

将其余设置保留其默认值。 单击“ 完成” 按钮将创建运行配置文件。

验证结果

本部分详细介绍了验证创建新 GCSV 连接器以及从示例 CSV 文件导入用户和组记录的结果所需的步骤。

运行完全导入

创建运行配置文件后，使用以下步骤运行此新的完整导入运行配置文件：

• 返回同步Service Manager。
• 选择 GCSV 管理代理。
• 右键单击它，然后选择 “运行”。
• 选择“ 完全导入 ”，然后单击“ 确定”。

验证完整导入操作结果

根据示例 CSV 文件的内容，应有 5 (5 个) 添加：

下图是成功导入示例 CSV 文件内容的结果示例：

检查 GCSV 连接器空间

创建运行配置文件后，使用以下步骤运行此新的完整导入运行配置文件：

• 返回同步Service Manager。
• 选择 GCSV 连接器 管理代理。
• 右键单击它，然后选择“搜索连接器空间”。
• 将范围保留为其默认值“子树”，然后单击“搜索”按钮。

下图是将显示的“搜索连接器空间”窗口的示例。

验证用户对象

选择其中一个用户对象进行检查。 下图是用户的 GCSV 连接器空间对象的一个示例：

检查 DisplayName 字段会显示如何正确分析限定字符串。

单击 ProxyAddresses 条目中的按钮会显示多值字符串也已正确解析为单个值：

验证组对象

选择要检查的组对象之一。 下图是组的 GCSV 连接器空间对象的一个示例：

单击 “成员” 条目中的按钮会显示如何正确加载包含 Members 文件的关联记录组文件成员记录作为成员：

验证 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 脚本。 以下部分详细介绍了在以下情况下应注意的一些注意事项：

重要

write-host在 PowerShell 脚本中使用命令将导致脚本执行失败。

示例预导入 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