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

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

• Microsoft Identity Manager 2016 （MIM2016）

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

准备示例 CSV 文件

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

将以下 CSV 复制到 C：\GCSV\SCRIPTS 文件夹中：

• 示例用户 CSV 文件 （Users.csv）
• 示例组 CSV 文件（Groups.csv）
• 示例成员 CSV 文件 （Members.csv）

准备示例 PowerShell 脚本

在运行 MIM 同步服务器的服务器上，C：\GCSV\SCRIPTS 创建文件夹，并将示例 PowerShell 脚本复制到 附录 B - 示例 PowerShell 文件 中。 请确保 MIM 同步服务帐户具有适当的 PowerShell ExecutePolicy 权限 才能执行脚本。

将以下 PowerShell 脚本复制到 C：\GCSV\SCRIPTS 文件夹中：

• 示例预导入脚本 （Pre-Import.ps1）
• 导入后脚本示例 （Post-Import.ps1）
• 示例预导出脚本 （Pre-Export.ps1）
• 导出后脚本示例 （Post-Export.ps1）

创建新连接器

以下列表简要概述了本指南中概述的步骤。 为此，需要使用具有 MIM 同步管理员角色的帐户来执行以下任务：

• 从 MIM 同步服务管理器打开 创建新的管理代理（MA） 窗口。
• 选择 通用 CSV 连接器 作为连接器类型。
• 提供要导入或导出的 CSV 文件的文件路径和名称。
• 指定 CSV 文件的文件编码、值分隔符、多值分隔符和文本限定符。
• 选择是否将第一行中的值用作标题字段。
• 选择要从 CSV 文件导入或导出的对象类型和属性。
• 为 MA 配置分区、运行配置文件和映射详细信息。
• 提供 PowerShell 脚本的脚本路径和参数（如果有）。
• 运行 MA 以执行导入、同步或导出操作。
• 评估结果。

让我们开始吧！

若要创建通用 CSV 连接器，MIM Synchronization Service Manager 选择 管理代理，创建。 选择通用 CSV (Microsoft) 连接器。

提供连接器的名称（例如：通用 CSV），然后单击 “下一步” 按钮。

连接

“连接”页包含连接器可以找到用户、组和组成员 CSV 文件的文件路径。

图是连接页面的示例：

下面是此页设置所需提供的值列表：

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

能力

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

下图是功能页面的示例：

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

查看有关的配置后，单击下一步按钮。

模式 1 （CSV 文件格式配置）

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

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

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

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

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

架构 2（标识和引用字段配置）

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

在此页面上，为“连接”页面列出的每个 CSV 文件配置锚点属性。

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

下表是应分配给此页面上每个设置的单个值：

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

架构 3 （用户文件属性架构配置）

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

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

下表列出了应分配给此页面每个设置的具体数值：

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

架构 4 （组文件属性架构配置）

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

下图是 架构 4（组文件属性架构配置）页的示例。

下表是应分配给此页面上每个设置的单个值：

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

全局参数 （PowerShell 脚本配置）

此页面允许配置在导入和/或导出操作之前和/或之后运行的 PowerShell 脚本。 此输入参数的值为对您的身份用户和组记录执行各种预处理和后处理操作提供了机会。

下图是 全局参数 页的示例。

下表是应分配给此页面上每个设置的单个值：

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

PowerShell 脚本执行

GCSV 连接器在其自己的会话中运行每个配置的 PowerShell 脚本，并且不支持在脚本执行之间传递变量。

此外，GCSV 连接器在文件中执行 PowerShell 脚本，而不是 cmdlet。 这意味着输入参数不能通过将它们添加到其路径语句的末尾来传递到脚本中。 执行此作会导致脚本的执行失败。

如果预导入或导出脚本执行引发异常，以防止导入或导出不当处理的用户或组记录，GCSV 连接器将中止并停止整个运行配置文件的执行。

同样，如果导入后或导出后的操作遇到异常，则会导致操作状态失败。

PowerShell 脚本执行期间遇到的错误将记录到 MIM 同步服务器的 *事件日志中。

PowerShell 输入参数：OperationType

尽管不支持使用输入参数，但 GCSV 连接器确实将一个输入参数传递给每个 PowerShell 脚本的执行：OperationType。

输入变量 OperationType 将具有 完整 或 Delta 的值，以显示与脚本一起运行的操作类型（例如，完全导入、增量导入、完整导出、(Delta) 导出）。 此值允许脚本检查它们是在完整还是增量导入/导出上下文中运行，并相应地执行其预处理或后处理任务。

预配层次结构

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

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

“配置层次结构”页的

在确认设置与所提供的值匹配后，单击 “下一步” 按钮。

分区和层次结构

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

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

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

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

对象类型

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

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

“对象类型”页

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

属性

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

下图是 属性 页的示例。

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

定位点

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

下图是定位点页面的示例。

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

连接器筛选器

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

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

“连接器筛选器”页的屏幕截图

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

联接和投影规则

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

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

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

属性流

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

下图是 属性流 页的示例。

的屏幕截图

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

取消设置

在本指南中，我们不会更改此连接器的默认取消预配设置。 本部分介绍如何在指南中提供连续性。

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

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

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

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

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

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

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

命名运行配置文件

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

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

在确认设置与提供的值匹配后，单击 “下一步” 按钮。

指定类型

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

连接器筛选在 GCSV 连接器中与任何其他 ECMA 连接器中的操作相同。

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

的屏幕截图

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

管理代理配置类型

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

的屏幕截图

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

验证结果

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

运行完全导入

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

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

验证完整导入操作结果

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

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

检查 GCSV 连接器空间

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

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

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

验证用户对象

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

验证用户对象页 1屏幕截图

查看 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 输入参数获取这些值，该参数指示脚本是在完全操作还是增量操作期间运行。

附录 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 脚本

在连接器的配置中，本指南假定 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