Workiva 支援中心

背景

Chains 通过利用与其集成的系统的 REST API 与各种第三方系统以及 Workiva 平台进行交互。  許多 REST API 回應都是 JSON 格式，包括各種Workiva API 。  雖然 JSON 回應可能有良好的文件記錄和一致的結構，但很難使用此格式的資料。  JSON Connector 中的Array to CSV 命令是一種有用的方法，可將 JSON 有效載荷轉換為表格（行與列）格式，以便在 Workiva 平台中使用。 

在本文中，我們將探討如何使用此 Command 的過濾功能，從 JSON 有效負載中只傳回所需的結果。  這可能是必要的，因為 REST API 回應所包含的資訊通常超過所需，因為有效負載通常由開發人員決定，而且端點的終端使用者通常無法限制回傳資料的範圍。 

例如，Workiva Connector 的List Files 命令 使用 Workiva Wdata API 的Retrieve a List of Files 端点返回与 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",
 "updated":"2023-12-18T15:06:56.000Z",
 "userId":"HzU1OTQwMTMxODMzMTE4NzI",
 "version"：1
 }
]

Array to CSV 指令允許我們只選擇要從 JSON 回應中擷取的欄位。  例如，我們可以選擇選擇id,name, 和status 欄位，方法是在 Command 的 Columns 輸入部分指定這些欄位。  该命令将从 JSON 响应中提取每个文件 ID、名称和状态，并为 JSON 响应中的每个文件创建一行。  

繼續上面的列表檔案範例，Workiva 平台中的常見用例是需要更新 Wdata 表中的資料 (檔案)。  若要匯入更新的資料集（檔案），需要從表中移除現有的資料集，因為 Wdata 不允許使用相同名稱的多個檔案。  要完成刪除現有檔案，需要擷取現有檔案的 ID 和狀態 (Staged 或 Imported)。 

擷取此資訊的一種方法是使用 Array to CSV Command 將 List Files JSON 有效負載轉換為表格格式。  接下來，您將使用表格轉換Smart Filter Rows Command 來隔離具有檔案資訊的個別行。  然後使用表格轉換Extract Value 指令擷取檔案 ID 和狀態。  在本文中，我們稱此為傳統方法。   

使用篩選器

篩選器 (Filter) 輸入允許篩選 JSON 回應，不僅可篩選要選擇的欄位 (列)，還可篩選將從 JSON 有效負載擷取的項目 (行)。  這是一種強大的機制，可選擇所需的特定資料，從而提高整合流程的效率。  篩選條件允許一個或多個元素，在 的 JSON 有效負載中，用來限制擷取的項目（行）數量。 

篩選條件包含 3 個元件 - 元素路徑、比較值和運算元。  條件必須解析為 true 或 false 值。  當篩選條件返回真值時，會根據 Command Columns 定義從 JSON 付載中擷取記錄，並在結果 CSV 輸出中建立為一列。例如：

• 檔案狀態是否等於 Staged？

在此範例中，file status 是元素路徑，equal 是運算符號，Staged 是比較值。  JSON 付載中檔案狀態為 Staged 的任何記錄，都會在 CSV 中建立一列，其中包含命令組態中的列定義。  在本範例中，它們是 ID、名稱和狀態。

元素路徑

要指定過濾器，必須知道元素的路徑。  例如，在 List Files 回應中，Status 元素的路徑是：

@.status

與元素相關的值會在執行 Command 時擷取。  在上面的有效負載範例中，這將是status元素的值IMPORTED。 

注意： 元素路徑必須以 (@) 符號的開始。

比較值

比較值是比較元素路徑值的對照值。  比較值可以是指令組態中定義的靜態值，也可以使用執行時決定的變數或輸出 值。  

運算子

運算符號決定篩選資料時將執行的評估類型。 

注意： 元素路徑和運算符之間需要空格，運算符和比較值之間也需要空格。

支援的運算符號

指定運算符時，必須考慮元素路徑存在的值類型。  例如，在評估包含文字值的元素時，使用 greater than (>) 運算符號可能會產生空白輸出，因為以數值評估文字值是不合邏輯的。

篩選器語法與範例篩選器

所有篩選條件都必須以問號 (?) 開頭，並包含在括號中。  

單一條件

單一條件篩選條件使用下列語法：

?(Element_Path Operator Comparison_Value)

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

此過濾器會返回名稱元素等於executions_2023-12.csv 的所有記錄。

多重條件

多重條件篩選器使用下列語法：

?(Element_Path Operator Comparison_Value Logical_Operator Element_Path Operator Comparison_Value)

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

此過濾器會返回名稱元素等於executions_2023-12.csv 且狀態元素等於IMPORTED 的所有記錄。

命令配置範例

在本範例中，篩選器輸入設定為評估 JSON 有效負載中的name 元素。  在此範例中，篩選器使用年和月的變數作為 Runtime 輸入值。  這使得篩選器在執行 Chain 時，能動態計算指定的年份和月份。  

篩選值

篩選器只允許從 JSON 回應中擷取所需的資料。  這可以減少指令產生的輸出檔案大小，從而改善 Chain 的效能。 

此外，當嘗試從 JSON 回應中隔離單一行時，動態輸出 可用於從篩選的有效負載中擷取這些特定值，並使其可用於 Chain 的後續節點。 

下圖顯示動態輸出定義的範例。

使用單一節點 (Array to CSV) 執行傳統方式所需的四個節點的作業，因此產生的 Chain 更為精簡。  由於執行的指令較少，產生的輸出也較小，因此這個精簡的 Chain 也能更有效率地執行。