Workiva Support Center

背景

Chains 通过利用与其集成的系统的 REST API 与各种第三方系统以及 Workiva 平台进行交互。许多 REST API 响应采用 JSON 格式，包括各种 Workiva API。虽然 JSON 响应可能文档齐全且结构一致，但处理这种格式的数据却很困难。JSON 连接器中的 Array to CSV 命令是一种将 JSON 有效负载转换为表格（行和列）格式以便在 Workiva 平台中使用的有效方法。 

本文将探讨如何使用此命令的过滤功能，仅返回 JSON 有效负载中所需的结果。这可能是必要的，因为 REST API 响应通常包含比所需更多的信息，因为有效负载通常由开发人员决定，而端点的最终用户通常无法限制返回数据的范围。 

例如，Workiva Connector 的 列出文件命令 使用 Workiva Wdata API 的 检索文件列表 端点返回与 Wdata 表关联的所有文件的列表。此端点的 JSON 响应包含以下信息：

 [ 
 { 
 "created": "2024-01-24T12:01:53.000Z", 
 "id": "89b34ac927fe499abf944571ded77983", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2024-01.csv", 
 "numRecords": 108808, 
 "originalFileSize": 26226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "updated": "2024-01-24T12:02:03.000Z", 
 "userId": "HzU1OTQwMTMxODMzMTE4NzI", 
 "version": 1 
 },
 { 
 "created": "2023-12-18T15:06:56.000Z", 
 "id": "62f3d0b79b724776a4fae8bf25f711f1", 
 "metadata": { 
 "column1": {}, 
 "column2": {}
 }, 
 "name": "executions_2023-12.csv", 
 "numRecords": 101789, 
 "originalFileSize": 24226080, 
 "status": "IMPORTED", 
 "tableId": "bafe350ebff74a2dbc11262245483dee", 
 "更新时间": "2023-12-18T15:06:56.000Z", 
 "用户 ID": "HzU1OTQwMTMxODMzMTE4NzI", 
 "版本": 1 
 }
]

Array to CSV 命令允许我们仅选择可以从 JSON 响应中检索的字段。例如，我们可以通过在命令的“列”输入部分中指定来选择 id、 name和 status 字段。该命令将从 JSON 响应中提取每个文件的 ID、名称和状态，并为 JSON 响应中的每个文件创建一行。  

继续以上面的“列出文件”示例为例，Workiva 平台中一个常见的用例是需要更新 Wdata 表中的数据（文件）。要导入更新后的数据集（文件），需要从表中删除现有数据集，因为 Wdata 不允许存在多个同名文件。要删除现有文件，需要检索现有文件的 ID 和状态（已暂存或已导入）。 

检索此信息的一种方法是使用 Array to CSV 命令将 List Files JSON 有效负载转换为表格格式。接下来，您可以使用表格转换 智能筛选行 命令来隔离包含文件信息的各个行。然后您可以使用表格转换 提取值 命令来检索文件 ID 和状态。在本文中，我们将这种方法称为传统方法。   

使用过滤器

筛选输入允许对 JSON 响应进行筛选，不仅可以选择要筛选的字段（列），还可以选择要从 JSON 有效负载中检索的项目（行）。这是一个强大的机制，可以选择所需的特定数据，从而提高集成过程的效率。过滤器允许使用 JSON 有效负载中的一个或多个元素 来限制检索的项目（行）数量。 

筛选条件包含 3 个组成部分——元素路径、比较值和运算符。这些判断标准必须得出真或假的结果。当筛选条件返回真值时，根据命令列定义从 JSON 有效负载中提取记录，并在生成的 CSV 输出中创建为一行。例如：

• 文件状态是否等于“已暂存”？

在这个例子中，文件状态是元素路径，等于是运算符，暂存是比较值。JSON 有效负载中任何文件状态为“已暂存”的记录，都会在 CSV 中创建一个行，其中包含命令配置中的列定义。在这个例子中，它们是 ID、名称和状态。

元素路径

要指定过滤器，必须知道元素的路径。例如，在“列出文件”响应中，“状态”元素的路径为：

@。地位

在命令执行期间检索与该元素关联的值。在上面的有效负载示例中，这将是 status 元素的值 IMPORTED 。 

注： 元素路径必须以 和 (@) 符号开头。

比较值

比较值是与元素路径值进行比较的值。比较值可以是命令配置中定义的静态值，也可以是执行时确定的变量值或输出值。  

运算子

操作员确定要执行的评估类型，以筛选数据。 

注意： 元素路径和运算符 之间以及运算符和比较值之间都需要一个空格。

支持的运营商

指定运算符时，必须考虑元素路径存在的值类型。例如，当评估包含文本值的元素时，使用大于 (>) 运算符可能会产生空白输出，因为对文本值进行数值评估是不合逻辑的。

筛选语法及筛选示例

所有筛选条件必须以问号（？）开头，并包含在括号内。  

单一标准

单条件筛选条件采用以下语法：

?(元素路径 运算符 比较值)

?(@.name == "executions_2023-12.csv")

此过滤器返回名称元素等于 executions_2023-12.csv的所有记录。

多准则

多条件筛选器使用以下语法：

?(元素路径 运算符 比较值 逻辑运算符 元素路径 运算符 比较值)

?(@.name == "executions_2023-12.csv" && @.status == "IMPORTED")

此筛选器返回名称元素等于 executions_2023-12.csv 且状态元素等于 IMPORTED的所有记录。

示例命令配置

在本例中，过滤器输入配置为评估 JSON 有效负载中的 name 元素。该筛选器使用年份和月份变量，在本例中，这些变量是运行时输入值。这样，过滤器就可以在链执行时动态地考虑指定的年份和月份。  

过滤器的价值

过滤器允许仅从 JSON 响应中检索所需的行。这可以减小命令生成的输出文件的大小，从而提高链式性能。 

此外，当尝试从 JSON 响应中分离出单行时，可以使用 动态输出 从过滤后的有效负载中提取这些特定值，并使其可用于链的后续节点。 

下面展示了一个动态输出定义示例。

由此产生的链更加精简，只需一个节点（数组到 CSV）即可执行传统方法所需的四个节点的操作。由于执行的命令更少，产生的输出也更小，因此该精简后的链式结构效率更高。