本指南提供實作「執行查詢並使用控制項工作表下載結果」範本的逐步說明。此範本是執行查詢命令的替代方案。使用者以往必須在部署及執行自動化工作流程前，手動在鏈結中輸入參數。
只要使用控制項工作表，使用者即可新增多個查詢 ID，並動態定義參數，例如選項清單或多選。此範本通常整合至現有的鏈結工作流程中，也可用於任何需要以 CSV 格式輸出查詢結果的工作流程。
必要條件
您的工作區必須啟用並設定以下連接器。
- 配置Workiva 連接器
- 配置JSON 連接器
- 配置Handlebars 連接器
- 設定HTTP 要求連接器
- 設定表格轉換連接器
您的工作區必須建立以下工作區變數：
- wsv_API 基本 URL - IAM
- wsv_Client ID
- wsv_Client Secret
- wsv_API 基本 URL - Wdata
尋找範本
執行查詢並使用控制項工作表下載結果範本位於範本畫面的 Workiva Chains 區段中。
以下是如何找到它：
- 在 Chain Builder 中，移至Templates 索引標籤。
- 從上方功能表選擇Workiva Chains 。
- 在右上角搜尋 0.0 Execute a Query | Top-Level Orchestration，並開啟該範本。
-
找到範本後，按一下New Chain 將其部署到您的工作區。
注意： 一旦配置完成，此模板中的每個鏈都必須發佈到工作區。
變數
| 變數類型 | 變數名稱 | 說明 |
|---|---|---|
| 工作區變數 | wsv_API 基本 URL - IAM |
根據您所在地區輸入 API 的基本 URL：
|
| 工作區變數 | wsv_Client ID |
輸入您在設定 API 授權時取得的用戶端 ID。 如需 Workiva API 的更多說明，請參閱此處。 |
| 工作區變數 | wsv_Client Secret |
您可以前往使用者設定檔的「安全性」分頁，然後在授權旁的「動作」下拉式選單中按一下「重新產生」選項，以檢視您的 API 授權密鑰。 如需 Workiva API 的更多說明，請參閱此處 |
| 工作區變數 | wsv_API 基本 URL - Wdata |
根據您所在地區輸入 API 的基本 URL： |
執行階段輸入項
配置模板
此範本包含兩個鏈結：0.0 Execute a Query | Top-Level Orchestration 與 0.1 Execute a Query | Download Results。主要鏈結部署至您的工作區時，子鏈結將自動一併部署。
- Top-Level Orchestration：根據控制項工作表中的資訊，此鏈結將判斷查詢使用的是單一參數類型（選項清單或多選），還是多種參數類型（同時包含選項清單與多選）。
- Execute a Query | Download Results：此鏈結使用了指定參數執行查詢，並擷取對應的資料。查詢執行完成後，結果會以 CSV 格式下載，供後續分析或使用。
控制項工作表設定完成且鏈結範本部署至您的工作區後，您只需提供控制項工作表的試算表 ID 與工作表 ID。
這些值必須新增為 Top-Level Orchestration 鏈結 的執行階段輸入。
依參數類型設定控制項工作表
控制項工作表的設定方式，將取決於您 Wdata 查詢中定義的參數類型。若查詢包含多種參數類型（例如同時包含選項清單與多選），每個參數必須使用相同的查詢 ID，分別定義於獨立的列中。若查詢僅使用一種參數類型，控制項工作表只需為該查詢設定單一列。
以下範例說明這兩種情境。
範例：使用多種參數類型的查詢
若查詢同時需要選項清單與多選參數，控制項工作表應為每個參數分別設定獨立的列，並全部使用相同的查詢 ID。
附註：索引鍵欄位對應至 Wdata 查詢中定義的參數名稱。
配置範例：
| 查詢 ID | 類型 | 索引鍵 | 值 |
|---|---|---|---|
| Wdata 查詢 ID | 選項清單參數 | 年 | 指定單一預設值（例如：2023）。 |
| Wdata 查詢 ID | 多選參數 | 帳戶類型 | 輸入多個可接受的值，以逗號分隔（例如：Asset, Expense, Equity, Revenue）。 |
範例：使用單一參數類型的查詢
若查詢僅使用一種參數類型，控制項工作表應為該查詢 ID 設定單一列。
例如，若查詢僅使用選項清單參數：
| 查詢 ID | 類型 | 索引鍵 | 值 |
|---|---|---|---|
| Wdata 查詢 ID | 選項清單參數 | 年 | 指定單一預設值（例如：January）。 |
請確保控制項工作表設定正確，設定錯誤可能導致後續問題。
將資料載入表格
您可以自動化將輸出資料直接載入表格的流程。若要將輸出資料載入表格，請考慮使用「將資料載入 Wdata」範本。您可以在下載結果的 HTTP 連接器處新增執行鏈結事件，將此步驟整合至您的流程中。
疑難排解
查看您的鏈運行歷史，包括錯誤：
- 移至 Chain Builder 中的Monitor 標籤。
-
將滑鼠移至問號上，檢視鏈執行的狀態。
若您的鏈結觸發錯誤或下載查詢結果失敗，請執行以下檢查：
- 確認兩個鏈結均已發布至您的工作區。每個連鎖必須單獨發佈。
- 確認 Wdata 中的查詢已更新至最新版本。
- 輸入查詢 ID、類型、索引鍵及控制項工作表中的值時，請確認已輸入完整 ID，且前後無多餘空格。同時確認索引鍵與值是否與 Wdata 中使用的參數完全相符。
- 確保與 Workiva 連線相關聯的OAuth2 授權 具有適當的存取權。
- 確認查詢中使用的所有參數均已包含在控制項工作表中。
其他資源
- 工作區連接器
- 檔案公用程式連接器
- JSON 連接器
- 表格轉換連接器
- 在另一個連鎖中執行連鎖 ("Run Chain events")
- OAuth2 授與
- Wdata 功能和 API 限制