huawei-cloud-apig-instance-management

华为云 APIG API 网关管理

步骤 0：安装 skill-quality-cli（幂等操作；如果已安装则跳过）

CLI 会安装到 ~/.local/bin/，此目录不一定包含在 $PATH 中（直接运行 skill-quality-cli 可能会以 127 错误码退出）。请先导出路径，再运行安装程序（它也会将 PATH 导出语句写入 ~/.bashrc / ~/.profile）：

> **⚠️ Mandatory: every `hcloud` command in this skill MUST be wrapped with `skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- ` — bare `hcloud` calls are strictly forbidden.**

export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh

如果找不到 skill-quality-cli，脚本会将捆绑的 scripts/cli/ 源文件安装到 ~/.local/bin/（离线安装，无需外部下载）， 并将 PATH 导出语句写入 ~/.bashrc / ~/.profile；脚本不会阻塞。如果仍然找不到，请调用绝对路径：~/.local/bin/skill-quality-cli。

概述

此技能通过 hcloud CLI（KooCLI）管理华为云 APIG（API 网关）专享版实例及其资源。涵盖实例生命周期管理、API 分组、API 创建与更新、批量发布与下线、请求限流策略、签名密钥、访问控制（ACL）策略和公网入口 EIP 绑定，也提供对公网访问配置、发布链路和策略生效情况的只读诊断。

功能（24 个 huawei_* 操作）：

类别	级别	操作
查询	R3（只读，自动）	huawei_list_apig_instances、huawei_get_apig_instance、huawei_list_apig_api_groups、huawei_list_apig_apis、huawei_list_apig_throttling_policies、huawei_list_apig_signature_keys、huawei_list_apig_access_control_policies
分析	R3（只读，自动）	huawei_analyze_apig_public_access、huawei_analyze_apig_publish_chain、huawei_analyze_apig_policy_effect
管理	R2（预览 + 确认）	huawei_create_apig_instance、huawei_add_apig_ingress_eip、huawei_create_apig_api_group、huawei_create_apig_api、huawei_update_apig_api、huawei_publish_apig_api、huawei_create_apig_throttling_policy、huawei_create_apig_signature_key、huawei_create_apig_access_control_policy
管理（删除）	R1（预览 + 明确确认）	huawei_delete_apig_instance、huawei_delete_apig_api、huawei_delete_apig_api_group、huawei_delete_apig_signature_key、huawei_delete_apig_access_control_policy

此技能不涵盖以下操作（请使用华为云 APIG 控制台）： 应用凭据（应用/AppCode）、API 插件、API ACL 绑定、域名绑定、 API 分组更新/重命名，以及上述列表中未列出的其他 APIG 操作。 对于这些操作的请求，必须明确拒绝。

所有命令均严格使用 KooCLI APIG 帮助输出中列出的操作名称（例如，限流策略使用 RequestThrottlingPolicyV2 命名，而非 ThrottlingPolicyV2）。

依赖项：通过 skill-quality-cli 自动收集质量遥测数据（若该工具不存在，则由 scripts/ensure_cli.sh 安装）。

重要警告

#	陷阱	原因
1	API 组受区域限制	API 组无法跨区域迁移。请从一开始就在目标区域创建。
2	默认限流策略按 API 生效	默认限流策略按 API 生效。要限制每位用户的调用次数，请使用应用级配额（--app_call_limits）。
3	必须显式配置 CORS	在 API 上配置 CORS（--cors=true）之前，OPTIONS 预检请求会失败。
4	BASIC 规格没有公网 IP	要公开访问，请使用 PROFESSIONAL + --loadbalancer_provider=elb（lvs 仅供内部使用）。
5	实例创建需要 5-15 分钟	这是一个耗时较长的异步操作。最终状态为 Running（不是 "SUCCESS"）。使用 ListInstancesV2 轮询，并等待 status == "Running"。
6	sl_domain 来自 API 组	不是来自实例。请从 CreateApiGroupV2 / ListApiGroupsV2 响应中获取。这是仅供内部使用的域名，从公共互联网访问时可能会返回 NXDOMAIN——要公开访问，请使用实例的 eip_address。
7	API / 限流策略名称不得包含连字符	仅允许 [a-zA-Z0-9_]+。连字符会导致正则表达式验证失败（CreateRequestThrottlingPolicyV2 也已验证，APIG.2011）。
8	VPC 参数需要前缀	使用 KooCLI 7.x 时，请使用 --vpc.name=<n> / --subnet.vpc_id=<id> / --security_group.name=<n>。
9	AddIngressEipV2 仅适用于 elb 提供商	AddEipV2（不含 "Ingress"）要求使用 lvs 提供商。Ingress 带宽最低为 5 Mbit/s。
10	签名密钥类型有各自的值规则	hmac 密钥为 8-32 个字符 / 密钥为 16-64 个字符；aes 密钥长度取决于算法（aes-128-cfb=16，aes-256-cfb=32）。省略 --sign_key/--sign_secret 可让 APIG 自动生成。
11	绑定了 API 的 ACL 策略无法删除	策略仍绑定到 API 时，DeleteAclV2 会失败（APIG 错误）。请先解除绑定（在 APP/控制台中使用 BatchDeleteAclV2，即 R1 删除操作）。
12	ACL acl_value 的含义取决于 entity_type	对于 IP，它是 IP/白名单（最多 100 个，以逗号分隔）；对于 DOMAIN，它是账户名称（不是网站域名）。DOMAIN_ID 使用账户 ID。

前提条件

1. 已安装并完成身份验证的 hcloud CLI——请参阅 references/cli-installation-guide.md
2. 身份验证：通过环境变量设置 AK/SK（HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY，或任何包含访问密钥/密钥对的 HUAWEI*/HW* 变量对），或使用 configure 命令创建本地 KooCLI 配置文件
3. 区域：APIG 是区域专属服务。始终传入 --cli-region={region}（例如 cn-north-4、ap-southeast-1）；若省略，则使用配置文件中的区域。
4. IAM 权限——最小权限策略请参阅 references/iam-policies.md
5. 对不确定的操作执行前，始终使用 hcloud APIG <Operation> --help 查找参数。

• skill-quality-cli——由 bash scripts/ensure_cli.sh 确保已就绪（幂等，已存在时会跳过）
  • 升级：手动运行 skill-quality-cli upgrade（不会自动升级）
  • 禁用遥测报告：设置 SKILL_QUALITY_REPORT=0

工作流

1. Identify the target APIG instance (huawei_list_apig_instances / huawei_get_apig_instance)
2. Route by intent:
   ├── Query   → list instances / groups / APIs / throttling policies / signature keys / access control policies
   ├── Analyze → public access analysis (eip_address vs sl_domain), publish chain analysis, policy effect diagnosis
   ├── Manage  → create instance (poll to Running), add ingress EIP, create group/API,
   │             update API, publish API, create throttling policy / signature key / ACL policy
   │             (preview + confirm)
   └── Delete  → delete instance / API / API group / signature key / ACL policy
                 (empty group first, unbind ACL first; preview + explicit confirm, never automatic)
3. Return results: read-only actions return the command JSON; mutations return the
   resource snapshot read back after the operation completes

核心命令

命令命名：操作名称完全采用 KooCLI APIG 帮助枚举中的名称。 CLI 帮助中显示的服务名称为 APIG（KooCLI 元数据目录名为小写的 apig；两种形式均可接受）。

命令格式和执行规则。 下方首先以规范的裸格式 hcloud APIG <Operation> ... 展示每条命令——这是用于查找参数（--help）的语法，也是技能评估工具读取的格式——随后紧跟等效的 skill-quality-cli run 封装格式，供执行时使用。本技能执行的每条 hcloud 命令都必须使用 skill-quality-cli run 封装（强制规则——请参阅步骤 0 和前提条件中的 skill-quality-cli 条目）。封装程序不会添加参数，只会更改报告行为。

查询 — 实例

huawei_list_apig_instances — 列出 APIG 实例及其状态（包括 eip_address）：

# --limit / --offset are optional pagination filters (example values shown)
hcloud APIG ListInstancesV2 --cli-region={region} --limit=20 --offset=0
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --limit=20 --offset=0

参数	必填	描述
--cli-region	是（自动）	区域，由 Agent 自动填充
--limit	否	每页项目数，默认为 20（最大 500）
--offset	否	查询偏移量（默认为 0）
--status	否	按网关状态筛选，例如 Running、Creating、Deleting

huawei_get_apig_instance — 查询单个实例详情：

# Narrow to a single instance: add --instance_id=<your_instance_id> (a UUID)
hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id}

**结果为空表示未找到：**当实例不存在时，ListInstancesV2 会返回 {"total": 0, "instances": []}（退出码为 0，无错误）。请报告“实例不存在，请确认 instance_id”，而不要将其视为查询成功。

参数	必填	描述
--instance_id	否	网关 ID（传入该参数可将查询范围缩小到一个实例）

查询 — API 分组

huawei_list_apig_api_groups — 列出 API 分组（响应包含 sl_domain）：

hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --limit=20
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --limit=20

参数	必填	描述
--instance_id	是	网关 ID
--limit / --offset	否	分页
--name / --id	否	按分组名称 / ID 筛选

查询 — API

huawei_list_apig_apis — 列出实例中的 API：

# --group_id={group_id} optionally filters to a single API group
hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id} --limit=20
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id} --limit=20

参数	必填	描述
--instance_id	是	网关 ID
--group_id	否	按 API 分组 ID 筛选
--name / --id	否	按 API 名称 / ID 筛选
--req_method / --req_uri	否	按方法 / URI 筛选
--auth_type	否	按认证类型筛选（IAM/APP/NONE）

查询 — 限流策略

huawei_list_apig_throttling_policies — 列出请求限流策略 （操作名称以 KooCLI APIG 帮助枚举中的名称为准）：

hcloud APIG ListRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --limit=20
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --limit=20

参数	必填	描述
--instance_id	是	网关 ID
--name / --id	否	按策略名称 / ID 筛选
--limit / --offset	否	分页

查询 — 签名密钥

huawei_list_apig_signature_keys — 列出签名密钥 （操作名称以 KooCLI APIG 帮助枚举中的名称为准）：

hcloud APIG ListSignatureKeysV2 --cli-region={region} --instance_id={instance_id} --limit=20
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListSignatureKeysV2 --cli-region={region} --instance_id={instance_id} --limit=20

参数	必填	描述
--instance_id	是	网关 ID
--name / --id	否	按密钥名称 / ID 筛选
--limit / --offset	否	分页

查询 — 访问控制策略

huawei_list_apig_access_control_policies — 列出 ACL（访问控制）策略：

# --acl_type: PERMIT (whitelist) | DENY (blacklist); --entity_type: IP | DOMAIN
hcloud APIG ListAclStrategiesV2 --cli-region={region} --instance_id={instance_id} --limit=20
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListAclStrategiesV2 --cli-region={region} --instance_id={instance_id} --limit=20

参数	必填	描述
--instance_id	是	网关 ID
--acl_type	否	PERMIT（白名单）/ DENY（黑名单）
--entity_type	否	IP / DOMAIN（账户名称）
--name / --id	否	按策略名称 / ID 筛选
--limit / --offset	否	分页

分析 — 公网访问

huawei_analyze_apig_public_access — 分析实例是否可通过公网访问，以及应使用哪个地址：

hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id} --cli-output=json
hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --cli-output=json
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id} --cli-output=json
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id} --cli-output=json

参数	必填	描述
--instance_id	是	网关 ID

分析规则：如果 instances[].eip_address 是有效 IP，则实例具有公网入站入口，可使用该地址进行公网访问。如果它为 null，则实例仅供内部使用（BASIC 规格或 lvs 提供商）。API 分组中的 sl_domain 仅供内部使用（例如 *.apic.cn-north-4.huaweicloudapis.com），不得将其宣传为公网端点。

分析 — 发布链路

huawei_analyze_apig_publish_chain — 沿着实例 -> 分组 -> API -> 发布状态链路，定位已发布端点故障的环节：

hcloud APIG ListInstancesV2 --cli-region={region}
hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id}
hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id}
# Optional: add --group_id={group_id} to restrict the walk to a single API group
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApiGroupsV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id}

参数	必填	描述
--instance_id	是	网关 ID
--group_id	否	限定为一个 API 分组

报告缺失的环节（无实例 / 无分组 / 无 API / 无 publish_id）， 并在使用 sl_domain 而非 eip_address 进行公网访问时发出警告。

分析 — 策略生效情况

huawei_analyze_apig_policy_effect — 诊断签名密钥 / ACL / 限流策略是否实际生效（已绑定到已发布的 API）：

# Signature key: list APIs bound to a given signature key
hcloud APIG ListApisBindedToSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --sign_id={sign_id}
# ACL policy: list APIs bound to a given ACL policy
hcloud APIG ListApisBindedToAclPolicyV2 --cli-region={region} --instance_id={instance_id} --acl_id={acl_id}
# Throttling policy: list APIs bound to a given throttling policy
hcloud APIG ListApisBindedToRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --throttle_id={throttle_id}
# Then confirm each bound API is actually published (non-empty publish_id):
hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id} --id={api_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisBindedToSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --sign_id={sign_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisBindedToAclPolicyV2 --cli-region={region} --instance_id={instance_id} --acl_id={acl_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisBindedToRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --throttle_id={throttle_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListApisV2 --cli-region={region} --instance_id={instance_id} --id={api_id}

参数	必填	描述
--instance_id	是	网关 ID
--sign_id	是（签名生效情况）	ListSignatureKeysV2 返回的签名密钥 ID
--acl_id	是（ACL 生效情况）	ListAclStrategiesV2 返回的 ACL 策略 ID
--throttle_id	否（限流生效情况）	ListRequestThrottlingPolicyV2 返回的限流策略 ID
策略类型	否	signature（默认）/ acl / throttling — Agent 会选择匹配的绑定查询

策略生效规则：只有至少一个已绑定的 API 已发布（具有非空的 publish_id）， 策略才算生效。诊断故障路径：策略存在但没有已绑定的 API → 将其绑定到 API；已绑定但 API 未发布 → 发布 API；已绑定且已发布 → 策略已生效。 报告具体缺失环节，而不是给出泛泛的回答。

管理 — 创建实例（异步，轮询至 Running）

huawei_create_apig_instance — 创建按需计费的专属网关。 API 为异步操作：创建需要 5-15 分钟。轮询 ListInstancesV2 直至 status == "Running"：

# Run as a single line (no line continuations); always check CreateInstanceV2 --help first
hcloud APIG CreateInstanceV2 --cli-region={region} --instance_name={instance_name} --spec_id={spec_id} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --loadbalancer_provider={loadbalancer_provider} --available_zone_ids.1={available_zone_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateInstanceV2 --cli-region={region} --instance_name={instance_name} --spec_id={spec_id} --vpc_id={vpc_id} --subnet_id={subnet_id} --security_group_id={security_group_id} --loadbalancer_provider={loadbalancer_provider} --available_zone_ids.1={available_zone_id}

参数	必填	描述
--instance_name	否*	网关名称（用于识别实例）
--spec_id	否*	BASIC（无公网访问）/ PROFESSIONAL（通过 elb 提供公网访问）
--vpc_id / --subnet_id	否*	目标区域中的 VPC / 子网
--security_group_id	否*	安全组（需先通过 VPC 服务创建）
--loadbalancer_provider	否*	elb 表示公网访问，lvs 表示仅内部访问
--available_zone_ids.1	否*	AZ 代码，例如 ap-southeast-3a（不是 UUID）
--enterprise_project_id	否	企业账号必填；默认项目使用 "0"

*当前 KooCLI 元数据将 CreateInstanceV2 参数标记为可选，但 APIG API 在缺少 spec_id、vpc_id、subnet_id、 security_group_id、loadbalancer_provider 和 available_zone_ids 时会拒绝请求 — 始终传入这些参数。构建命令前，务必先检查 CreateInstanceV2 --help，确认参数名称。

创建后的轮询循环：

while true; do
  status=$(skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListInstancesV2 --cli-region={region} --instance_id={instance_id} --cli-output=json | jq -r '.instances[0].status')
  [ "$status" = "Running" ] && break
  echo "instance status: $status, waiting 60s..."; sleep 60
done

终止状态为 Running（不是 “SUCCESS”）。CreateSuccess 等状态属于 中间状态，表示实例仍在配置中。

管理 — 添加入口 EIP

huawei_add_apig_ingress_eip — 为 elb 提供商的网关启用公网入站访问（带宽最低为 5 Mbit/s）：

# --bandwidth_charging_mode: bandwidth|traffic; --bandwidth_size: Mbit/s (min 5)
hcloud APIG AddIngressEipV2 --cli-region={region} --instance_id={instance_id} --bandwidth_charging_mode=bandwidth --bandwidth_size=5
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG AddIngressEipV2 --cli-region={region} --instance_id={instance_id} --bandwidth_charging_mode=bandwidth --bandwidth_size=5

参数	必填	描述
--instance_id	是	网关 ID
--bandwidth_charging_mode	否	bandwidth 或 traffic
--bandwidth_size	否	入口带宽，单位为 Mbit/s（最低为 5）

绑定后的验证：ListInstancesV2 中的 eip_address 可能不会立即出现 （已验证：成功后 8 分钟仍为 null）— 不要将其作为唯一依据。请通过 AddIngressEipV2 响应/任务受理情况、重试时返回 APIC.7711（“已启用公网入站访问”） 或 APIG 控制台中的 EIP 列表确认成功。仅适用于 elb 提供商的实例。

管理 — 创建 API 分组

huawei_create_apig_api_group — 创建 API 分组：

# --remark={remark} is optional
hcloud APIG CreateApiGroupV2 --cli-region={region} --instance_id={instance_id} --name={name}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateApiGroupV2 --cli-region={region} --instance_id={instance_id} --name={name}

参数	必填	描述
--instance_id	是	网关 ID
--name	是	分组名称（3-255 个字符，以字母或数字开头）
--remark	否	描述

管理 — 创建 API

huawei_create_apig_api — 在分组中创建 API：

hcloud APIG CreateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}

参数	必填	描述
--instance_id	是	网关 ID
--group_id	是	API 分组 ID
--type	是	API 类型，例如 1（公开）
--name	是	API 名称 — 仅允许 [a-zA-Z0-9_]+，不允许连字符
--req_protocol	是	HTTPS / HTTP / BOTH
--req_method	是	GET / POST / PUT / DELETE / PATCH / HEAD / OPTIONS / ANY
--req_uri	是	请求 URI，例如 /demo
--auth_type	是	IAM / APP / NONE
--backend_type	是	HTTP / MOCK / FUNCTION / VPC_CHANNEL。**已知限制（KooCLI 7.2.12，已验证）：**通过 CreateApiV2 创建 HTTP 后端 API 时，所有合理的参数组合都会因 APIG.2011 invalid req_protocol 而失败，而 MOCK / FUNCTION 后端则可以成功创建。如果必须使用 HTTP 后端，请使用 APIG 控制台，或先创建使用 MOCK / FUNCTION 后端的 API，再在控制台中切换。
--backend_api.req_uri / --backend_api.req_method / --backend_api.url_domain	否	backend_type=HTTP 时的后端路由
--cors	否	需要 CORS 预检时设为 true

管理 — 更新 API

huawei_update_apig_api — 修改现有 API（认证模式、路径、后端等）：

hcloud APIG UpdateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --api_id={api_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG UpdateApiV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id} --api_id={api_id} --type={type} --name={name} --req_protocol={req_protocol} --req_method={req_method} --req_uri={req_uri} --auth_type={auth_type} --backend_type={backend_type}

参数	必填	描述
--api_id	是	API ID（来自 ListApisV2）
--instance_id / --group_id	是	在网关中定位 API
其余参数	是	与 CreateApiV2 的必填字段相同

管理 — 发布 / 下线 API

huawei_publish_apig_api — 批量发布或下线 API （操作为 BatchPublishOrOfflineApiV2；apis 是从 1 开始的数组）：

# 1) Get the real env ID first (RELEASE is only the environment NAME, NOT accepted); fill {env_id} / {api_id} from the query results:
hcloud APIG ListEnvironmentsV2 --cli-region={region} --instance_id={instance_id}
hcloud APIG BatchPublishOrOfflineApiV2 --cli-region={region} --instance_id={instance_id} --action=online --env_id={env_id} --apis.1={api_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG ListEnvironmentsV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG BatchPublishOrOfflineApiV2 --cli-region={region} --instance_id={instance_id} --action=online --env_id={env_id} --apis.1={api_id}

参数	必填	描述
--action	是	online（发布）/ offline（下线）
--env_id	是	环境 ID（不是名称）。先使用 hcloud APIG ListEnvironmentsV2 --cli-region={region} --instance_id={instance_id} 查询，并使用返回的 env_id — 名称 RELEASE 会被拒绝，并报错 APIG.3003。
--apis.1	是*	从 1 开始的 API ID 数组（最多 1000 个）。也可以改用 --group_id。
--group_id	否	发布 / 下线某个分组中的所有 API（apis 的替代方式）
--remark	否	描述

管理 — 创建限流策略

huawei_create_apig_throttling_policy — 创建请求限流策略 （操作名称以 KooCLI APIG 帮助枚举为准）：

hcloud APIG CreateRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --name={name} --time_unit={time_unit} --time_interval={time_interval} --api_call_limits={api_call_limits}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateRequestThrottlingPolicyV2 --cli-region={region} --instance_id={instance_id} --name={name} --time_unit={time_unit} --time_interval={time_interval} --api_call_limits={api_call_limits}

参数	必填	描述
--instance_id	是	网关 ID
--name	是	策略名称 — 仅允许 [a-zA-Z0-9_]+，不允许连字符（与 API 名称的限制相同，参见重要警告 7）
--time_unit	是	SECOND / MINUTE / HOUR / DAY
--time_interval	是	该单位下的时间间隔
--api_call_limits	是	间隔内的最大 API 调用次数
--app_call_limits	否	每个应用的配额（用于设置每个用户的限额）
--user_call_limits / --ip_call_limits	否	每个用户 / 每个 IP 的限额
--enable_adaptive_control	否	自适应限流（默认值为 false）

管理 — 创建签名密钥

huawei_create_apig_signature_key — 创建用于验证绑定 API 请求的签名密钥（R2：预览 + 确认）：

# [W] 写操作 (WRITE): creates a signature key — R2: preview + explicit confirmation required
# --sign_type: hmac (default) | basic | public_key | aes; --sign_key/--sign_secret auto-generated when omitted
hcloud APIG CreateSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --name={name}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --name={name}

参数	必填	描述
--instance_id	是	网关 ID
--name	是	密钥名称 — 字母/数字/下划线，必须以字母（或中文）开头
--sign_type	否	hmac（默认）/ basic / public_key / aes
--sign_key / --sign_secret	否	若未提供则自动生成；具体取值规则因类型而异（参见重要警告 10）
--sign_algorithm	否	aes-128-cfb / aes-256-cfb（仅适用于 aes 类型）

管理 — 创建访问控制策略

huawei_create_apig_access_control_policy — 创建 ACL 策略（按 IP 或账户名称设置白名单 / 黑名单）（R2：预览 + 确认）：

# [W] 写操作 (WRITE): creates an ACL policy — R2: preview + explicit confirmation required
# --acl_type: PERMIT (whitelist) | DENY (blacklist); --entity_type: IP | DOMAIN | DOMAIN_ID
hcloud APIG CreateAclStrategyV2 --cli-region={region} --instance_id={instance_id} --acl_name={name} --acl_type=PERMIT --entity_type=IP --acl_value={ip_addresses}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG CreateAclStrategyV2 --cli-region={region} --instance_id={instance_id} --acl_name={name} --acl_type=PERMIT --entity_type=IP --acl_value={ip_addresses}

参数	必填	描述
--instance_id	是	网关 ID
--acl_name	是	策略名称 — 3-64 个字符，以字母/数字开头（允许中文）
--acl_type	是	PERMIT（白名单）/ DENY（黑名单）
--entity_type	是	IP / DOMAIN（账户名称）/ DOMAIN_ID（账户 ID）
--acl_value	是	以逗号分隔；根据 entity_type 填写 IP（最多 100 个）或账户名称

删除 — 实例

huawei_delete_apig_instance — 删除专享网关（R1：运行前必须获得用户明确确认）：

# [W] 写操作 (WRITE) — IRREVERSIBLE: deletes a dedicated gateway — R1: explicit confirmation required
hcloud APIG DeleteInstancesV2 --cli-region={region} --instance_id={instance_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteInstancesV2 --cli-region={region} --instance_id={instance_id}

参数	必填	描述
--instance_id	是	要删除的网关 ID

删除 — API

huawei_delete_apig_api — 从分组中删除 API（R1：运行前必须获得用户明确确认）：

# [W] 写操作 (WRITE) — IRREVERSIBLE: deletes an API — R1: explicit confirmation required
# Note: DeleteApiV2 takes --api_id + --instance_id only (--group_id is NOT a
# parameter of this operation; verified against `hcloud APIG DeleteApiV2 --help`)
hcloud APIG DeleteApiV2 --cli-region={region} --instance_id={instance_id} --api_id={api_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteApiV2 --cli-region={region} --instance_id={instance_id} --api_id={api_id}

参数	必填	描述
--instance_id	是	网关 ID
--api_id	是	要删除的 API ID（来自 ListApisV2）

API 分组中仍包含 API 时，无法删除该分组（APIG.3415）。先使用此操作删除分组中的每个 API，然后再删除分组。

删除 — API 分组

huawei_delete_apig_api_group — 删除 API 分组（R1：运行前必须获得用户明确确认）：

# [W] 写操作 (WRITE) — IRREVERSIBLE: deletes an API group — R1: explicit confirmation required
hcloud APIG DeleteApiGroupV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteApiGroupV2 --cli-region={region} --instance_id={instance_id} --group_id={group_id}

参数	必填	描述
--instance_id	是	网关 ID
--group_id	是	要删除的 API 分组 ID

分组必须先清空： APIG 不允许删除仍包含 API 的分组（APIG.3415 The API group cannot be deleted because it contains APIs）。删除分组前，请使用 huawei_delete_apig_api（DeleteApiV2）删除分组中的所有 API。只有删除所有 API 后，DeleteApiGroupV2 才会成功。

删除 — 签名密钥

huawei_delete_apig_signature_key — 删除签名密钥（R1：运行前必须获得用户明确确认）。删除密钥也会删除其绑定关系 — 所有绑定该密钥的 API 都将失去签名验证：

# [W] 写操作 (WRITE) — IRREVERSIBLE: deletes a signature key — R1: explicit confirmation required
hcloud APIG DeleteSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --sign_id={sign_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteSignatureKeyV2 --cli-region={region} --instance_id={instance_id} --sign_id={sign_id}

参数	必填	描述
--instance_id	是	网关 ID
--sign_id	是	要删除的签名密钥 ID（来自 ListSignatureKeysV2）

删除 — 访问控制策略

huawei_delete_apig_access_control_policy — 删除 ACL 策略（R1：运行前必须获得用户明确确认）。该策略必须没有 API 绑定（否则 DeleteAclV2 会失败）：

# [W] 写操作 (WRITE) — IRREVERSIBLE: deletes an ACL policy — R1: explicit confirmation required
hcloud APIG DeleteAclV2 --cli-region={region} --instance_id={instance_id} --acl_id={acl_id}
skill-quality-cli run --skill-name huawei-cloud-apig-instance-management -- hcloud APIG DeleteAclV2 --cli-region={region} --instance_id={instance_id} --acl_id={acl_id}

参数	必填	描述
--instance_id	是	网关 ID
--acl_id	是	要删除的 ACL 策略 ID（来自 ListAclStrategiesV2）

如果 ACL 策略仍绑定了 API，DeleteAclV2 会返回错误。先解除 API 绑定（通过 APIG 控制台/BatchDeleteAclV2），然后重试删除。

参数确认

• 每条 huawei_* 命令执行前，都必须根据 hcloud APIG <Operation> --help 进行检查；本技能中的参数名称已根据 KooCLI 7.2.12 的输出进行验证。
• 必填与可选参数：始终传入 --cli-region（由 Agent 填写）。项目 ID（--project_id）会从配置文件或区域所属的父项目中自动解析。
• 变更操作（管理 R2 / 删除 R1）执行前，必须预览完整命令并征得用户确认；删除 R1 还需明确确认该资源将被永久删除。

KooCLI 命令格式标准

通用调用格式为 hcloud APIG <Operation> --cli-region=<region> [--key=value ...]——这仅用于说明格式：<...> 和 [...] 是占位符，绝不可原样执行。

特性	说明	示例
服务名称	APIG（CLI 帮助中显示的名称；元数据目录为 apig）	hcloud APIG ListInstancesV2 --cli-region={region}
操作名称	PascalCase，已根据 KooCLI APIG 帮助输出进行验证	ListInstancesV2
区域	--cli-region=<value>	--cli-region=cn-north-4
简单参数	--key=value	--instance_id=xxx
索引数组参数	--key.N=value（从 1 开始）	--apis.1=xxx
嵌套对象参数	--key.sub=value	--backend_api.req_uri=/demo

工具参数验证（必需）

执行前验证每个参数；非法输入将直接拒绝（绝不传递给 hcloud）：

验证项	规则
枚举白名单	已记录的取值集合（--cli-region、--status、--spec、--loadbalancer_provider、--protocol 等）必须完全匹配；其他任何取值 → 拒绝并列出允许的取值
类型检查	数值参数（--limit、--offset、--bandwidth、--port）必须可解析为整数；名称/ID 参数必须是匹配 [a-zA-Z0-9_-]+ 的字符串（不含连字符，参见关键警告 #7）
拒绝未知参数	hcloud APIG <Operation> --help 中未列出的参数必须在运行命令前拒绝

参考文档

• references/cli-installation-guide.md — KooCLI 安装与身份验证
• references/iam-policies.md — APIG 的最小权限 IAM 策略
• references/verification-method.md — 各项操作的验证方法
• references/dataflow-diagram.md — Mermaid 数据流图
• references/acceptance-criteria.md — 本技能的验收标准

APIG 文档：https://support.huaweicloud.com/apig/