Windows PowerShell 连接器技术参考

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

• Microsoft Identity Manager 2016 （MIM2016）

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

PowerShell 连接器概述

借助 PowerShell 连接器，可以将同步服务与提供基于 Windows PowerShell API 的外部系统集成。 该连接器在基于调用的可扩展连接管理代理 2 (ECMA2) 框架和 Windows PowerShell 的功能之间架起了一座桥梁。 有关 ECMA 框架的详细信息，请参阅 可扩展连接 2.2 管理代理参考。

先决条件

在使用连接器之前，请确保在同步服务器上具有以下内容：

• Microsoft .NET 4.6.2 Framework 或更高版本
• Windows PowerShell 2.0、3.0 或 4.0

必须将同步服务服务器上的执行策略配置为允许连接器运行 Windows PowerShell 脚本。 除非连接器要运行的脚本已经过数字签名，否则请运行以下命令来配置执行策略：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

部署此连接器需要一个或多个 PowerShell 脚本。 某些 Microsoft 产品可能会提供用于此连接器的脚本，此外还会提供这些脚本的支持声明。 如果要开发自己的脚本以用于此连接器，则需要熟悉 可扩展连接管理代理 API 来开发和维护这些脚本。 如果在生产环境中使用自己的脚本与第三方系统集成，建议与第三方供应商或部署合作伙伴合作，获取此集成的帮助、指导和支持。

创建新的连接器

若要在同步服务中创建 Windows PowerShell 连接器，必须提供一系列 Windows PowerShell 脚本来执行同步服务请求的步骤。 根据连接到的数据源和所需的功能，必须实现的脚本会有所不同。 本部分概述了可以实现的每个脚本，以及何时需要这些脚本。

Windows PowerShell 连接器旨在将每个脚本存储在同步服务数据库中。 虽然可以运行存储在文件系统上的脚本，但可以更轻松地将每个脚本的正文直接插入连接器的配置中。

若要创建 PowerShell 连接器，请在 同步服务 中选择 管理代理 并 创建。 选择 PowerShell（Microsoft） 连接器。

连接性

提供用于连接到远程系统的配置参数。 这些值由同步服务安全地存储，并在运行连接器时提供给 Windows PowerShell 脚本。

可以配置以下连接参数：

连接

通用模块
连接器允许在配置中存储共享的 Windows PowerShell 模块。 当连接器运行脚本时，Windows PowerShell 模块将提取到文件系统，以便每个脚本可以导入它。

对于导入、导出和密码同步脚本，通用模块将提取到连接器的 MAData 文件夹。 对于架构、验证、层次结构和分区发现脚本，公共模块将提取到 %TEMP% 文件夹中。 在这两种情况下，提取的通用模块脚本都根据通用模块脚本名称设置命名。

若要从 MAData 文件夹中加载名为 FIMPowerShellConnectorModule.psm1 的模块，请使用以下语句： Import-Module (Join-Path -Path [Microsoft.MetadirectoryServices.MAUtils]::MAFolder -ChildPath "FIMPowerShellConnectorModule.psm1")

若要从 %TEMP% 文件夹中加载名为 FIMPowerShellConnectorModule.psm1 的模块，请使用以下语句： Import-Module (Join-Path -Path $env:TEMP -ChildPath "FIMPowerShellConnectorModule.psm1")

参数验证
验证脚本是可选的 Windows PowerShell 脚本，可用于确保管理员提供的连接器配置参数有效。 验证服务器、连接凭据和连接参数是验证脚本的常见用法。 在修改以下选项卡和对话框后调用验证脚本：

• 连接性
• 全局参数
• 分区配置

验证脚本从连接器接收以下参数：

验证脚本应将单个 ParameterValidationResult 对象返回到管道。

模式发现
架构发现脚本是必需的。 此脚本返回同步服务在配置属性流规则时使用的对象类型、属性和属性约束。 架构发现脚本在连接器创建期间运行，并填充连接器的架构。 同步服务管理器中的刷新架构操作也会使用它。

架构发现脚本从连接器接收以下参数：

该脚本必须将单个 Schema 对象返回到管道。 Schema 对象由表示对象类型的 SchemaType 对象组成（例如：用户和组）。 SchemaType 对象包含一组 SchemaAttribute 对象，这些对象表示类型的属性（例如：给定的名称、姓氏和邮政地址）。

其他参数
除了标准配置设置外，还可以定义连接器实例特定的其他自定义配置设置。 可以在连接器、分区或运行步骤级别指定这些参数，并从相关的 Windows PowerShell 脚本进行访问。 自定义配置设置可以以纯文本格式存储在同步服务数据库中，也可以加密这些设置。 如果需要，同步服务会自动加密和解密安全配置设置。

若要指定自定义配置设置，请使用逗号分隔每个参数的名称（，）。

若要从脚本访问自定义配置设置，必须在参数名称后加上下划线（_）和参数范围（全局、分区或 RunStep）作为后缀。 例如，若要访问 Global FileName 参数，请使用以下代码片段： $ConfigurationParameters["FileName_Global"].Value

能力

管理代理设计器的功能选项卡定义连接器的行为和功能。 创建连接器后，无法修改此选项卡上所做的选择。 下表列出了功能设置。

全局参数

通过管理代理设计器中的“全局参数”选项卡，可以配置连接器运行的 Windows PowerShell 脚本。 还可以为“连接”选项卡上定义的自定义配置设置配置全局值。

分区发现
分区是一个共享架构中的单独命名空间。 例如，在 Active Directory 中，每个域都是一个林中的分区。 分区是用于导入和导出作的逻辑分组。 导入和导出具有分区作为上下文，并且所有作都在此上下文中发生。 分区应表示 LDAP 中的层次结构。 分区的可分辨名称用于导入，以验证所有返回的对象是否都在分区范围内。 在从 metaverse 到连接器空间的预配过程中，也会使用分区可分辨名称来确定对象在导出过程中应与哪个分区相关联。

分区发现脚本从连接器接收以下参数：

该脚本必须将单个 Partition 对象或 Partition 对象的 List[T] 返回到管道。

层次结构发现
仅当可分辨名称样式功能为 LDAP 时，才会使用层次结构发现脚本。 该脚本用于让您浏览和选择一组容器，以确定它们是否在导入和导出操作的范围内。 该脚本应仅提供一个节点列表，这些节点是提供给脚本的根节点的直接子级。

层次结构发现脚本从连接器接收以下参数：

脚本必须向管道返回单个子 HierarchyNode 对象或子 HierarchyNode 对象的 List[T] 对象。

进口

支持导入作的连接器必须实现三个脚本。

开始导入
开始导入脚本在导入运行步骤的开头运行。 在此步骤中，可以建立与源系统的连接，并在从连接的系统导入数据之前执行准备步骤。

开始导入脚本从连接器接收以下参数：

该脚本必须将单个 OpenImportConnectionResults 对象返回到管道，例如： Write-Output (New-Object Microsoft.MetadirectoryServices.OpenImportConnectionResults)

导入数据
导入数据脚本由连接器调用，直到脚本指示没有要导入的数据。 Windows PowerShell 连接器的页面大小为 9,999 个对象。 如果脚本返回的导入对象超过 9,999 个，则必须支持分页。 连接器公开一个自定义数据属性，你可以用它来存储一个水印，以便每次调用导入数据脚本时，脚本都能从上次中断处继续导入对象。

导入数据脚本从连接器接收以下参数：

导入数据脚本必须将 List[CSEntryChange] 对象写入管道。 此集合由表示要导入的每个对象的 CSEntryChange 属性组成。 在完全导入运行期间，此集合应具有一组完整的 CSEntryChange 对象，这些对象具有每个对象的所有属性。 在增量导入过程中，CSEntryChange 对象应包含要导入的每个对象的属性级增量，或已更改对象的完整表示（替换模式）。

结束导入
在导入运行结束时，将运行 End Import 脚本。 此脚本应执行所需的任何清理任务（例如，关闭与系统的连接并响应故障）。

最终导入脚本从连接器接收以下参数：

该脚本必须将单个 CloseImportConnectionResults 对象返回到管道，例如： Write-Output (New-Object Microsoft.MetadirectoryServices.CloseImportConnectionResults)

出口

与连接器的导入体系结构相同，支持导出的连接器必须实现三个脚本。

开始导出
开始导出脚本在导出运行步骤的开头运行。 在此步骤中，可以建立与源系统的连接，并在将数据导出到连接的系统之前执行任何准备步骤。

开始导出脚本从连接器接收以下参数：

脚本不应将任何输出返回到管道。

导出数据
同步服务会根据需要多次调用导出数据脚本，以处理所有待处理的导出。 如果连接器空间的导出量超过连接器的页面大小，则导出数据脚本可能会多次调用，并且可能为同一对象调用多次。

导出数据脚本从连接器接收以下参数：

导出数据脚本必须将 PutExportEntriesResults 对象返回到管道。 除非发生错误或更改定位点属性，否则此对象不需要包括每个导出连接器的结果信息。 例如，若要将 PutExportEntriesResults 对象返回到管道： Write-Output (New-Object Microsoft.MetadirectoryServices.PutExportEntriesResults)

结束导出
导出运行结束时，运行“结束导出”脚本。 此脚本应执行所需的任何清理任务（例如，关闭与系统的连接并响应故障）。

结束导出脚本从连接器接收以下参数：

脚本不应将任何输出返回到管道。

密码同步

Windows PowerShell 连接器可用作密码更改/重置的目标。

密码脚本从连接器接收以下参数：

密码脚本不应将任何结果返回到 Windows PowerShell 管道。 如果密码脚本中出现错误，脚本应引发以下异常之一，以通知同步服务出现问题：

• PasswordPolicyViolationException – 如果密码不符合连接系统中的密码策略，则引发。
• PasswordIllFormedException – 如果密码不被连接的系统接受，则抛出此异常。
• PasswordExtension – 用于处理密码脚本中的所有其他错误。

示例连接器

有关可用示例连接器的完整概述，请参阅 Windows PowerShell 连接器示例连接器集合。

其他说明

身份模拟的附加配置

授予被模拟的用户在同步服务服务器上的以下权限：

对以下注册表项的读取权限：

• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Software\Microsoft\PowerShell
• HKEY_USERS\[SynchronizationServiceServiceAccountSID]\Environment

若要确定同步服务服务帐户的安全标识符（SID），请运行以下 PowerShell 命令：

$account = New-Object System.Security.Principal.NTAccount "<___domain>\<username>"
$account.Translate([System.Security.Principal.SecurityIdentifier]).Value

对以下文件系统文件夹的读取权限：

• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\ExtensionsCache
• %ProgramFiles%\Microsoft Forefront Identity Manager\2010\Synchronization Service\MaData\{ConnectorName}

将 Windows PowerShell 连接器的名称替换为 {ConnectorName} 占位符。

故障排除

• 有关如何启用日志记录以排查连接器问题的信息，请参阅 如何为连接器启用 ETW 跟踪。