Workiva Support Center

本指南将引导您使用 OpenAPI 规范将 Workiva API 集合导入 Bruno 。您将学习如何配置全局环境变量、使用 OAuth 2.0 进行身份验证以及端到端验证 API 请求。

先决条件

1. 从 www.usebruno.com 下载并安装 Bruno。

背景

Workiva API 以 OpenAPI (.yaml) 格式发布。这些规范可以直接导入到 Bruno 等 API 客户端中，使您能够处理完全结构化的集合，而无需手动构建请求。

步骤 1：导入 Workiva API 集合

1. 导航至 Workiva 平台代码生成 页面。
2. 下载 OpenAPI .yaml 文件。

3. 打开 Bruno。在左上角，点击三点菜单，然后选择 导入集合。

   

4. 选择 OpenAPI V3 文件 并选择下载的 .yaml 文件。

   

5. 出现提示时，创建或选择一个本地文件夹，Bruno 将在其中存储收藏集（例如， Bruno Collections）。

   

步骤 2：配置全局环境

1. 在 Bruno 的右上角，点击 地球图标 ，然后选择 配置。

   

2. 选择 创建全局环境。
3. 创建以下全局变量：
   • 访问令牌
   • 环境
   • 客户端ID
   • 客户端密钥
   • api_version

4. 填充 Environment、 ClientID和 ClientSecret的值。将 access_token 留空，并将 api_version 设置为 2026-01-01。

   

5. 保护环境。

步骤 3：配置 OAuth 2.0 – 获取令牌

为了在多个集合中重用身份验证，OAuth 访问令牌将存储为 全局环境变量。

1. 选择 Workiva API 集合。
2. 选择 “变量 ”选项卡。

3. 更新 baseUrl 变量，使其使用 {{environment}} 而不是硬编码的域名。

   原文：
   https://api.app.wdesk.com

   已更新：
   https://api.{{environment}}.wdesk.com

4. 将授权方式设置为 Bearer Token，并使用 {{access_token}} 变量。
5. 选择 脚本 选项卡。

6. 将以下脚本添加到 预请求 部分。

   对于 2026 平台 API，每个请求都需要 X-Version 标头。该脚本确保标头在整个集合中保持一致，符合 Workiva 2026 年 API 版本控制要求。

   注： 此要求目前仅适用于平台 API。

   // 添加或更新 X-Version 标头 (Bruno) req.setHeader("X-Version", bru.getGlobalEnvVar("api_version")); 

   

7. 在 Workiva API 集合中，导航到 oauth2 文件夹并打开 获取令牌。

8. 在 Post Response 脚本部分，添加以下内容以全局保存令牌：

   const body = res.getBody(); bru.setGlobalEnvVar("access_token", body.access_token); 

9. 保存更改。

步骤 4：生成 Bearer Token。

1. 在 OAuth2 请求正文中，设置：
   • {{ClientID}}
   • {{ClientSecret}}
2. 发送 获取令牌 请求。

3. 如果成功，响应将包含一个 Bearer 令牌，并且它将自动保存为 全局变量。

   

您现在可以发送经过身份验证的请求。如果成功，您将在响应中看到返回的文档列表。

步骤 5：导入并配置 Wdata 和 Chains API 集合

1. 转到 Wdata 代码生成 页面。
2. 下载 .yaml 文件并将其导入 Postman（按照 步骤 1：导入 Workiva API 集合中概述的步骤操作）。注意： .yaml 文件名可能与 Workiva API 集合相同。
3. 在 Wdata 集合中：
   • 选择 “变量 ”选项卡。

   • 更新 baseUrl 变量，使其使用 {{environment}} 而不是硬编码的域名。

     原文：
     https://h.app.wdesk.com/s/wdata/oc/api

     更新：
     https://h.{{environment}}.wdesk.com/s/wdata/prep

   • 将授权方式设置为 Bearer Token，并使用 {{access_token}} 变量。
   • 对 Chains API 集合重复上述步骤，确保授权设置和 baseUrl 变量以相同的方式配置。

疑难解答

• 请确保您引用的是正确的 环境。如果集合默认为“无环境”，则将其切换为 您指定的环境。
• 请确认 baseUrl 变量在您的环境和集合设置中保持一致。
• 请确保将 baseUrl 集合变量设置为使用 {{environment}}；否则，您的请求可能会失败。
• 如果您的请求返回 401 或空白响应，请重新检查您的客户端 ID、客户端密钥、API_version 和环境值是否正确。