大数据开发治理平台 DataWorks：调用API

调用前提：三要素缺一不可

在调用任何数据服务 API 之前，您需要确保以下三个条件全部满足：

三者的关系可以理解为：API 是“门”，App 是“身份证”，授权是“通行证”。只有同时出示合法的身份证和对应的通行证，才能通过这扇门。

创建应用（App 身份）

应用（App）是您调用 API 时的身份凭证载体。每个 App 拥有一组独立的认证信息（AppKey、AppSecret、AppCode），相当于该身份的“账号和密码”。

自动创建的默认应用

当您在 DataWorks 中首次发布 API 时，系统会自动在 API 网关中创建一个与工作空间同名的应用（App），并将该工作空间下的所有 API 自动授权给这个默认应用。这意味着：

• 同一工作空间内的成员，可以直接使用默认 App 的凭据调用本空间下的 API，无需额外授权。

• 默认应用的认证信息可在数据服务控制台的API 调用页面查看。

手动创建应用

如果需要对不同的调用方进行流量隔离或权限区分，您可以在 API 网关控制台中手动创建新的应用：

1. 登录API 网关控制台。

2. 在左侧导航栏，选择应用管理。

3. 单击创建应用，输入应用名称和描述。

4. 创建成功后，系统会为该应用生成一组 AppKey、AppSecret 和 AppCode。

授权流程

授权是指将某个 API 的调用权限授予指定的应用（App）。只有建立了授权关系的 App，才能使用其凭据成功调用对应的 API。

授权给其他账号

当您需要将 API 开放给其他阿里云账号下的工作空间调用时，需要进行跨账号授权：

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

2. 进入数据服务页面，单击顶部菜单栏的服务管理，进入API 管理页面。

3. 在发布的 API页签下，找到目标 API，单击其后的授权。

4. 在API 授权对话框中，配置以下参数：

   

   参数	说明
   API 名称	待授权的 API 名称，默认不可修改。
   要授权的云账号 ID	需要获得该 API 调用权限的阿里云账号 ID。您可以在页面查看账号 ID。
   要授权的工作空间	选择目标阿里云账号下的工作空间名称。
   授权有效期	选择授权的有效期限（详见下文）。

5. 单击确认，完成授权。

授权有效期

授权有效期决定了被授权方可以调用 API 的时间范围：

查看已授权与被授权的 API

在API 管理页面，您可以从两个维度查看授权状态：

查看获得授权的 API（我被授权了哪些 API）

单击获得授权的 API页签，查看所有其他账号授权给您的 API 列表。在此页面您可以：

• 单击测试，在线测试获得授权的 API。详情请参见测试API。

• 单击删除，主动放弃某个 API 的调用授权。

查看授权给他人的 API（我授权了哪些 API 给别人）

单击授权给他人的 API页签，查看您授权给其他工作空间的 API 列表。在此页面您可以：

• 单击测试，在线测试已授权的 API。

• 单击授权管理，取消或修改对特定工作空间的授权。

三种授权场景

根据团队规模和安全管理需求的不同，API 授权的粒度也有所差异。以下三种场景覆盖了最常见的授权方案。

场景一：同一工作空间，共用一个 App

场景描述：同一个 DataWorks 工作空间下的所有成员，共同使用工作空间默认创建的同一个应用（App）来调用 API。

适用情况：团队规模较小、成员之间信任度高；不需要区分不同成员的调用流量来源；快速启动，最简配置。

工作方式：DataWorks 在 API 发布时自动创建与工作空间同名的 App，并自动将工作空间内的所有 API 授权给该 App。工作空间内的所有成员共享这组 AppKey、AppSecret 和 AppCode。

优势：零配置，开箱即用。劣势：无法区分具体是哪个成员发起的调用；如果某个成员的凭据泄露，影响范围为整个工作空间。

场景二：每个 RAM 用户使用独立的 App

场景描述：企业内的每个 RAM 用户（子账号），各自在 API 网关中创建独立的应用（App），分别获得 API 的调用授权。

适用情况：需要精确追踪每个用户的 API 调用行为；需要对不同用户设置不同的限流策略；安全合规要求较高，需要做到“一人一凭据”。

工作方式：每个 RAM 用户登录 API 网关控制台各自创建自己的 App；API 管理员将 API 分别授权给每个用户的 App；每个用户使用自己 App 的凭据调用 API。

优势：调用行为可追溯到个人，安全隔离性强，凭据泄露影响范围最小。劣势：管理开销较大，每新增一个用户都需要创建 App 和配置授权。

场景三：多个 RAM 用户分组，每组共用一个 App

场景描述：将多个 RAM 用户按业务职能或团队划分为若干组，每组成员共同使用同一个应用（App）来调用 API。

适用情况：团队规模较大，按部门或项目组划分；需要区分不同业务线的调用流量，但不需要精确到个人；在管理成本与安全性之间取得平衡。

工作方式：按业务组创建对应数量的 App；API 管理员将 API 授权给各业务组的 App；组内成员共享本组 App 的凭据。

优势：管理粒度适中，既能区分业务来源又不会产生过多管理开销。劣势：组内成员之间无法进一步区分。

场景选型建议

三类凭据辨析：避免混淆

数据服务涉及三类完全不同的认证凭据，用途、来源和使用场景完全不同，请务必区分：

一句话记忆：AccessKey 管“连数据源”，AppKey 管“调 API”，RAM 管“进控制台”。三者各司其职，互不替代。

混淆一：“API 调用报 403，但我有 RAM 管理员权限” — RAM 权限控制的是 DataWorks 控制台操作权限，而不是 API 调用权限。API 调用权限由 App 授权控制。即使您是 RAM 管理员，调用 API 时仍然需要一个已被授权的 App 的 AppKey/AppSecret。

混淆二：“数据源配置的 AccessKey 和 API 调用的 AppKey 是同一个吗？” — 不是。AccessKey 用于数据服务后台连接数据源；AppKey 用于调用方调用 API。两者完全独立。

混淆三：授权页面的“云账号 ID”填什么？ — 授权页面要求填写的是阿里云账号 ID（纯数字），而非 RAM 用户名或登录邮箱。获取方式：登录账号管理页面，在安全设置中查看账号 ID。

认证方式对比

API 网关支持两种身份认证方式。数据服务默认会为工作空间下的 API 添加“阿里云 APP 认证”，调用方可以根据安全需求选择具体的认证方式。

简单认证（AppCode）

调用者仅需在 HTTP 请求的 Header 中添加 AppCode 即可完成身份认证，无需进行签名计算。

请求示例：

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

签名认证（AppKey + AppSecret）

调用者需要使用 AppSecret 对请求内容进行 HMAC-SHA256 签名计算，将 AppKey 和签名值添加到请求 Header 中。API 网关收到请求后使用相同的 AppSecret 重新计算签名，对比签名是否一致来验证调用者身份。

请求示例（Header 部分）：

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

两种方式对比

签名算法详解

签名认证基于 HMAC-SHA256 算法，核心流程如下：

签名流程概览

1. 构造规范化请求字符串（StringToSign）：将 HTTP 方法（GET/POST）、Accept Header、Content-MD5（请求 Body 的 MD5 值）、Content-Type、Date、参与签名的自定义 Header（X-Ca-*，按字母序排列）以及规范化 URL（路径 + 排序后的查询参数）依次拼接。

2. 使用 HMAC-SHA256 计算签名：Signature = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. 将签名信息添加至请求 Header：包括 X-Ca-Key（AppKey）、X-Ca-Signature（签名值）、X-Ca-Timestamp（毫秒级时间戳）、X-Ca-Nonce（UUID，防重放）和 X-Ca-Signature-Headers（参与签名的 Header 列表）。

关键注意事项

在实现签名算法时，以下细节容易出错：

• 参数排序：URL 查询参数和签名 Header 必须按 Key 的字母序（ASCII 码序）排列。

• URL 编码：参数值中的特殊字符（空格、中文等）需要进行 URL 编码。

• 换行符：StringToSign 中各行之间使用 \n（LF）分隔，不能使用 \r\n（CRLF）。

• 空值处理：无 Body 时 Content-MD5 为空字符串（不是 null），Accept 等 Header 不存在时也用空字符串。

• 时间戳精度：X-Ca-Timestamp 为毫秒级时间戳，客户端与服务器时间偏差不能超过 15 分钟。

• Nonce 唯一性：每次请求必须生成唯一的 UUID 作为 X-Ca-Nonce，重复使用会触发重放攻击拦截。

查看认证凭据

在成功创建应用并获得授权后，您需要获取 AppKey、AppSecret 或 AppCode 来进行 API 调用。数据服务提供了便捷的凭据查看入口。

通过数据服务控制台查看

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

2. 在数据服务页面，单击页面顶部菜单栏的服务管理。

3. 在左侧导航栏，单击API 调用。

4. 在API 调用页面，您可以查看和复制以下认证信息：AppKey（应用唯一标识）、AppSecret（用于签名认证，请妥善保管）、AppCode（用于简单认证）。

通过 API 网关控制台查看：登录 API 网关控制台，在应用管理中找到目标应用，进入详情页查看 AppKey、AppSecret 和 AppCode。

通过 API 网关 SDK 调用

API 网关提供了主流编程语言的 SDK，帮助您快速集成 API 调用。SDK 已内置签名算法的实现，您无需手动计算签名，只需提供 AppKey 和 AppSecret 即可。详情请参见调用 API 文档和SDK 下载与使用。

支持的 SDK 语言

使用 SDK 的优势

相比手动构造 HTTP 请求，使用 SDK 调用有以下优势：

• 自动签名：SDK 内部实现了 HMAC-SHA256 签名算法，开发者无需关心签名细节。

• 自动重试：部分 SDK 内置了网络异常重试机制。

• 参数校验：SDK 会在发送请求前进行基本的参数合法性校验。

• 性能优化：SDK 通常使用连接池和 HTTP/2 等技术优化网络性能。

快速集成示例（Java）

以下示例展示如何使用 API 网关 Java SDK 调用数据服务 API：

// 1. 添加 Maven 依赖
// <dependency>
//     <groupId>com.aliyun.api.gateway</groupId>
//     <artifactId>sdk-core-java</artifactId>
//     <version>最新版本</version>
// </dependency>

// 2. 初始化客户端
HttpClientBuilderParams params = new HttpClientBuilderParams();
params.setAppKey("your_app_key");
params.setAppSecret("your_app_secret");

ApacheHttpClient client = new ApacheHttpClient(params);

// 3. 构造请求
IoTApiRequest request = new IoTApiRequest();
request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com");
request.setPath("/api/v1/query");
request.setHttpMethod("GET");
request.putQueryParam("pageSize", "10");
request.putQueryParam("pageNum", "1");

// 4. 发起调用
ApiResponse response = client.execute(request);
System.out.println("Response: " + response.getBody());

快速集成示例（Python）

# 1. 安装 SDK
# pip install aliyun-api-gateway-sdk

# 2. 调用 API
from com.alibaba.cloudapi.sdk.client import DefaultClient
from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams

params = HttpClientBuilderParams()
params.app_key = "your_app_key"
params.app_secret = "your_app_secret"
params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com"

client = DefaultClient(params)
response = client.get(
    path="/api/v1/query",
    query_params={"pageSize": "10", "pageNum": "1"},
    headers={"Accept": "application/json"}
)

print(f"Status: {response.status_code}")
print(f"Body: {response.content}")

完整调用流程总结

从 API 发布到成功调用的完整流程：API 开发者开发并测试 API、发布 API 至 API 网关（自动创建默认 App 和授权）；如需跨账号共享则手动授权给目标账号。API 调用者创建 App（或使用默认 App）、获取认证凭据（AppKey/AppSecret/AppCode）、选择认证方式（简单认证使用 AppCode，签名认证使用 AppKey+AppSecret），最后通过 SDK 或 HTTP 调用 API。API 网关验证身份后，数据服务执行查询并返回结果。

相关文档

• 发布API：了解如何将 API 发布至 API 网关。

• 授权API：了解授权操作及授权给他人的 API 管理。

• 测试API：在服务管理页面对已发布或已授权的 API 进行测试。