入站Webhook可实现数据从自定义应用程序向ADManager Plus的传输。配置时需在"端点设置"和"响应设置"部分填写必要信息。
端点设置
- 在入站Webhook下的 API端点配置中，点击端点设置以提供下列端点详情。如有需要，可通过+添加API端点按钮为自定义应用配置多个端点。
- 端点URL：输入端点URL。该URL将根据需执行的操作及从应用程序获取的数据类型而变化。
- 例如：获取用户数据的端点URL与获取组数据的URL不同。请参考您与ADManager Plus集成的应用程序的API文档。
- 方法：选择HTTP请求方法（GET或POST）。
- 标头：点击并配置相应的HTTP标头。
- 参数：点击并配置查询参数。
- 正文消息：根据API类型从可用选项中选择正文消息数据类型：
- 要上传 CSV 文件，请在XML 路径文件字段下点击CSV 导入，上传 CSV 文件并从 XML 响应中提取所需数据。
- 点击测试并保存。
注意：请按以下步骤配置高级设置。
响应设置
- 在响应设置部分：
- 响应超时：设置等待API响应的最大时长。
在响应超时字段中以毫秒为单位指定最大等待时间。
- 响应类型：选择响应返回的格式。在响应类型字段中选择JSON或XML。默认设置为JSON，但可根据API要求更改为XML。
- 重复调用设置：配置这些设置以处理对该端点的重复调用时的分页功能。
- 重复调用此端点：
启用“重复调用此端点”开关，配置持续运行直至从集成应用程序获取全部数据的条件。
- 重复调用配置：定义重复请求的触发机制，确保从集成应用程序完整获取数据。
从第一个下拉列表中选择操作类型。在相邻下拉框中填写分页参数，以便按顺序获取数据集直至完整数据集被提取。在值字段中输入分页参数的具体数值。
- 重复调用条件：
您还可通过"重复调用条件"选项设置等待API响应的时限。
- 响应处理器：响应处理器设置允许您定义如何处理和自定义端点的响应。
设置完成后，点击"保存"或
" 测试并保存"。响应窗口将显示所有请求的元素。
- 点击数据源 - LDAP属性映射，匹配 端点并将AD LDAP属性映射至自定义应用程序的对应属性。
- 输入配置名称和描述，并 从下拉菜单中选择自动化类别。
- 在"选择端点"字段勾 选自定义应用程序的端点框，并在主键下拉菜单中选择用户唯一标识属性（员工ID、用户名等），该属性在所有端点中需保持相同值。若已配置从属端点，则需为这些端点同样选择唯一属性。
- 在属性映射字段中，从LDAP属性名称下拉菜单选择属性，并将其映射至自定义应用程序的对应属性。
注意：
- 点击"添加新格式"为自定义应用程序的用户命名属性创建新格式。在弹出的"自定义命名格式"窗口中填写详细信息并点击"保存"。必要时可在指定格式值时添加宏。
- 以下自定义属性可在映射过程中使用，并支持所有外部数据源集成及CSV集成：
- templateName：指定可用于创建用户、计算机、组和联系人以及修改用户的模板名称。
- executionTime：指定非模板化操作中每个对象的执行时间。
- 点击保存。
如何使用入站Webhook
配置入站Webhook后，可在ADManager Plus的计划自动化中将其作为数据源执行各类身份管理操作。操作路径：进入自动化 管理，点击+创建新自动化，在选择对象部分使用"选择更多"选项。此功能可对通过入站Webhook导入的对象列表执行单次或周期性自动化操作。
入站webhook嵌套端点的进阶配置
某些API配置中可能需要设置多个相互依赖的端点。例如：首个端点获取组织内所有员工ID，随后需针对响应中每个员工ID调用另一个API以获取员工详细信息。 此类场景下，请将首个API配置为基础端点（默认类型），并通过"端点配置"部分的高级选项将第二个端点设为依赖端点。
配置依赖端点的步骤
在API 端点配置下切换“高级”按钮至开启状态，当端点依赖于前一个 API 端点时填写相关信息。
- 在端点配置部分，启用高级选项以填写端点依赖于先前API端点时的相关信息。
- 从"配置类型"下拉菜单中选择端点类型。默认选中"基础端点"选项，需将其更改为"依赖端点"。
- 从"依赖于"下拉菜单中选择相关基础端点，该端点数据将为依赖端点提供支持。因此，基础端点返回的每个对象都将触发依赖端点的调用。
- 若需使用基础端点响应中的字段，请输入%调用基础端点宏列表，或点击
。
基于条件从REST API响应中提取值的步骤
遵循"入站webhook配置"章节所述全部步骤。当消息类型设置为JSON且需根据特定条件从响应数组中提取数据时，ADManager Plus支持通过JSON条件解析实现此功能。
此功能可从API的JSON响应中筛选所需数据，该响应包含目标键值的数组，随后可映射至对应的LDAP属性。映射格式可根据需求配置为单条件或多条件。
条件语法
使用以下格式定义条件：
<数组对象键路径>[?(('<条件键路径>')='<条件值>')].<待获取值路径>
<数组对象键路径>[?(('<条件键路径>')='<条件值>')&(('<条件键路径>')='<条件值>')].<待获取值路径>
语法参数
| <数组对象键的路径> |
JSON数组对象的路径，以键值结尾 |
| <条件路径 key > |
数组对象中用于条件的键的路径 |
| <条件值> |
条件路径中待匹配的值 |
| <待获取值的路径> |
需要获取的值的路径（位于数组对象之后） |
示例 JSON 响应：
{
"data": [
{
"id": 443,
"name": "TestUser",
"employee_id": 443,
"address": [
{
"职位": {
"城市": {
"名称": "城市名1",
"是否住宅": "false"
},
"电话": {
"号码": 999888777,
"是否住宅": "true"
}
}
},
{
"position": {
"city": {
"name": "cityname2",
"isHome": "true"
},
"phone": {
"number": 5556666444,
"isHome": "false"
}
}
}
],
"items": [
{
"category": "department",
"reference": "department_reference",
"data": [
{
"value": "teamname1",
"type": "primary"
},
{
"value": "teamname2",
"type": "secondary",
"details": [
{
"id": "oldteamid",
"type": "old"
},
{
"id": "newteamid",
"type": "new"
}
]
}
]
},
{
"category": "group",
"reference": "group_reference",
"data": [
{
"value": "groupname1",
"type": "primary"
},
{
"value": "groupname2",
"type": "secondary",
"details": [
{
"id": "oldgroupid",
"type": "old"
},
{
"id": "newgroupid",
"type": "new"
}
]
}
]
}
]
}
]
}
类型 1：基于单一条件的映射
根据单一条件从 JSON 数组中检索值。当需要从数据集中筛选并提取仅满足单一匹配条件的特定信息时，此方法非常有用。该条件作为简单过滤器，确保仅选取数组中相关的对象。
示例：要从 示例响应中 获取cityname2 值，需将条件路径data[].address[].position.city. isHome设为true，并将目标数组路径设为data[].address[].position.city.name。
语法：data[].address[?(('position.city.isHome')='true')].position.city.name
说明：
- data[].address：此为JSON数组对象的路径。
- position.city.isHome：这是数组data[].address内部的条件键路径。
- true：匹配条件值。
- position.city.name：此为需获取的值路径。
输出：该条件匹配数组中的第二个项，因此返回值为cityname2。
类型2：多条件映射
通过应用多重条件从JSON数组中检索值并映射至LDAP属性。此方法适用于复杂或嵌套数据场景，需满足多重条件才能精确映射值至LDAP属性。通过逻辑与(&)或或(|)运算符组合条件，可筛选出满足所有指定条件的对象。
示例： 从 示例响应中 获取值groupname2， 需设置条件路径data[].items[].category = 'group' 且 data[].items[].data[].type = 'secondary'，并将目标 数组路径设为data[].items[].data[].value。
语法：data [].items[?(('category')='group')&(('data[].type')='secondary')].data[].value
说明：
- data[].items：这是 JSON 数组对象的路径。
- category：这是 data[].items 数组中的第一个条件键路径。
- group：这是要匹配的第一个条件值。
- data[].type：这是data[].items内部的第二个条件键路径。
- secondary：这是要匹配的第二个条件值。
- data[].value：这是要获取的值路径。
输出：该条件匹配数组中的第二个项，因此返回值为groupname2。
注：
如何在ADManager Plus中配置基于条件的解析
在 ADManager Plus 中，基于条件的解析可通过两种方式配置。 方法1（推荐）提供更高灵活性：可为同一JSON数组定义多个带不同条件的格式映射，并在LDAP属性间复用。方法2则直接在终端节点配置，每个JSON数组路径仅允许设置一个条件，且仅能从数组中提取单个值。此方法限制更严格但配置更简单。
方法1：[推荐]
- 在数据源 - LDAP 属性映射部分，选择端点。
- 在“属性映射”字段的下拉菜单中选择“添加新格式”。
- 在格式映射属性弹窗中，输入格式名称并选择格式。
- 在格式值字段中，点击宏图标 。
- 在“选择宏”弹出窗口 中，导航至“函数”> “匹配条件”。
- 在文本框中输入条件值。
- 点击添加。
- 点击保存。
- 现在，您可以使用此格式映射任何LDAP属性。
注意：使用此方法时，可为每个需要映射的LDAP属性创建多个格式。
方法 2：
- 填写端点配置详情后，点击测试并保存或选择响应字段图标。
- 单击任何数据类型字段以打开下拉菜单，然后选择“数组”。
- 在文本框中输入条件值。
- 点击保存。
- 现在，您可以使用此列映射任何 LDAP 属性。
配置SOAP API端点的步骤
除以下步骤外，需遵循入站Webhook配置部分的所有步骤。当消息类型设置为XML时，ADManager Plus需要响应解析器CSV文件。该文件可帮助从端点的XML响应中过滤所需数据，随后将过滤后的属性关联至AD LDAP属性。
CSV文件应包含如下三列：
- columnName：这是从 XML 响应中过滤数据所需的名称。
- xPath：这是数据将被获取的位置。
- isParameter：若设置为1，则在重复调用时将成为迭代属性。例如，若消息主体中名为Page的节点需在每次调用时递增1，则Page的isParameter需设为1。
例如，如下图所示，示例CSV文件中突出显示的columnName Worker ID值，是从示例XML响应中突出显示的属性Worker_ID(值:100001)提取的。该值后续可映射至ADLDAP属性employeeID。
示例CSV文件：
示例XML响应：
点击此处下载示例CSV文件。
基于值的索引
基于值的索引是一种通过对数据值应用特定条件来高效定位和检索数据的技术。该方法允许用户创建特定的xPath表达式，从而高效查找符合定义条件的条目。
如下方图片所示，示例CSV文件中Company列的值取自Organization_Name属性（值：company1），该属性在第二张图片中被高亮显示。 由于存在多个Worker__Organization_Data条目，需添加附加条件（Organization_Subtype_ID='company'）以指定正确的Worker_Organization_Data。这意味着最终值是基于与另一个特定值关联的条件选取的。
该xPath通过检查Organization_Subtype_ID是否等于Company来过滤Worker_Organization_Data下的数据，随后返回匹配条件的组织名称。
创建条件的步骤如下：
- 指定要过滤的数据字段（例如 Organization_Subtype_ID）。
- 指定匹配值（例如：Company）。
- 应用条件格式 [?(searchpath = 'value') ] 基于选定属性进行过滤。
此方法可基于定义条件创建精确的xPath并生成结果。
