大数据开发治理平台 DataWorks：API测试、发布与版本管理

测试开发中的 API

测试开发中的 API 是指在服务开发页面（即开发环境）中进行测试。在测试之前，您需要先通过向导模式或脚本模式生成 API，或通过注册已有服务的方式注册 API。

操作步骤：

1. 登录DataWorks控制台，切换至目标地域后，单击左侧导航栏的数据分析与服务 > 数据服务，在下拉框中选择对应工作空间后单击进入数据服务。

2. 在左侧 API 列表中，双击要测试的 API 名称，进入 API 编辑页面。

3. 在 API 编辑页面中，找到并单击测试按钮，打开API 测试对话框。

4. 在对话框左侧区域，为每个请求参数填入测试值。

5. 单击开始测试，触发 API 调用。

查看测试结果：

测试完成后，您可以在对话框右侧查看以下信息：

• 请求详情：展示本次测试的完整请求信息，包括请求路径、请求头和请求体等内容，方便确认请求构造是否正确。

• 返回内容：展示 API 的响应数据，即实际的查询结果。您可以对比返回内容与预期结果，确认 API 逻辑是否正确。

• 响应时长：显示本次 API 请求的端到端响应耗时，供您评估 API 的性能表现。如果响应延迟较大，需要考虑优化查询逻辑或数据源配置。

如果测试失败，请仔细查看返回的错误提示信息，根据提示进行相应修改后重新测试。

测试已发布的 API

测试已发布的 API 是指在服务管理页面（即生产环境）中进行测试，目的是验证 API 发布后的实际运行状态。进行此测试前，您需要先完成 API 的发布操作。

操作步骤：

1. 在数据服务页面，单击顶部导航栏的服务管理。

2. 在左侧导航栏中，单击API 测试。

3. 从下拉列表中选择需要测试的 API，确认 API 的请求参数值已配置完整。

4. 单击开始测试，在右侧查看请求详情和返回内容。

注意事项：

• API 测试页面仅提供 API 在线测试功能，不支持通过该页面更新 API 的正常返回示例。

• 如果 API 配置了返回结果分页展示，返回数据是否有序取决于底层数据源的行为。若需要排序，可在向导模式下为 API 配置排序字段，或在脚本模式下为 SQL 代码添加ORDER BY子句。

测试结果的解读与优化建议

一次完整的 API 测试结果由三部分构成，理解各部分含义有助于快速定位问题：

当测试结果完全符合预期后，即可进入下一阶段——将 API 发布至 API 网关。

准备工作

在发布 API 之前，请确保满足以下条件：

• API 网关已开通：请前往 API 网关控制台开通服务。

  重要

  由于 DataWorks 与 API 网关的网络架构限制，购买 API 网关实例时，实例类型目前仅支持传统专享实例，VPC 融合实例暂不支持。

• API 分组已创建：API 发布时会根据其所属业务流程的关联分组，将 API 部署到 API 网关中的对应分组。请确保业务流程已正确关联 API 网关分组（可通过右键业务流程>修改属性查看具体的分组名称）。

发布流程

API 的发布遵循提交 → 审批 → 发布的三步流程：

第一步：提交 API

1. 进入数据服务页面，在服务开发页面的 API 列表中，双击要发布的 API 名称，进入 API 编辑页面。

2. 单击右上方的提交按钮。

3. 提交成功后，系统会自动生成一个 API 版本（如 V1、V2 等），您可以在右侧弹出的版本面板中查看该版本的状态信息。

第二步：申请发布并等待审批

1. 在右侧的版本面板中，找到待发布的 API 版本，单击发布按钮。

2. 根据界面提示，输入申请原因并单击申请权限，提交发布申请。

3. 如果工作空间配置了审批流程，发布请求需要经过审批中心的审核。审批人可在审批中心>待我审批页面查看申请详情并进行审批。

4. 审批通过后，API 在版本面板中的状态会从待申请变为可发布。

第三步：执行发布

1. 审批通过后，在 API 编辑页面的右侧导航栏中，单击版本，找到状态为可发布的 API 版本。

2. 单击发布按钮，等待系统提示发布成功。

3. 发布成功后，DataWorks 会根据 API 所属业务流程的关联分组，将 API 部署至 API 网关中的对应分组。

发布后的验证

发布完成后，您可以通过以下方式验证和管理 API：

• 在 API 网关中查看：登录API网关控制台，在API 管理 > API列表中查看已发布的 API 信息，并可配置流量控制、访问控制等策略。

• 应用调用：如果 API 供自己的应用程序调用，需要在 API 网关中创建应用，将 API 授权到应用中，然后通过 AppKey 和 AppSecret 进行加密签名调用。API 网关还提供了主流编程语言的 SDK，可快速集成 API 至您的应用中。详情请参见客户端调用API示例；SDK 集成请参见SDK下载及使用指南。

• 协议变更：对已发布的 API，在服务管理>发布的 API页签下，单击对应 API 的更多>协议变更，修改 API 的访问协议（如从 HTTP 变更为 HTTPS）。协议变更实时生效，但如果删除了原有协议，原协议的接口调用将会失败，请谨慎操作。

上架至阿里云 API 市场（可选）

阿里云 API 市场涵盖多类目，可帮助实现数据变现。

数据服务生成和注册的 API 发布至 API 网关后，可以一键上架至阿里云 API 市场售卖，帮助企业快速实现数据价值变现，形成商业闭环。

前置要求：

• 仅支持企业身份入驻阿里云 API 市场。

• 上架前需以服务商身份入驻阿里云云市场。流程详见云市场入驻流程。

操作步骤：

1. 进入阿里云服务商平台。

2. 在左侧导航栏，单击商品 > 商品管理。

3. 单击发布商品。

4. 在接入信息页面，按照指引配置各项参数（包括商品名称、定价策略、API 绑定等），完成 API 的上架流程。

查看版本历史

1. 登录DataWorks控制台，切换至目标地域后，单击左侧导航栏的数据分析与服务 > 数据服务，在下拉框中选择对应工作空间后单击进入数据服务。

2. 在服务开发页面的 API 列表中，双击要查看的 API 名称，进入 API 编辑页面。

3. 单击页面右侧的版本按钮，打开版本面板查看版本信息、版本详情等。版本面板中展示了当前 API 的所有历史版本信息，包括：

   说明

   每个版本的操作列中提供API 详情链接，单击可查看该版本的完整配置信息，包括请求参数、返回参数、数据源配置等详细内容。

   字段	说明
   API ID	当前 API 的唯一标识符。
   版本	版本号，按提交顺序递增（V1、V2、V3……）。
   提交人	提交该版本的操作人员。
   提交日期	该版本的发布时间，精确至秒。
   状态	发布（当前线上生效的最新版本） 可发布（通过测试并提交的版本） 离线（历史旧版本）

版本对比

当 API 经过多次迭代修改后，您可能需要对比不同版本之间的差异，以便了解具体的变更内容。

操作步骤：

1. 在版本面板中，勾选任意两个需要对比的版本。

2. 单击面板底部的对比按钮。

3. 在弹出的历史版本对比对话框中，查看两个版本之间的差异。

对比内容说明：

• 向导模式 API：对比展示请求参数和返回参数的差异，包括参数名称、类型、是否必填等属性的变化。

• 脚本模式 API：对比展示 SQL 脚本的文本差异，以高亮方式标注新增、删除和修改的代码行。

版本对比功能特别适合在团队协作场景中使用，帮助审核人员快速理解每次变更的具体内容。

版本回滚

当新版本出现异常或不符合预期时，您可以将 API 快速回滚至之前的某个稳定版本。

操作步骤：

1. 在版本面板中，找到目标历史版本。

2. 单击该版本操作列中的回滚按钮。

3. 在弹出的确定要回滚当前版本对话框中，单击确认。

版本管理策略

良好的版本管理习惯能够显著降低线上事故的风险：

• 变更记录：每次提交时，在提交说明中清晰描述本次修改的内容和原因，方便团队成员通过版本对比了解变更上下文。

• 灰度验证：对于重大变更，建议先在测试环境充分验证，确认无误后再发布至生产环境。

• 快速回滚：线上发现异常时，优先使用版本回滚功能恢复服务，再排查问题根因。版本回滚比修改后重新发布更快，能够最大限度减少业务影响。

• 定期清理：对于长期未使用的 API，建议及时下线并清理，减少管理复杂度和潜在的安全风险。

测试与发布的协作流程

在团队协作场景中，推荐以下工作流程：

1. 开发者在服务开发页面完成 API 的创建和配置。

2. 开发者在开发环境中执行测试，确认功能正确。

3. 开发者提交 API，生成新版本并发起发布申请。

4. 审批人在审批中心审核发布申请，可通过版本对比功能查看变更内容。

5. 审批通过后，开发者执行最终发布操作。

6. 运维人员在服务管理页面对已发布 API 进行线上测试和监控。

7. 如发现问题，通过版本回滚快速恢复，或下线 API 进行修复。

通过遵循这一流程，团队可以在保证发布质量的同时，实现高效的 API 全生命周期管理。

返回示例的限制

API 编辑页面支持设置正常返回示例，用于在 API 文档中展示预期的返回数据结构。需要注意以下限制：

• 不自动同步：API 测试页面的返回结果不会自动更新为 API 的正常返回示例。您需要在 API 编辑页面手动编辑或粘贴返回示例。

• 大小限制：正常返回示例的内容有最大字符数限制。如果示例数据过大（例如包含上百条记录），可能保存失败。建议仅保留 2~3 条典型记录作为示例。

• 发布后生效：修改正常返回示例后，需要重新提交并发布 API 才会在 API 网关文档中生效。

数据源表结构变更后的处理

当 API 关联的数据源表结构发生变更（如新增字段、删除字段、修改字段类型）时，已发布的 API 不会自动感知这些变更。如果不处理，可能导致以下问题：

操作步骤：

1. 进入 API 编辑页面，根据表结构变更修改 API 配置。

   1. 向导模式：重新选择表，系统会自动刷新字段列表。

   2. 脚本模式：手动修改 SQL 语句中的字段名或表名。

2. 保存配置后，重新执行测试验证。

3. 提交并重新发布 API。