如何使用 Workiva API 将文件导入 Wdata

介绍

本指南将向您展示如何使用 Workiva API 将文件导入 Wdata。

如果您希望自动将数据集文件导入到 Wdata 表中，但不想使用 chains 和 Workiva 连接器，则可以直接从 chains 中使用 HTTP 连接器或从任何能够与使用 OAuth 2.0 保护的 REST API 进行交互的外部软件使用 Workiva 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}`	您的 Wdata 表 ID 为，可在 URL 中找到（参见此处）
`{fileId}`	您在上传步骤中导入的文件的 ID

以下示例中显示的是欧盟平台的 URL；对于美国或亚太地区，“eu”应分别更改为“app”或“apac”。

上传

将文件上传到您选择的 Wdata 表中： https://developers.workiva.com/wdata-v1/wdata-uploadfile/

例子：

POST：{baseURL}/api/v1/file 头部： Content-Type: multipart/form-data; boundary="boundary" 主体： --boundary Content-Disposition: form-data; name="delimiter" 分号 --boundary Content-Disposition: form-data; name="tableId" {tableId} --boundary Content-Disposition: form-data; name="file"; filename="filename.csv" Content-Type: text/plain 水果;数量 苹果;133 杏;175 牛油果;182 香蕉;187 越橘;160 黑莓;178 黑加仑;102 蓝莓;156 醋栗;194 樱桃;182 番荔枝;169 克莱门汀;165 枣;112 李子;164 榴莲;157 茄子;189 --boundary--

导入

然后使用响应中收到的“Id”作为“fileId”来导入文件： https://developers.workiva.com/wdata-v1/wdata-importfile/

例子：
```
POST：{baseURL}/api/v1/table/{tableId}/import 请求头：Content-Type：application/json 请求体：{"delimiter":";", "fileId":"{fileId}" } 
```
注意： 此请求仅启动文件导入，响应会在不等待成功或失败的情况下发送。

检查状态

虽然不是必须的，但在大多数使用场景中，确认并记录/报告文件导入是否成功是一种良好的做法。这可以通过以下两个 GET 请求来实现。

要确认导入文件端点已成功导入文件，您应该使用 （轮询）从导入中检索同一 {fileId} 的 [] 单个文件 端点，然后检查文件的响应。

例子：
```
GET：{baseURL}/api/v1/file/{fileId} 请求头：Content-Type：application/json 
```
如果状态为“正在导入”，则导入仍在进行中，因此您应该暂停该过程一段时间，然后再重复之前的请求（轮询）。
状态显示“已导入”表示文件已成功导入。
如果您的文件状态仍为“STAGED”且“numErrors”大于零，则表示文件导入失败，您可以使用 Retrieve errors endpoint 获取发生的错误消息。

故障排除

如果您无法向 API 发出任何请求（401 未授权错误）

请检查您是否使用了正确的 URL 前缀来指定您的 Workiva 工作区的位置。
请检查您的请求中是否使用了正确的客户端 ID 和密钥，前后不要有任何空格。

身份验证成功，但后续请求失败（出现 404 或 500 错误）。

检查您创建的 API 授权中指定的用户是否具有对指定 Wdata 表 ID 的访问权限。
检查 Wdata 表是否与 API 授权位于同一工作区。
请检查您使用的文件 ID 是否正确，前后是否包含空格。
检查您的标头，特别是“Content-Type”，确保与文档一致。

文件上传成功，但导入时出错。

请检查您是否指定了正确的分隔符。
请确保文件中的数据为平面文件格式，其中第 1 行 A 列为标题，第 2 行 A 列为数据。
请确保表头列的数量与数据列的数量一致。
检查数据类型是否与 Wdata 表设置中指定的数据类型一致。
检索与文件导入相关的错误以便进一步排查问题

支持

社区

Workiva支持中心