/manage-app-and-bindauth

name: manage-app-and-bindauth
description: |
  数据服务应用管理与 API 权限绑定。创建应用 → 添加成员 → 为应用授权 API → 验证授权结果 → 获取 AppKey/AppSecret 供后续调用使用。
  触发场景：创建数据服务应用 / API 授权 / 权限绑定 / 应用管理 / 密钥管理。

数据服务应用管理与 API 权限绑定

1. Scenario Description

管理员/开发者通过阿里云 CLI 完成数据服务应用的创建与 API 权限绑定全流程：

**业务流程：**

创建应用 → 添加成员（可选）→ 发现已发布 API → 授权 API（字段级）→ 验证授权 → 获取凭证

> ⚠️ **当前限制（据实测）**：`授权 API`（步骤 3，`grant-data-service-api`）与 `回收授权`（Cleanup，`revoke-data-service-api`）**当前 OpenAPI 暂不支持**——命令虽存在，但授权所需的字段标识（`Columns` / 字段 ID）无法通过现有 OpenAPI 获取，实测无法构造出有效的授权参数。**请通过 Dataphin 控制台完成 API 授权与回收**；本 Skill 的应用创建、成员、凭证管理不受影响。

**资源拓扑：**

数据服务项目
└── 应用（App）
    ├── AppKey / AppSecret（调用凭证）
    ├── 应用成员
    └── 已授权 API
        ├── API 信息
        └── 授权字段（GrantColumns）

**前置条件：**

• 数据服务项目已存在，当前用户为项目成员
• 至少一个 API 已发布到生产环境（可由 S1 `create-and-publish-api` 产出）

**与 S1 的衔接：**

• S1 产出 `ApiId`，本 Skill 消费 `ApiId` 完成授权
• 本 Skill 产出 `AppKey` / `AppSecret`，供 S3 `call-data-service-api` 消费

2. Installation

**Pre-check: Aliyun CLI >= 3.4.8 required** > 运行 `aliyun version` 确认版本 >= 3.4.8。未安装或版本过低，请从 https://aliyuncli.alicdn.com 安装/升级（各操作系统一键脚本见 ./references/cli-installation-guide.md）。

**Pre-check: Aliyun CLI plugin update required** > [MUST] 运行 `aliyun configure set --auto-plugin-install true` 开启插件自动安装。 > [MUST] 运行 `aliyun plugin update` 确保已装插件保持最新。

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

# 开启插件自动安装并更新已装插件
aliyun configure set --auto-plugin-install true
aliyun plugin update

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

# 验证
aliyun version            # 需 >= 3.4.8
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:CreateDataServiceApp",
    "dataphin:GetDataServiceApp",
    "dataphin:GetDataServiceAppGroups",
    "dataphin:ListDataServiceApps",
    "dataphin:ListDataServicePublishedApis",
    "dataphin:AddDataServiceAppMember",
    "dataphin:GrantDataServiceApi",
    "dataphin:RevokeDataServiceApi",
    "dataphin:ListAuthorizedDataServiceApiDetails",
    "dataphin:ResetDataServiceAppSecret"
  ],
  "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 | profile 或询问用户 | 是 | | ProjectId | 数据服务项目 ID | 需从控制台页面请求中手动获取（见下方说明） | 是（查已发布 API/应用列表用） | | AppGroupId | 应用分组 ID（**≠ ProjectId**） | `get-data-service-app-groups` 查询（见步骤 1a） | 创建应用时必填 | | AppName | 应用名称 | 用户指定 | 是 | | AppKeyStr | 应用 AppKey（字符串形式） | 创建返回 / `AppInfoList[].AppKeyStr` / `get-data-service-app` | 查已授权时必填 | | ApiId | 要授权的 API ID | S1 产出或步骤 2b 查询 | 是 | | GrantColumns | 授权字段列表 | 查询 API 字段后选择 | 是（控制台授权用） | | UserId | 要添加的成员 ID | 用户提供 | 否 |

**ProjectId 获取说明（重要）：** > 当前 **无 OpenAPI 可列举数据服务项目**，ProjectId 需从 Dataphin 控制台页面的网络请求中手动获取： > 1. 打开浏览器 DevTools（F12）→ Network 面板 > 2. 在 Dataphin 控制台进入「数据服务」模块，切换到目标项目 > 3. 观察网络请求中的 `projectId` 参数（通常出现在请求 URL 或 body 中，如 `projectId=126`） > 4. 将该整数值作为 `--project-id` 传入 > > ℹ️ 典型值为小整数（如 `126`、`130`），**与 19 位 snowflake ID 不同**。

**ApiId 获取说明：** > 若由 S1 `create-and-publish-api` 产出，直接传入即可。 > 若需独立获取，可通过步骤 2b `list-data-service-published-apis` 查询项目下已发布 API 列表。

**GrantColumns 获取说明：** > 授权 API 时需指定允许应用访问的字段列表。可通过 `get-data-service-api-document` 查询 API 返回参数，从中选择需要授权的字段名。 > ⚠️ **实测限制**：授权所需的字段标识无法通过现有 OpenAPI 完整获取，`grant-data-service-api` 当前无法经 OpenAPI 完成授权，请改用控制台（详见步骤 3）。

> **⚠️ 应用定位暗坑**：`list-data-service-apps` 按 `AppName` 找应用时，**同租户可能存在多个同名应用**（列表不返回 AppKey）。若用户给了 AppKey，应**用 AppKey 唯一确定**目标应用（逐个 `get-data-service-app` 取详情核对 `AppKey`），避免授权到错的应用。注意 `get-data-service-app` 返回的 `AppKey` 为**字符串**（如 `"200000326"`）。

7. Observability

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

所有 CLI 命令携带：

--user-agent AlibabaCloud-Agent-Skills/manage-app-and-bindauth/{SESSION_ID}

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

8. Core Workflow

步骤 1：创建数据服务应用

步骤 1a：查询应用分组（获取 AppGroupId）

> **⚠️ 关键概念**：创建应用需要 **应用分组 ID（`AppGroupId`）**，它与 `ProjectId` 是**两个独立概念**——`AppGroupId` 来自 Dataphin 独立的「应用分组」管理体系，**不能用 `ProjectId` 代替**。传错分组 ID（如把 `ProjectId` 当成 `AppGroupId`）服务端**不报错**，但应用会被分到不可见/不存在的分组，在平台分组管理页面找不到。

aliyun dataphin-public get-data-service-app-groups \
  --op-tenant-id "{OpTenantId}" \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/manage-app-and-bindauth/{SESSION_ID}"

> 从返回列表中选择目标分组的 `Id` 作为 `AppGroupId`（如 `509`）。注：该命令的 `--project-id` 参数**已废弃**，可不传；如需新建分组用 `create-data-service-app-group`。

步骤 1b：创建应用

HITL 确认（写操作）

执行前确认以下信息：

• 应用名称：`{AppName}`
• 应用分组：`{AppGroupId}`（来自步骤 1a，**非 ProjectId**）
• 影响范围：在目标分组下创建新应用
• 可回滚：创建后可删除

**确认后执行：**

aliyun dataphin-public create-data-service-app \
  --op-tenant-id "{OpTenantId}" \
  --create-command '{"AppGroupId": {AppGroupId}, "AppName": "{AppName}", "Scenarios": "OPENAPI"}' \
  --endpoint <YOUR_DATAPHIN_ENDPOINT> \
  --user-agent "AlibabaCloud-Agent-Skills/manage-app-and-bindauth/{SESSION_ID}"

> **create-command 结构**：`{AppGroupId: integer, AppName: string, AppKey?: string, AppSecret?: string, OwnerIds?: [string], Scenarios?: string}`。**无 `ProjectId`、无 `AppDescription` 字段**；`AppGroupId` 为整数，直接内嵌不加引号。

**响应处理：**

• 确认 `Code` 为成功
• 提取 `Ap