如何使用 Workiva API 將檔案匯入 Wdata

簡介

本指南將向您展示如何使用 Workiva API 將檔案匯入 Wdata。

如果您希望自動將資料集檔案匯入 Wdata 表格，但不希望將鏈結與 Workiva 連接器一起使用，您可以直接從鏈結使用 Workiva API使用 HTTP 連接器或任何能夠與受 OAuth 2.0 保護的 REST API 互動的外部軟體。

初始設定

首先，您需要建立一個 API 授與，它會產生一個用戶端 ID 和密碼。這可以由任何至少具有「工作區擁有者」或「組織安全性管理員」權限的 Workiva 使用者帳戶來完成，並按照此處提供的說明進行操作。

驗證

正確設定 API 授與後，與 API 通訊的第一步是獲得驗證。這會使用業界標準的 oauth 2.0 持有權杖交換，並且需要進行 POST 呼叫，如此處說明中所述。

匯入

使用 Workiva API 將資料載入 Wdata 表格需要執行兩個必要步驟：

將檔案上傳到您選擇的 Wdata 表格 (https://developers.workiva.com/wdata-v1/wdata-uploadfile/)。這會將您的檔案新增為表格中的資料集，狀態為「暫存」。因此，新資料此時不會顯示在表格的任何查詢或檢視表中。
匯入檔案 (https://developers.workiva.com/wdata-v1/wdata-importfile/)。您在上傳的回應中收到的「Id」可以在屬性「fileId」中使用，以匯入檔案，如果成功，則將資料新增到表格中，並在查詢和視圖中可用。

包含範例

索引鍵

文字	取代為
`{baseURL}`	您在此處定義為的相關位置代碼
`{tableId}`	在 URL 中找到您的 Wdata 表格 ID (請參閱此處)
`{fileId}`	您在上傳步驟中匯入的檔案 ID

以下範例顯示的是針對歐盟平台的 URL；美國或亞太地區的「歐盟」應分別變更為「應用程式」或「亞太地區」。

上傳

將檔案上傳到您選擇的 Wdata 表格中： https://developers.workiva.com/wdata-v1/wdata-uploadfile/

範例：

POST：{baseURL}/api/v1/file 標頭：內容類型：multipart/form-data；邊界=“邊界” 主體：--邊界內容處置：表單數據； name="delimiter" 分號 --邊界 Content-Disposition: form-data; name="tableId" {tableId} --邊界內容處置：表單資料； name="file"; filename="filename.csv" Content-Type：text/普通水果；數量 Apple；133 杏；175 鱷梨；182 香蕉；187 覆盆子；160 黑莓；178 黑加侖；102 藍莓；156 加侖；194 櫻桃；182 車厘子；169柑桔;165 日期;112 水母;164 榴蓮;157 茄子;189 --邊界--

匯入

然後使用您在回應中收到的「Id」作為「fileId」，將檔案匯入以下網址： https://developers.workiva.com/wdata-v1/wdata-importfile/

範例：
```
POST：{baseURL}/api/v1/table/{tableId}/import 標題：內容類型：application/json 主體：{ "delimiter":";", "fileId":"{fileId}" } 
```
注意： 此要求僅會啟動檔案匯入，且不會等待成功或失敗即傳送回應。

檢查狀態

如果檔案匯入成功與否，確認並記錄/報告不是必需的，但在大多數用例中是一種不錯的做法。這可以透過以下兩個 GET 要求來完成。

若要確認匯入檔案的端點是否已成功匯入檔案，您應該從匯入中使用 (輪詢) 為相同的 {fileId} 擷取單一檔案 端點，然後檢查檔案的回應。

範例：
```
GET：{baseURL}/api/v1/file/{fileId} 標頭：內容類型：application/json 
```
如果狀態為「正在匯入」，則匯入項目仍在進行中，因此您應該將進程暫停一段時間，然後再重複上一個要求（輪詢）。
「已匯入」狀態表示檔案已成功匯入。
如果檔案狀態仍為「暫存」且「錯誤次數」大於零，則檔案匯入失敗，您可以使用 擷取錯誤 端點擷取發生的錯誤訊息。

疑難排解

如果您無法向 API 提出任何要求 (401 Unauthorized 錯誤)

檢查您對 Workiva 工作區的位置使用了正確的 URL 前置詞。
檢查您在要求中使用正確的用戶端 ID 和密碼，前後不得有空格。

驗證有效，但後續要求無效（404 或 500 錯誤）

檢查您建立的 API 授與中指定的使用者是否有權存取指定的 Wdata 表格 ID。
檢查 Wdata 表格是否與 API 授予位於同一工作區。
請檢查您使用的檔案 ID 前後不得有空格。
檢查您的標頭，尤其是「內容類型」，是否與文件相符。

我的檔案上傳成功，但匯入時發生錯誤

檢查您指定的分隔符號是否正確。
請確保檔案中的資料採用平面檔案格式，標題在第 1 列中的 A 列，資料在第 2 列的 A 列。
請確保標題欄數與資料欄數相符。
檢查資料類型是否與 Wdata 表格設定中指定的資料類型相符。
擷取與匯入檔案相關的錯誤以進一步疑難排解

支援

社群

Workiva 支援中心