添加“查找”
“查找”是一种只读机制，可用于查询服务，以获得以下拉列表形式显示的值列表。“查找”可以基于表单中已提供的其他信息项。在配置“操作”或“触发器”时，使用“查找”可无需手动输入或记住与第三方帐户资源相关联的值。
在“操作”和“触发器”中使用“查找”。为了显示多个项，“查找”可以使用分页机制。
“查找”支持初始数据筛选。例如，当您在查找字段中键入文本并单击箭头时，会显示包含文本的值列表。
与其他构件不同，“查找”在外部未版本化。每个查找调用都是查找构件中的一个函数。因此，每个连接器都有一个查找构件。
例如，有一个查找操作，如下图所示。通过查找可以从 Gmail 获取用户的电子邮件，且这些值将在“消息 ID”中作为输入显示。之所以能做到这一点，是因为架构指定了查找可用于此字段。
要执行 get-mail-details 操作，您需要电子邮件帐户的 ID。查找脚本使用 Gmail 帐户的身份验证来搜索您帐户中的所有电子邮件。之后，“操作”表单上会显示列表，您可以从中选择适当的 ID 作为“查找”。
要创建新查找，请执行下列操作：
1. 在命令提示符处执行以下命令：
a. cd <user project root directory>
b. flow add lookup
查找的名称就是连接器的名称，且该名称在项目目录中的查找文件夹中创建。
下列选项适用于此命令。
选项 | 说明 | 数据类型 |
|---|---|---|
--version | 显示版本号。 | [布尔型] |
--help | 显示帮助 | [布尔型] |
--parentDir, -d | 项目的父项目录。 | [默认："."] |
--logLevel, -1 | 设置日志级别。 | [默认："info"] |
2. 更新 index.js 文件中的属性。
查找 JavaScript 应导出单一 JavaScript 对象。此对象可以包含任意数量的方法。index.js 文件具有以下结构。
function(input, options, output){
return}
return}
 | 如果外部服务使用的是“连接”，而非 OAuth，则代码可能会有所不同。 |
options 对象提供了使用查找所需的多种实用方法。
validateDependencies(input.<property name>) - 检查输入是否包含指定的属性。
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
有关可在“查找”中使用的 API 的 SDK 信息，请参阅
ThingWorx Flow 连接器 SDK 部分。
下表介绍了如何使用自变量。
自变量 | 用法 |
|---|---|
input | 包含针对查找配置的相关性。 |
options | 提供用于获取身份验证机制 (连接或访问令牌) 和启用分页支持的实用工具方法。 |
output | 需要通过调用以将结果返回 ThingWorx Flow 的回调。它遵循节点的错误优先约定。 结果必须是 JSON 对象的数组。通常，它们是 ID 对和值对。如果添加了动态架构，则也可以添加其他字段。有关详细信息，请参阅“动态架构注入”一节。 结果必须传递给回调 (输出函数)，并且必须是包含 ID 和值的 JSON 对象的数组。 结果应采用以下格式： { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
动态架构注入
如果某项操作有固定的输入和输出架构，则此架构会在构建功能丰富的操作时创建限制。在加载查找或从查找中选择值时，可以根据用户的选择对操作的输入和输出架构进行更新。因此，表单会随着保留当前值的输入架构的更新一并更新。此外，用于下一个操作的映射的输出字段也会进行更新，以匹配更新的输出架构。
可在查找结果处理界面上完成对操作的输入和输出架构的更新。
返回查找的结果时，可以注入动态架构，也可以通过 onSelect 属性 (对于选定的选项) 向查找添加另一个函数。如果在查找加载时注入，则动态架构注入需要所有查找值的架构。
| | 对于某些事物，可能需要通过两次连续查找进行多级注入。多级注入可以附加限制，但不能移除。 |
要添加表单所显示的输入架构，可以将所生成 JSON 的 schema、parent 和 append 属性用于 ID 和 value 旁边的查找。同样，可以使用 outSchema、outAppend 和 outParent 添加输出架构，此输出架构会在连接的操作打开后显示为操作的输出架构。通常，append 或 outAppend 以及 parent 或 outParent 同时使用，在这种情况下，提供的架构会被附加到指定父项来扩展属性。如果未使用 append，则架构将替换为新添加的架构。
parent 或 outParent 属性是对应架构的架构元素 (必须为 object 类型) 的 ID。如果没有 parent 或 outParent 属性，则更新的默认上下文为对应架构的根。架构更新在 parent 或 outParent 对象范围内进行，方法是在没有 append/outAppend 的情况下，将注入架构中提供的属性与现有属性合并，或将其替换为现有属性。
您还可以使用正在注入的输出架构的 userSelected 属性。该属性用于在表单上选择选项时注入默认架构 (值为 false)，并使用子集 (值为 true) 进行替换。如果移除 userSelected = true 属性 (当删除表单的数组元素时)，则架构会恢复为默认值。
例如，对于 OData 连接器，需要设置输入和输出注入架构，如下图所示：
以下是 OData 的输入注入架构：
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
以下是 OData 的输出注入架构：
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
如上面示例所建议的，可通过设置下列属性，将几个参数固定到动态注入输出架构中的映射用户界面上：visible = true。
分页
查找支持分页，即：能够生成多页结果。每次调用都会生成单页结果。在 UI 上，可通过单击列表中的“更多结果”来检索页面。input 和 options 对象包含处理分页的方法和属性。
• options.getNextPage(boolean) - 在分页时用于返回下一页的 URL。要使分页正确工作，必须在 result 对象的“next_page”属性上设置此 URL。如果不返回更多的页面，则将此属性设置为 false。
• options.maxResults - 与分页配合使用，以一次返回最大结果数。
• input.page - 当前页码。
• input.searchById - 按 ID 搜索。
• input.searchByValue - 按值搜索。
如果查找的 searchable 标志设置为 true，则“按 ID 搜索”和“按值搜索”可用。有关查找的示例，请参阅以上各节。这些属性可通过在目标系统中搜索与 ID 或值匹配的项来缩小搜索范围。
| | ID 和值可能会引用目标系统中的不同字段。 |