配置集成
现在您已添加 HTTP 集成,请配置您的集成。此端点数据以及服务操作配置构成了创建可操作微应用的基础。
添加数据端点
配置数据端点以将相关数据读入缓存中。我们要向用户显示的任何数据(或想要触发事件或操作)都必须被缓存。
要添加数据端点,请执行以下步骤:
-
选择数据加载。
- 在数据端点配置下,输入端点名称。
-
(可选)如有必要,添加模板变量。此字段提供在 HTTP 请求定义中使用的动态值。使用模板变量,您可以在以下任一项中覆盖或更改原始终端节点定义的所有参数:
- 操作前或后动作更新
- 动作调用
- 增量同步
例如,您可能希望在增量同步期间使用模板变量的动态值。
- 选择添加变量。
- 输入新变量的名称。
-
选择数据类型和源。选择的数据类型决定了源的选项。
- 在 DATETIME 数据类型下,对于静态值,请输入值。
- 在 DDATETIME 数据类型下,对于相对日期,请选择一个时间段。
- 如有必要,选择配置菜单,然后输入日期时间的格式类型详细信息。
- 选择保存。
您创建的新变量现在可以在 HTTP 请求中使用。当您在胡子标签之间输入变量时,如果输入的变量不存在,则会警告您该变量不存在。如果将鼠标悬停在该变量上,弹出窗口允许您通过选择创建变量来添加此变量。
注意:
配置模板变量后,必须定义请求方法、分页类型,并测试完全同步和增量同步部分的服务,如下所述。
-
配置请求方法 和 URL。
-
(可选)选择 + 添加参数,然后根据需要配置查询、标头或请求正文参数。
注意:
您选择的数据类型决定了属性的格式。格式确定微应用中的字段。使用胡子标记引用参数名称。例如 。
-
选择分页类型。您必须选择的分页类型取决于目标应用程序集成的 API 标准。请查阅目标应用程序集成的 API 文档,了解您的应用程序集成使用的分页方法。
通过我们的 HTTP 集成,您可以从以下标准分页方法中进行选择。页面、偏移和光标方法包含一个字段页面大小值,该值定义了每页要提取的记录数。
- 无 -未定义分页。
-
页面 -设置每页返回的限制。
示例:
https://example.com?limit=100&page=3
-
偏移 -提供两个参数:偏移和限制。偏移量定义要跳过的记录数,限制每页显示的记录数。
示例:
https://example.com?limit=100&offset=300
-
链接 -定义分页方法以定义正文中的下一页链接。
示例:
{ “data”[…] “next”: https://example.com?lpage=3 }
-
标题链接 -类似于链接分页,但根据 URL 页面标题定义分页。
示例:
链接:<https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next", <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
-
游标 -光标分页使用特定记录的唯一标识符,该标识符用作指向要查询的下一条记录的指针,以返回结果页。
示例:
https://example.com?paginationToken=BFLMPSVZ
-
OData -选择您的 OData 版本以执行 OData 标准分页。
- 选择使用参数测试以检查终端节点是否配置正确。选择要测试的页数,然后选择测试服务。选择完成以关闭刀片式服务器。
- (可选)如果需要,请切换分页边界以定义返回记录的条件。这仅适用于页面和偏移分页类型,并取决于目标 SoR 要求。
- 设置要加载的最大页数变量(默认值为 1000,范围为 1 到 100000)。在需要时,使用此变量可以限制从 SoR 返回的记录量。这可以为每个终端节点单独配置。
-
选择测试服务以检查您的端点是否正确配置。
如果测试成功,请继续执行下一步。如果您收到错误消息,请根据您收到的错误消息进行故障排除。
脚本转换
有关配置脚本转换的更多信息,请参阅 脚本转换。
获取数据结构
现在,您可以在获取数据结构部分创建表。
- 选择生成表。
-
从 API 或从 JSON 中选择:
- 从 API - 从定义的端点自动获取数据。
- 从 JSON -如有必要,使用从示例 JSON 粘贴 API,例如,您有响应,但现在不能调用 API。 (可选)如果从定义的端点需要备用根目录,则定义根路径。根路径必须用 JSON 指针表示法定义。
- 选择生成表。
-
要设置主键,请选择编辑属性铅笔图标,然后切换要用作主键的属性的主键(例如 id)。重要的是,主键列不能包含空值。不要将数据类型更改为时间戳。
注意:
创建自定义集成和微应用时,必须始终分配主键以启用正确的增量加载,而不是在同步数据时完全覆盖。
-
(可选)选择“添加表”并根据所需目标应用程序的需要配置额外的表属性,然后单击“保存”。然后,您可以从 API 端点重新加载表结构。
-
增量同步
随着增量同步切换,您可以设置同步。也就是说,以更频繁的时间间隔下载自上次数据同步以来的更新记录。要执行此操作,请配置 API 调用的执行频率。至少输入一个服务器时间参数。在不设置同步计划的情况下离开会将同步设置为手动。
仅当目标应用程序需要自定义参数时,才需要这些参数。根据需要,请参阅目标应用程序集成文档。如果创建用于同步的自定义字符串,则必须在方括号中输入。例如“[updated >=]YYY-MM-DD HHmm”。
有关同步的详细信息,请参阅下面的设置数据同步。
- 在提取数据结构部分输入已创建表的基本名称,然后选择:
- 从 API - 从定义的端点自动获取数据。
- 从示例 JSON -在必要时粘贴 API 时使用从示例 JSON,例如,您有响应,但现在不能调用 API。
- 选择添加。
您的数据端点已映射,您现在可以设置服务操作。
注意:
设置和添加端点后,您的表结构将被锁定。如果需要重构,则必须创建和配置新的数据加载端点。
添加其他 API 调用
为应用程序集成配置数据端点时,您可以向原始父端点添加额外的子端点以启用调用链接。设置数据端点后,您可以添加更多关联的端点。
请按照以下步骤进行操作:
-
在要向其添加子呼叫的集成菜单上选择编辑。
此时将打开集成页面。
-
从“要添加的数据端点”菜单中选择添加子 API 调用:
-
选择父表并定义端点,就像您在上面“数据加载”部分中的步骤中所做的那样。
定义请求方法时,您可以将路径设置为静态值或列值。 您的 API 调用链现在已与父 API 调用相关联。您定义的父/子端点现在可以在“数据端点”页面中显示。
注意:
创建集成时,建议仅从一个端点加载数据,而不是多个端点加载数据。尽可能倾向于批量调用而不是单个终端节点调用。
合并表
配置子 API 调用时,您可以选择以下选项之一将子表与父表合并:
如果不想合并父表和子表,请选择不合并。
选择“合并为详细信息”以从记录系统中获取所有任务和请求以及请求中的每个请求详细信息,然后合并这些任务和请求,例如,如果父表和子表是:
/request-list
{
“id”: 123,
“Title”:“Car”,
“Role”:“Order”,
“Category”:“Sales”
}
以及:
/request-detail/123
{
“id”: 123,
“Title”:“Car”,
“Desc”:“Cabriolet”,
“Date”:“2020-01-01”
}
如果选择了合并为详细信息后返回下表:
ID | 标题 | 角色 | 类别 | 说明 | 日期 |
---|---|---|---|---|---|
123 | 车载电话 | 命令 | 销售 | Cabriolet | 2020-01-01 |
选择合并为子列表,将每个子表单独附加到父表中。使用上面的示例,合并为子列表会产生以下结果:
ID | 标题 | 角色 | 类别 | ID | 标题 | Desc | 日期 |
---|---|---|---|---|---|---|---|
123 | 车载电话 | 命令 | 销售 | 123 | 车载电话 | Cabriolet | 2020-01-01 |
配置表
您可以在不设置新配置的情况下重新配置表主键。您可以通过删除表屏幕中的单个表条目、重新同步表并选择新主键来执行此操作。
支持的时间格式
HTTP 集成支持记录数据系统的以下时间格式:
- ISO 日期格式
- OData 格式
"yyyy-M-dd HH:mm:ss.SSS",
"M/d/yy h:mm a",
"M/d/yyyy h:mm:ss a",
"dd/MM/yy HH:mm",
"MMM d, yyyy h:mm:ss a",
"dd-MMM-yyyy HH:mm:ss",
"MMMM d, yyyy h:mm:ss a",
"dd MMMM yyyy HH:mm:ss",
"EEEE, MMMM d, yyyy h:mm:ss a",
"EEEE, d MMMM yyyy HH:mm:ss 'o''clock'",
"h:mm a",
"HH:mm",
"h:mm:ss a",
"HH:mm:ss"
添加服务操作
配置 HTTP 集成后,您可以配置服务操作。使用服务操作,您可以在应用程序集成的记录系统上配置回写操作。您可以使用与上述数据端点类似的方式配置服务操作。由于您的应用程序集成可以是任意数量的定制组合,我们将采用一种通用方法来解释服务操作的工作原理。
若要添加服务操作,请按照下列步骤操作:
- 在应用程序名称下选择您创建的集成。
- 选择服务操作和添加新服务操作。
- 为其指定一个操作名称(例如“获取 JIRA 票证信息”)并输入端点 URI 路径:(/rest/api/2/issue/)
-
根据应用程序集成的 API 要求配置请求方法。
注意:
使用胡子标记引用参数名称。例如 。
- 选择添加以保存服务操作。您现在可以根据需要添加额外的服务操作。
API 请求方法
现在,您可以根据应用程序集成 API 要求配置请求方法,使用以下组件:
- GET -在不修改的情况下从应用程序集成 SOR 中检索资源。
- POST -在应用程序集成 SOR 中创建新资源。
- PUT - 在应用程序集成中更新现有资源。
- PATCH -对资源进行部分更新。
- DELETE -删除资源。
使用以下可配置 API 参数:
- 标题 -定义请求标头中包含的参数,通常与授权相关。
- 路径 -在端点路径中定义查询字符串之前的参数。
- 查询 -在端点的查询字符串中定义参数。
- 正文 -定义请求正文中包含的参数。
脚本转换
有关配置脚本转换的更多信息,请参阅 脚本转换。
执行操作前的数据更新
(可选)在执行操作之前配置数据更新,以确保您的微应用最终用户在执行操作时完全同步您的数据。例如,您希望确保可操作微应用程序上显示的金额是要批准的正确金额,并且在创建和批准之间的时间内尚未更新该数量。
重要:
此操作执行前的数据更新功能仅适用于文本组件。这意味着在执行操作之前的其他数据更改不会向最终用户显示。同样,如果为文本组件的页面逻辑输入了值,则不会运行检查。如果 Workspace 用户正在进行并发修改,则不会出现警告。
若要在执行之前设置数据更新,请按照下列步骤操作:
- 选择要从中获取更新记录的现有数据端点。
- (可选)仅当需要子数据端点才能获取更新记录的完整详细信息时,启用包括子端点。
- (可选)如果允许更新获取单个记录,则扩展原始端点 URI。例如,如果数据端点 URI
https://domain/api/items
更新为https://domain/api/items/itemId
。新终端 URI 必须返回与原始终端结构相同的数据结构,否则数据解析将失败。
注意:
如果终端配置在此初始设置之后发生了更改,则不会自动在此传播更改。
- (可选)如果启用对单个记录的筛选,则使用添加附加参数扩展原始请求参数。
-
选择使用参数测试以检查终端节点是否配置正确。选择要测试的页数,然后选择测试服务。选择完成以关闭刀片式服务器。
如果测试成功,请继续执行下一步。如果您收到错误消息,请根据您收到的错误消息进行故障排除。
完成配置后,选择“保存”。
操作执行后的数据更新
(可选)为确保数据在执行操作后完全同步,您可以配置数据更新以从目标应用程序记录系统中获取新数据。
若要在执行后设置数据更新,请按照下列步骤操作:
- 选择要从中获取更新记录的现有数据端点。
- (可选)仅当需要子数据端点才能获取更新记录的完整详细信息时,启用包括子端点。
- (可选)如果允许更新获取单个记录,则扩展原始端点 URI。例如,如果数据端点 URI
https://domain/api/items
更新为https://domain/api/items/itemId
。新终端 URI 必须返回与原始终端结构相同的数据结构,否则数据解析将失败。 -
(可选)如果启用对单个记录的筛选,则使用添加附加参数扩展原始请求参数。
-
选择使用参数测试以检查终端节点是否配置正确。选择要测试的页数,然后选择测试服务。选择完成以关闭刀片式服务器。
如果测试成功,请继续执行下一步。如果您收到错误消息,请根据您收到的错误消息进行故障排除。
完成配置后,选择“保存”。
验证所需实体
使用表验证存储在缓存中的表的当前列表以及应用于这些表的过滤器。
现在,除非需要创建自定义关系,否则您可以设置和运行第一个数据同步。有关详细信息,请参阅设置数据同步。
创建自定义关系
使用关系页面在集成中的表之间创建自定义连接。如果您有多个基本 URL 并且需要多个集成,或者如果您想在同一集成中创建自定义关系,则可以使用此选项。这是一个高级用例,我们建议您在开始映射多个集成之前熟悉在单个集成上创建微应用。
- 在“管理微应用”页面中,选择要验证其实体的集成旁边的菜单。
- 选择编辑,然后选择关系。
-
选择添加新关系。
此时将打开“添加关系”页面。
- 您可以将主表映射到外表。
- 输入您想要拥有的别名。
现在,您可以根据您在每个集成上设置的主键映射和添加其他参考列。
重要:
如果删除表,所有关系也会被删除。
设置数据同步
将集成应用程序中的数据提取到 微应用平台,以便与缓存进行比较。作为最佳做法,每 24 小时执行一次完全同步,并且可以将增量同步配置为每五分钟进行一次。
有关同步规则、不符合其计划的同步以及否决规则的完整信息,请参阅 同步数据。
- 在“管理微应用”页面中,选择要为其设置同步的集成旁边的菜单。
-
选择同步。
-
设置完全数据同步值和增量数据同步值。
-
完全删除本地缓存并从源系统中提取所有数据。
重要:
运行完全同步可能需要很长时间。我们建议在夜间或通常在非工作时间运行完全同步。您可以通过选择 X 图标随时取消正在进行的数据同步。
-
增量 提取仅更改(新的和更新的)记录。不加载已删除的数据。
重要:
并非所有 API 都支持增量同步。
定义每日或每周同步时,同步会在您选择的时间段内随机进行。例如,选择 00-04 每日完全同步将在该时段内随机选择的时间运行完全同步。
-
- 选择保存。
注意:
如有必要,您还可以选择箭头图标以按需运行集成。
显示集成日志
使用集成日志查看按严重性分类的更改历史记录。使用此功能可对集成问题进行故障排除。例如,如果您看到同步失败,请检查集成日志以了解原因。或者,如果预期的卡片未显示,请检查集成日志以查看是否进行同步。
- 在“管理微应用”页面中,选择要查看集成日志的集成旁边的菜单。
- 选择集成日志。
- 查看条目,并根据需要选择菜单以按“错误”进行筛选。
导出集成配置
您可以导出集成配置。所有凭据都将被丢弃。这包括密码和客户端详细信息。仅导出存储在 微应用服务器中的配置。例如,导出会保留您的用户名而不是密码,并且导出会保留您的 OAuth 配置,但不保留客户端密钥。
- 在“管理微应用”页面中,选择要导出的集成旁边的菜单。
-
选择导出配置。
service.mapp 文件下载。
下一步的去向
既然您已经创建并配置了自定义集成,就可以构建自己的微应用,以提供满足您需求并简化日常工作流程的最佳终用户体验。有关详细信息,请参阅创建微应用。