/create-and-publish-api

name: create-and-publish-api
description: |
  数据服务 API 创建与发布的完整流程。数据开发工程师通过 CLI 完成：查询项目 → 创建 SQL 模式 API → 发布到生产环境 → 验证发布结果。
  触发场景：创建数据服务 API / 发布 API / SQL API / API 开发 / 直连数据源创建 API。

数据服务 API 创建与发布

1. Scenario Description

数据开发工程师通过阿里云 CLI 完成数据服务 API 的全生命周期管理：

**业务流程：**

查询项目 → 查询分组 → 创建 API（直连 SQL 模式）→ 发布到生产 → 验证发布

**资源拓扑：**

数据服务项目
├── API 分组（可选）
└── API
    ├── 请求参数
    ├── 返回参数
    ├── 数据源绑定
    └── 发布状态（开发态 / 已发布）

**前置条件：**

• 数据服务项目已存在，当前用户为项目成员
• 目标数据源已注册并授权（[TODO: 数据源管理 Skill，属于 dataplan 模块]）

2. Installation

# 安装 aliyun CLI（>= 3.4.8）：https://github.com/aliyun/aliyun-cli
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

# 检查凭证配置
aliyun configure list

# 检查 CLI 版本
aliyun version
# 要求 >= 3.4.8

# 检查插件可用
aliyun dataphin-public --help

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

5. RAM Policy

本 Skill 涉及的最小 RAM 权限：

{
  "Effect": "Allow",
  "Action": [
    "dataphin:GetDataServiceMyProjects",
    "dataphin:GetDataServiceApiGroups",
    "dataphin:CreateDataServiceApi",
    "dataphin:PublishDataServiceApi",
    "dataphin:ListDataServicePublishedApis",
    "dataphin:GetDataServiceApiDocument"
  ],
  "Resource": "*"
}

Permission Failure Handling

若遇到权限错误（HTTP 403 或 ErrorCode 含 `Forbidden`/`NoPermission`），请： 1. 确认 RAM 用户已附加上述策略 2. 确认策略中 Resource 范围覆盖目标租户 3. 联系租户管理员授权

详见 [RAM 策略参考](../../ram-policies.md)。

6. Parameter Confirmation

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

顶层参数

| 参数 | 含义 | 获取方式 | 必填 | |------|------|---------|------| | OpTenantId | 租户 ID（小整数，如 300001413） | profile 或询问用户 | 是 | | ProjectId | 数据服务项目 ID（小整数，如 22） | 步骤 1 查询 | 是 | | ApiName | API 名称 | 用户指定 | 是 | | GroupId | API 分组 ID（小整数，如 85） | 步骤 2 查询 | 否 |

CreateCommand 必填参数

| 参数 | 含义 | 合法值 | 必填 | |------|------|-------|------| | ProjectId | 项目 ID | 小整数 | 是 | | ApiName | API 名称 | 字符串 | 是 | | ApiType | API 类型 | **3**（当前仅支持 3） | 是 | | Mode | 项目模式 | 0（Basic模式）/ 1（Dev-Prod模式） | 是 | | CallMode | 调用模式 | 1（同步）/ 2（异步） | 否 | | RequestType | 请求类型 | 0（GET单条）/ **1**（LIST多条）/ 2（CREATE）/ 3（UPDATE） | 是 | | BizProtocol | 协议 | **[0]**（HTTP） | 是 | | Version | 版本号 | **"1.0.0"** | 是 | | Timeout | 超时（毫秒） | 默认 **30000** | 是 | | ApiGroupId | 分组 ID（SDK 字段名） | 小整数 | 是 | | ApiGroupName | 分组名称 | 字符串（如 `默认API分组`） | 是 |

ScriptDetails 参数（SQL 模式必填）

| 参数 | 含义 | 合法值 | 必填 | |------|------|-------|------| | DatasourceID | 数据源 ID | **19 位 snowflake ID，必须用 Python SDK 传参** | 是 | | DatasourceType | 数据源或数据服务单元类型 | 0（数据服务单元）/ **1**（数据源） | 是 | | SqlMode | SQL 模式 | **1**（基础模式）/ 2（高级模式） | 是 | | Script | SQL 语句 | 使用 `${param}` 占位符 | 是 | | ScriptRequestParameters | 请求参数列表 | 见下方枚举 | 是 | | ScriptResponseParameters | 返回参数列表 | 见下方枚举 | 是 |

ScriptRequestParameters 字段

| 字段 | 含义 | 合法值 | 必填 | |------|------|-------|------| | ParameterName | 参数名称 | 与 SQL 中 `${param}` 对应 | 是 | | ParameterDataType | 数据类型 | 见 ParameterDataType 枚举 | 是 | | ParameterValueType | 参数值类型 | **1**（单值，用于=/>=/<=/>/</!=/between）/ 2（多值，用于 IN/NOT IN） | 是 | | IsRequiredParameter | 是否必填 | true / false | 否 | | DefaultValue | 默认值 | 字符串 | 否 | | ExampleValue | 示例值 | 字符串 | 否 |

ParameterDataType 枚举值（字符串类型）

| 值 | 含义 | |----|------| | STRING | 字符串 | | INT | 整型 | | LONG | 长整型 | | DOUBLE | 双精度浮点 | | FLOAT | 单精度浮点 | | SHORT | 短整型 | | BOOLEAN | 布尔 | | DATE | 日期（yyyy-MM-dd HH:mm:ss） | | BIGDECIMAL | 高精度十进制 | | BINARY | 二进制 | | BYTE | 字节 | | ARRAY | 数组 |

publish-data-service-api 参数

| 参数 | 含义 | 获取方式 | 必填 | |------|------|---------|------| | OpTenantId | 租户 ID | 同上 | 是 | | ApiId | API ID | 步骤 3 返回 | 是 | | ProjectId | 项目 ID | 同上 | 是 | | VersionId | 版本 ID | 步骤 3 返回或查询 | 是 |

**数据源获取说明：** > 数据源需预先创建并授权。当前可通过 Dataphin 控制台 > 数据源管理 获取 DatasourceID。 > [TODO: 数据源管理 Skill（dataplan 模块）后续补充]

**⚠️ 大整数精度警告：** > DatasourceID 是 19 位 snowflake ID（如 `7467470269897096832`），超过 JavaScript 安全整数范围（2^53）。 > **aliyun CLI 内部 JSON 解析会丢失精度**（`7467470269897096832` → `7467470269897097216`）。 > 因此 `create-data-service-api` **必须使用 Python SDK 而非 CLI**。详见 §8 步骤 3。

7. Observability

版本 `{version}`（Shell 变量 `SKILL_VERSION`）来自套件 `references/manifest.json` 的 `version` 字段，与 session-id 一同继承[父技能 §7](../../../SKILL.md#7-observability)。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

本子 Skill 的 session-id **继承自父 Skill `alibabacloud-dataphin-skills`**，不重新生成。

所有 CLI 命令携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{SESSION_ID} skill-version/{version}"

其中 `{SESSION_ID}` 为父 Skill 生成的 32 字符小写十六进制字符串。

8. Core Workflow

步骤 1：查询数据服务项目

aliyun dataphin-public get-data-service-my-projects \
  --op-tenant-id "{OpTenantId}" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{SESSION_ID} skill-version/{version}"

**响应处理：**

• 从返回的项目列表中选择目标项目
• 提取 `ProjectId`（小整数，如 22）
• 示例：`"ProjectId": 22`

步骤 2：查询 API 分组（可选）

aliyun dataphin-public get-data-service-api-groups \
  --op-tenant-id "{OpTenantId}" \
  --project-id "{ProjectId}" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{SESSION_ID} skill-version/{version}"

**响应处理：**

• 列出可用分组，用户选择或使用默认分组
• 提取 `GroupId`（小整数，如 85）

步骤 3：创建 API（Python SDK 方式）

> **⚠️ 为什么必须使用 Python SDK？** > `create-data-service-api` 涉及 `DatasourceID`（19 位 snowflake ID），aliyun CLI 内部 JSON 解析会将超过 2^53 的整数精度丢失。 > 例如：`7467470269897096832` → `7467470269897097216`（差值 384）。 > 必须使用 Python SDK 绕过此问题。

HITL 确认（写操作）

执行前确认以下信息：

• API 名称：`{ApiName}`
• SQL 语句：`{Sql}`
• 数据源：`{DatasourceID}`
• 调用模式：同步/异步
• 影响范围：在目标项目中创建新 API
• 可回滚：创