Create And Publish 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 安装指南。

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 策略参考。

6. Parameter Confirmation

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

顶层参数

CreateCommand 必填参数

ScriptDetails 参数（SQL 模式必填）

ScriptRequestParameters 字段

ParameterDataType 枚举值（字符串类型）

publish-data-service-api 参数

数据源获取说明：

数据源需预先创建并授权。当前可通过 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

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

所有 CLI 命令携带：

--user-agent AlibabaCloud-Agent-Skills/create-and-publish-api/{SESSION_ID}

其中 {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/create-and-publish-api/{SESSION_ID}"

响应处理：

• 从返回的项目列表中选择目标项目
• 提取 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/create-and-publish-api/{SESSION_ID}"

响应处理：

• 列出可用分组，用户选择或使用默认分组
• 提取 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
• 可回滚：创建后可删除

确认后执行：

import os
from alibabacloud_dataphin_public20230630.client import Client
from alibabacloud_dataphin_public20230630 import models as datap_models
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models

# UA 可观测（Principle 9）：SKILL_SESSION_ID 由 Agent 执行时内联注入（继承自父 skill）
SESSION_ID = os.environ.get('SKILL_SESSION_ID', '')
ua = 'AlibabaCloud-Agent-Skills/create-and-publish-api'
if SESSION_ID:
    ua = f'{ua}/{SESSION_ID}'

config = open_api_models.Config(
    access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
    access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
    endpoint='dataphin-openapi.{env}.aliyun.com',
    user_agent=ua
)
client = Client(config)
runtime = util_models.RuntimeOptions()
runtime.ignore_ssl = True  # 独立部署环境需忽略 SSL

# ⚠️ ParameterDataType SDK 定义为 int 是 bug，需 monkey-patch 为字符串
# 参考：https://github.com/aliyun/alibabacloud-sdk/issues

script_details = datap_models.CreateDataServiceApiRequestCreateCommandScriptDetails(
    datasource_id=7467470269897096832,  # ← 大整数在 Python int 中安全
    datasource_type=1,  # 0=数据服务单元, 1=数据源
    sql_mode=1,          # 1=基础模式
    script='SELECT user_id, user_name FROM user_info WHERE user_id = ${userId}',
    script_request_parameters=[
        datap_models.CreateDataServiceApiRequestCreateCommandScriptDetailsScriptRequestParameters(
            parameter_name='userId',
            parameter_data_type='STRING',   # ← 字符串枚举，非 int
            parameter_value_type='1',       # 1=单值（必填）
            is_required_parameter=True
        )
    ],
    script_response_parameters=[
        datap_models.CreateDataServiceApiRequestCreateCommandScriptDetailsScriptResponseParameters(
            parameter_name='user_id',
            parameter_data_type='STRING'
        ),
        datap_models.CreateDataServiceApiRequestCreateCommandScriptDetailsScriptResponseParameters(
            parameter_name='user_name',
            parameter_data_type='STRING'
        )
    ]
)

create_cmd = datap_models.CreateDataServiceApiRequestCreateCommand(
    project_id=22,
    api_name='query_user_info',
    api_type=3,           # 固定为 3（数据源SQL模式）
    mode=0,               # 0=Basic模式, 1=Dev-Prod模式
    call_mode=1,          # 1=同步
    request_type=1,       # 1=LIST（返回多条）
    biz_protocol=[0],     # [0]=HTTP
    version='1.0.0',      # 固定初始版本
    timeout=30000,        # 毫秒
    api_group_id=85,      # API 分组 ID（SDK 字段名）
    api_group_name='默认API分组',  # API 分组名称
    script_details=script_details
)

req = datap_models.CreateDataServiceApiRequest(
    op_tenant_id=300001413,
    create_command=create_cmd
)

resp = client.create_data_service_api_with_options(req, runtime)
print(resp.body.to_map())
# 成功时返回 ApiId

完整参数结构见 CreateDataServiceApi 参数参考。

SDK 安装：

pip3 install alibabacloud-dataphin-public20230630

响应处理：

• 确认 Code 为 OK
• 提取 ApiId（小整数，如 10121）

步骤 4：发布 API

HITL 确认（写操作）

执行前确认：

• 要发布的 API：{ApiName}（ID: {ApiId}）
• 版本 ID：{VersionId}
• 影响范围：API 发布到生产环境，可被授权应用调用
• 可回滚：发布后可下线

确认后执行：

aliyun dataphin-public publish-data-service-api \
  --op-tenant-id "{OpTenantId}" \
  --api-id "{ApiId}" \
  --project-id "{ProjectId}" \
  --version-id "{VersionId}" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/create-and-publish-api/{SESSION_ID}"

VersionId 说明：

• VersionId 即创建 API 时指定的 Version 字符串（如 "1.0.0"），直接传入即可

步骤 5：验证发布结果

aliyun dataphin-public list-data-service-published-apis \
  --op-tenant-id "{OpTenantId}" \
  --project-id "{ProjectId}" \
  --list-query "PageNo=1 PageSize=50" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/create-and-publish-api/{SESSION_ID}"

验证标准：

• 在 PageResult.ApiList 中找到 ApiId 对应的记录
• 确认 DeployTime 非空（表示已发布）

9. Success Verification

采用三步验证法：

1. 同步返回检查：create-data-service-api 返回 Code 为成功
2. 反查确认：list-data-service-published-apis（需传 --list-query 分页参数）能查到已发布 API
3. 文档获取（可选）：

aliyun dataphin-public get-data-service-api-document \
  --op-tenant-id "{OpTenantId}" \
  --id "{ApiId}" \
  --version-id "{VersionId}" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/create-and-publish-api/{SESSION_ID}"

10. Cleanup

如需清理测试创建的 API：

注意：当前 OpenAPI 可能不支持直接删除 API。如需清理，请通过 Dataphin 控制台操作。

11. Command Tables

详见 相关命令索引。

12. Best Practices

• 大整数精度丢失（Critical）：aliyun CLI 内部 JSON 解析使用 JavaScript Number，超过 2^53 的整数会精度丢失。DatasourceID 等大整数必须使用 Python SDK 传参，不可通过 CLI --create-command JSON 传入。
• CLI 参数格式：CLI 使用 kebab-case（如 --op-tenant-id），非 PascalCase（如 --OpTenantId）
• ProjectId / GroupId / ApiId：数据服务项目的 ID 是小整数（如 22/85/10121），非 snowflake ID
• SQL 占位符：使用 ${paramName} 语法定义请求参数，如 WHERE user_id = ${userId}
• 默认分组：如无特殊需求，可使用项目默认 API 分组
• SDK ParameterDataType Bug：SDK 中 ParameterDataType 定义为 int，但实际应为字符串枚举（"STRING"/"INT"/"LONG" 等），需 monkey-patch 或直接传字符串
• 独立部署 SSL：独立部署环境自签名证书需 runtime.ignore_ssl = True
• grant-data-service-api 限制：APP 类型授权查询类 API 需 ProdFieldList（含字段 ID），但 OpenAPI 未提供获取字段 ID 的接口，仅前端 RESTful API /api/dataService/api/queryApiColumns 可查。如遇此限制，可改用 USER 类型授权（无需 ProdFieldList）
• list-data-service-published-apis 需分页：必须传 --list-query "PageNo=1 PageSize=50" 参数，否则返回空列表
• 环境 Endpoint：
  • 管理面：dataphin-openapi.<env>.aliyun.com
  • 数据服务网关：dataphin-os-gateway.<env>.aliyun.com