/call-data-service-api

name: call-data-service-api
description: |
  调用 Dataphin 数据服务已发布的 API。使用附带脚本（Python 标准库，零依赖）完成 HMAC-SHA256 签名，无需下载官方 SDK。
  触发场景：调用数据服务 API / SDK 调用 / Python 调用 / AppKey 调用 / 异步调用 API。

数据服务 API 调用

1. Scenario Description

应用开发者调用 Dataphin 数据服务已发布并授权的 API，支持同步、异步和流式（SSE）三种调用模式。调用脚本内置 HMAC-SHA256 签名认证，**不依赖官方 SDK，也不需要任何第三方库**。

**业务流程：**

确认调用信息 → 同步调用 API → （可选）异步调用 → 验证调用成功

**资源拓扑：**

数据服务网关
├── 阿里云 API 网关模式（推荐脚本调用）
│   ├── HMAC-SHA256 签名（脚本内置）
│   └── AppKey/AppSecret → 脚本自动处理
├── 内置网关模式
│   ├── 参数认证（appkey/appsecret 请求参数）
│   └── AppKey/AppSecret → 请求参数
├── 同步调用（即时返回）
├── 异步调用
│   ├── 提交任务 → jobId
│   ├── 脚本自动轮询状态
│   └── 获取结果
└── 流式调用（SSE）
    └── 实时返回数据片段

**前置条件：**

• 至少一个 API 已发布到目标环境（S1 `create-and-publish-api` 产出）
• 应用已创建并获授权（S2 `manage-app-and-bindauth` 产出）
• 已获取 AppKey 和 AppSecret
• 已确认网关地址和 API 调用路径
• Python >= 3.9（仅需标准库）

**与 S1/S2 的衔接：**

• S1 产出 `ApiId` + API 路径（通过 `get-data-service-api-document` 查询）
• S2 产出 `AppKey` / `AppSecret`，本 Skill 消费这些凭证发起调用

**与 S1/S2 的本质差异：**

| 维度 | 管理面（S1/S2/S4） | 调用面（本 Skill） | |------|-------------------|-------------------| | 凭证 | RAM AccessKey/Secret | **App AppKey/AppSecret** | | 工具 | `aliyun` CLI | **本 Skill 调用脚本（HTTP + 签名）** | | 网关 | 阿里云 OpenAPI 网关 | **数据服务网关** | | 环境 | 无区分 | **Dev / Prod（stage 参数）** |

2. Installation

**无需安装任何 SDK 或第三方库。**

| 用途 | 要求 | 说明 | |-----|------|------| | **API 调用（本 Skill 核心）** | Python ≥ 3.9 | 直接用 `scripts/call-data-service-api.py`，纯标准库 | | 元信息查询（apiId/AppKey 等） | aliyun CLI ≥ 3.4.8 + dataphin 插件 | 见 [CLI 安装指引](./references/cli-installation-guide.md) | | 嵌入自有工程（可选） | `requests` 或标准库 | 见 [Python 调用模板](./references/python-client-template.md) |

> 官方 Python/Java SDK 亦可用（控制台「数据服务 → 应用管理 → 调用说明 → SDK 下载」），但**不是本 Skill 的前置条件**；脚本签名逻辑与官方 SDK v5.5.0 逐字节一致。

3. Environment Variables

| 变量 | 说明 | 必须 | |------|------|------| | DATAPHIN_APP_KEY | 应用 AppKey | 是 | | DATAPHIN_APP_SECRET | 应用 AppSecret | 是 | | DATAPHIN_GATEWAY_HOST | 数据服务网关地址 | 是 |

> **安全提示**：不要将 AppKey/AppSecret 硬编码在代码中，务必使用环境变量。

4. Authentication

Pre-check: Credentials Required

# 检查 Python 环境（脚本要求 >= 3.9，无需第三方库）
python3 --version

# 确认应用凭证已获取（来自 S2 manage-app-and-bindauth 产出）
# appKey: 应用 AppKey
# appSecret: 应用 AppSecret
# host: 数据服务网关地址（从控制台"网络配置"获取）

**凭证不可打印**：任何时候不得将 AppKey/AppSecret 输出到终端或日志。

**认证方式说明：**

本 Skill **不使用 RAM 凭证**，使用数据服务应用凭证（AppKey/AppSecret），签名由调用脚本内置完成。

| 网关类型 | 认证方式 | 脚本支持 | 适用场景 | |---------|---------|---------|---------| | **阿里云 API 网关** | HMAC-SHA256 签名（脚本自动处理） | ✅ 内置签名 | 公共云独立部署 | | **内置网关** | appkey/appsecret 作为请求参数 | 需手动构造 | 私有云独立部署 / VPC 环境 |

> **如何判断当前网关类型**：登录 Dataphin 控制台 → 数据服务 → 服务管理 → 网络配置。

5. App Authentication

> **本 Skill 不使用 RAM 认证**，改用数据服务应用认证。

认证方式一：脚本自动签名（阿里云 API 网关）——推荐

`scripts/call-data-service-api.py` 内置 HMAC-SHA256 签名，用户只需提供 AppKey/AppSecret，脚本自动完成全部签名流程（nonce/timestamp 生成、签名串构造、签名计算、Header 设置）。签名串规范见 [Python 调用模板 §1](./references/python-client-template.md)，App 认证说明见 [App 认证参考](../../ram-policies.md)。

认证方式二：参数认证（内置网关）

| 项目 | 说明 | |------|------| | 凭证类型 | App AppKey / AppSecret | | 传输方式 | 请求参数（Query 或 Body） |

内置网关模式下，appkey 和 appsecret 作为 API 的公共参数传入。详见 [App 认证参考](../../ram-policies.md)。

AppKey/AppSecret 获取

AppKey/AppSecret 由 S2 `manage-app-and-bindauth` 创建应用时获取。也可通过以下 CLI 命令查询：

# 查看应用详情（需要是应用成员，或 SuperAdmin 权限）
aliyun dataphin-public get-data-service-app \
  --op-tenant-id <tenantId> --app-id <appId> \
  --profile <profile> --endpoint <endpoint>

# 列出所有应用（查看 AppId，需应用成员才能获取 AppKey/AppSecret）
aliyun dataphin-public list-data-service-apps \
  --op-tenant-id <tenantId> \
  --list-query PageNo=1 PageSize=20 \
  --profile <profile> --endpoint <endpoint>

常见认证错误

| 错误码 | 原因 | 解决方案 | |--------|------|---------| | `AppKeyNotFound` | AppKey 无效 | 检查 AppKey 是否正确，是否来自 S2 | | `SignatureDoesNotMatch` | 签名不匹配（自行实现签名时） | 用附带脚本可避免；自研时对照 [签名规范](./references/python-client-template.md) 检查：`x-ca-signature-headers` 不含 `x-ca-signature` 自身、path 与签名串完全一致、JSON 请求不带 `content-md5` | | `TimestampExpired` | 时间戳偏差过大 | 确保客户端时间与服务器偏差 < 15 分钟 | | `The request api path not bind app` | 应用未授权该 API | 回到 S2 完成授权流程 | | `InvalidAppKey` | AppKey/AppSecret 参数错误（内置网关） | 检查 appkey/appsecret 参数值 |

Permission Failure Handling

若遇到权限错误（HTTP 403 或错误码含 `AppUnauthorized`/`Forbidden`），请： 1. 确认应用已通过 S2 `manage-app-and-bindauth` 获得目标 API 的授权 2. 确认 stage 参数与 API 发布环境匹配（RELEASE = 生产，PRE = 开发） 3. 确认当前用户是应用成员（`IsMember: true`） 4. 联系项目管理员授权

详见 [App 认证参考](../../ram-policies.md)。

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** > 执行前必须确认以下业务参数：

| 参数 | 含义 | 获取方式 | 必填 | |------|------|---------|------| | appKey | 应用 AppKey | S2 创建应用时获取；或 SuperAdmin 用 `get-data-service-app` 查询 | 是 | | appSecret | 应用 AppSecret | 同上 | 是 | | host | 数据服务网关地址 | 控制台「网络配置」或管理员提供 | 是 | | apiId | API 唯一标识（整数） | `list-data-service-published-apis` 或 API 列表页面 | 是 | | methodType | API 操作类型 | `get-data-service-api-document` 查询（LIST/GET/CREATE/UPDATE/DELETE）| 是 | | stage | 环境 | RELEASE（生产）/ PRE（开发），默认 RELEASE | 是 | | env | 数据环境 | PROD（生产数据）/ PRE（开发数据），默认 PROD | 是 | | 业务参数 | API 定义的请求参数 | `get-data-service-api-document` 的 `RequestParamList` | 视 API |

**host 获取说明：** > 网关地址从 Dataphin 控制台获取：数据服务 → 服务管理 → 网络配置。独立部署环境常见命名为 `dataphin-dataservice.<租户基础域名>`（反代 canonical 常落 `dataphin-os-gateway.*`）。该网关**与管理面 OpenAPI 端点 `dataphin-openapi.*` 不是同一域名**，也不在任何 OpenAPI 返回里。若无法直接拿到，可按命名规律**探测确认**（`curl POST /list/{apiId}` 返回 `DPN-OLTP-*` 即命中），详见 [调用前置发现 §网关 host 发现](./references/pre-call-discovery.md#网关-host-发现p1)。VPC/私有化部署中该域名可能不对外暴露公网地址，需联系运维确认。

> **⚠️ 参数获取暗坑（逆向参数时必看）**： > - **应用名不唯一**：同租户可能多个同名应用，必须用 **AppKey** 唯一确定，不靠名字。 > - **AppKey 是字符串**（如 `"200000326"`），比较用 `str()`。 > - `list-authorized-data-service-api-details` 用 **`AppKeyStr`**（字符串），`AppKey`（整型）已弃用。 > - `returnFields` 只能取**已授权字段**（步骤 C 产出），传未授权字段会报错。 > 完整清单见 [调用前置发现 §暗坑清单](./references/pre-call-discovery.md#暗坑清单p2-速查)。

**API 调用路径构造：**正确格式为 `/{methodType}/{apiId}?appKey={appKey}&env={env}`，**不是** `/api/<GroupId>/<ApiName>`。methodType