bk-cli-apigateway

name	bk-cli-apigateway
description	当需要通过 `bk-cli apigateway` 发现 BlueKing API Gateway 中所有公开网关、浏览某个网关公开的 API/资源列表、获取 OpenAPI/Schema、判断某个接口该怎么调用，或在 `apigateway` 子命令与 `bk-cli api` 之间做选择时使用。尤其是当用户还不知道或不确定该调用哪个网关、哪个公开接口、接口名可能是什么、只知道业务目标/关键词/资源名片段时，也应优先使用这个 skill，先搜索再确认，而不是直接猜测接口。

bk-cli apigateway — API Gateway 管理

用于发现网关、浏览网关 API，并获取 OpenAPI Schema。

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../bk-cli-shared/SKILL.md。共享 skill 负责认证、context、tenant、stage、header/body、dry-run、verbose 等通用使用规则；本 skill 只补充 apigateway 命令自己的探索与调用路径。

何时优先使用本 Skill

• 用户只知道“我想做什么”，但不知道应该调用哪个公开网关或公开接口。
• 用户还不知道当前有哪些网关，或只知道模糊名称，需要先筛选、搜索和浏览。
• 用户知道网关名，但还不知道资源名、API 名或入参，希望先查看资源列表与 Schema。
• 用户在决定“这里该用现成 apigateway 子命令，还是退回 bk-cli api”。
• 用户要把 API Gateway 发现结果接到脚本或 jq 中继续处理。

推荐工作流

1. 先 list_gateways 搜索并确认可能相关的公开网关。
2. 再用 list_gateway_apis 浏览该网关公开资源，缩小到候选 API。
3. 如果结果不唯一，向用户展示候选网关/API，并明确说明你为什么认为它们相关，请用户确认最终目标。
4. 用 retrieve_gateway_api_details 查看完整 Schema、认证要求、方法、路径、请求/响应结构。
5. 如果目标已经有合适的 apigateway 子命令，就继续使用该命令做发现或查看。
6. 如果需要真正调用某个公开 API，或目标接口尚未映射成 apigateway 子命令，就根据详情里的协议信息切换到 bk-cli api 做原始调用。

Agent 工作方式

发现优先，不要猜接口

• 当用户不知道网关名、API 名、路径或入参时，不要直接假设接口。
• 先使用 list_gateways 和 list_gateway_apis 做搜索，把“我猜你要这个接口”变成“这里有几组可能匹配的公开接口”。
• 如果有多个候选，先给用户一个短名单，再继续下一步，不要跳过确认环节。

候选确认方式

给用户候选时，尽量包含这些信息：

• gateway_name
• api_name
• 简短匹配理由，例如“名字包含 system”“描述里提到了权限”“路径看起来对应创建应用”

推荐话术是“我找到了 2 个可能相关的公开接口，请确认你要的是哪一个”，而不是“我直接替你调用最像的那个”。

从发现切换到调用

• bk-cli apigateway 负责“找网关、找接口、看详情、看 Schema”。
• bk-cli api 负责“按真实 method/path/query/body/header 发请求”。
• 只有在看过 retrieve_gateway_api_details 的结果之后，才去组装 bk-cli api 调用更稳妥。
• 首次调用、排障、或用户自己也不确定参数时，优先先生成 bk-cli api ... --dry-run，确认 URL、headers、body 后再真正发请求。

组装 bk-cli api 的原则

从 API 详情 / Schema 中提取这些信息：

• 网关名：对应 bk-cli api <gateway_name>
• HTTP 方法：如 GET、POST
• 路径：填到 api_path
• query 参数：放入 --query '<json>'
• path 参数：如果路径模板里有占位符，用 --path '<json>'，否则直接写入具体路径
• body：放入 --body '<json>'
• 额外 header：仅在接口详情确实要求时再用 --header

如果 detail/Schema 不能唯一说明如何调用，就先把不确定点告诉用户，再确认，不要把缺失信息默默补成猜测值。

读取 auth_config 做调用前检查

retrieve_gateway_api_details 的返回里如果包含：

{
  "auth_config": {
    "user_verified_required": false,
    "app_verified_required": true,
    "resource_perm_required": true
  }
}

应把它理解成接口调用前置条件，而不只是展示字段：

• app_verified_required: true：调用方需要带应用身份。
• user_verified_required: true：调用方需要带用户身份。
• resource_perm_required: true：除了有应用身份外，应用通常还需要先申请该 API 的资源权限。

对 agent 来说，推荐这样解读：

• 仅 app_verified_required: true：优先确认当前登录票据里有应用身份，或使用可满足要求的 access_token。
• 同时 app_verified_required: true 且 user_verified_required: true：优先确认当前登录票据同时具备应用身份和用户身份，或使用可满足要求的 access_token。
• resource_perm_required: true：即使认证字段齐全，也不能排除“应用尚未申请该 API 权限”。

失败时的诊断提示

如果后续 bk-cli api 调用失败，应该结合 retrieve_gateway_api_details 的 auth_config 一起解释错误，而不是只把原始报错丢给用户。

优先按下面的思路提示：

• 当接口要求应用认证，但当前登录方式没有应用身份时，提示用户检查 bk_app_code / bk_app_secret，或改用满足条件的 access_token。
• 当接口要求用户认证，但当前登录方式没有用户身份时，提示用户检查 bk_token / bk_ticket，或改用满足条件的 access_token。
• 当接口要求资源权限，且报错表现像“无权限访问 / permission denied / forbidden”时，明确提示“这不一定只是登录票据问题，也可能是应用尚未申请该 API 权限”。
• 当接口既要求应用身份又要求资源权限时，不要只给单一结论；应同时告诉用户检查“登录身份是否完整”以及“应用是否已申请 API 权限”。

推荐输出风格：

• 先说明该接口从 auth_config 看需要什么。
• 再说明当前报错更像是“缺身份”还是“缺 API 权限”。
• 如果无法仅凭错误唯一判断，就把两种最可能原因按优先级列出来，不要伪装成确定结论。

快速开始

# 1. 认证
bk-cli auth login --bk_app_code="your_app" --bk_app_secret="your_secret" --bk_token="your_token"

# 2. 列出网关
bk-cli apigateway list_gateways

# 3. 列出某个网关的 API
bk-cli apigateway list_gateway_apis --gateway_name bk-iam

# 4. 获取 API 详情 / Schema
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

面向“不确定接口”的探索流程

当用户只给出业务目标，例如“我想找蓝鲸里公开的权限系统接口”“我不知道该调哪个网关，只知道想查应用信息”，优先按下面的顺序做：

1. 用关键词、名称或模糊匹配搜索公开网关。
2. 进入最相关的一个或几个网关，列出公开 API。
3. 再用关键词缩小到候选接口。
4. 把候选接口返回给用户确认。
5. 对确认后的接口读取详情/Schema。
6. 根据详情构造 bk-cli api 调用。

示例：

# 先找可能相关的公开网关
bk-cli apigateway list_gateways --keyword "iam"
bk-cli apigateway list_gateways --name iam --fuzzy

# 再看某个网关下的公开接口
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "system"

# 确认接口后查看详情
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

Commands

list_gateways

列出所有 API Gateway，可按条件筛选。

bk-cli apigateway list_gateways [--name <name>] [--fuzzy] [--keyword <keyword>]

Flag	类型	必填	说明
--name	string	否	网关名称过滤
--fuzzy	bool	否	启用网关名称模糊匹配
--keyword	string	否	描述字段中的搜索关键词

bk-cli apigateway list_gateways --name bk-iam
bk-cli apigateway list_gateways --name iam --fuzzy
bk-cli apigateway list_gateways --keyword "identity"

list_gateway_apis

列出某个网关下的 API（资源）。

bk-cli apigateway list_gateway_apis --gateway_name <name> [--keyword <keyword>]

Flag	类型	必填	说明
--gateway_name	string	是	网关名称，必须匹配 ^[a-z][a-z0-9-]{2,29}$
--keyword	string	否	搜索关键词

bk-cli apigateway list_gateway_apis --gateway_name bk-iam
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "create"
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --header 'X-Request-Id:req-001'

retrieve_gateway_api_details

获取某个资源的完整 API Schema，包括 OpenAPI 规范、请求/响应格式和认证要求。

bk-cli apigateway retrieve_gateway_api_details --gateway_name <name> --api_name <name>

Flag	类型	必填	说明
--gateway_name	string	是	网关名称，必须匹配 ^[a-z][a-z0-9-]{2,29}$
--api_name	string	是	API 资源名

bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

query_log_by_request_id

根据 request_id 查询 API Gateway 日志。

bk-cli apigateway query_log_by_request_id --request_id <id>

Flag	类型	必填	说明
--request_id	string	是	要查询的请求 ID

bk-cli apigateway query_log_by_request_id --request_id=9f6563e4-cc2d-402d-b8d0-11ad26d7f6a9

认证与通用输入

认证、--stage、--body、--header、tenant、timeout、dry-run、verbose 等通用规则见 ../bk-cli-shared/SKILL.md。

环境与请求输入

# 使用 testing stage，而不是 prod
bk-cli apigateway list_gateways --stage testing

# 使用不同的 context（BlueKing 部署）
bk-cli apigateway list_gateways --context clouds

# 查看实际请求/响应细节
bk-cli apigateway list_gateways --verbose

# 传入请求级 header
bk-cli apigateway list_gateway_apis --gateway_name bk-iam \
  --header 'X-Request-Id:req-001'

说明：

• --gateway_name 会在本地校验 ^[a-z][a-z0-9-]{2,29}$，不合法时直接返回 invalid_gateway_name。
• 其他通用请求输入与排障顺序以 ../bk-cli-shared/SKILL.md 为准。

原始 API 调用

如果某个 apigateway 接口还没有映射成子命令，直接使用 bk-cli api。完整说明见 bk-cli-api skill。

bk-cli api bk-apigateway GET /api/v2/open/gateways/ --query '{"name":"bk-iam"}'
bk-cli api bk-apigateway GET /api/v2/open/gateways/ --dry-run

一个常见串联方式是：

# 1. 发现公开网关
bk-cli apigateway list_gateways --name iam --fuzzy

# 2. 浏览该网关下的公开接口
bk-cli apigateway list_gateway_apis --gateway_name bk-iam --keyword "system"

# 3. 查看目标接口详情 / Schema
bk-cli apigateway retrieve_gateway_api_details --gateway_name bk-iam --api_name create_system

# 4. 根据详情改用 bk-cli api 发真实请求
bk-cli api bk-iam POST /api/v2/systems/ --body '{"id":"demo","name":"Demo"}' --dry-run

上面第 4 步里的 POST、路径和 body 只是“根据第 3 步详情去落命令”的示例形态。真正执行时，应以 retrieve_gateway_api_details 返回的协议信息为准，不要跳过确认直接套用。

Pipeline 示例

# 提取 data
bk-cli apigateway list_gateways | jq '.data'

# 统计某个网关的 API 数量
bk-cli apigateway list_gateway_apis --gateway_name bk-iam | jq '.data | length'

# 列出 API 名称
bk-cli apigateway list_gateway_apis --gateway_name bk-iam | jq -r '.data[].name'

apigateway 子命令的 stdout 同样是结构化 JSON envelope，适合继续接 jq、shell pipeline 或其他自动化步骤。