接口详情
GET /v1/admin/package-groups
List package catalog groups
- operationId
listPackageGroups- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. Unknown or repeated query parameters are rejected.
响应
listPackageGroups 响应| 状态码 | 说明 |
|---|
200 | All active groups ordered by sort order and then name. 字段：items: array<PackageGroup> total: integer(int64) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/package-groups
Create a package catalog group
- operationId
createPackageGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. The same idempotency key and normalized input replay the original response; a changed input returns idempotency_conflict, and a duplicate active name returns package_name_conflict.
参数
createPackageGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
createPackageGroup 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
name | string | 是 | — |
|---|
visible | boolean | 是 | Whether the group is shown in package selection surfaces. |
|---|
sort_order | integer | 是 | — |
|---|
响应
createPackageGroup 响应| 状态码 | 说明 |
|---|
201 | Group created, or an identical idempotent request replayed. 字段：id: string(uuid) owner_scope_id: string(uuid) name: string visible: boolean sort_order: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
PATCH /v1/admin/package-groups/{id}
Replace package group fields using optimistic concurrency
- operationId
updatePackageGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. expected_revision is checked atomically; stale input returns version_conflict. An identical idempotent request replays the original response.
参数
updatePackageGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
updatePackageGroup 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
expected_revision | integer(int64) | 是 | — |
|---|
name | string | 是 | — |
|---|
visible | boolean | 是 | Whether the group is shown in package selection surfaces. |
|---|
sort_order | integer | 是 | — |
|---|
响应
updatePackageGroup 响应| 状态码 | 说明 |
|---|
200 | Group fields replaced and revision incremented, or an identical request replayed. 字段：id: string(uuid) owner_scope_id: string(uuid) name: string visible: boolean sort_order: integer revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表
DELETE /v1/admin/package-groups/{id}
Soft-delete an unused package group
- operationId
deletePackageGroup- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
Requires packages.manage in the platform scope, or reseller.packages.manage in an active reseller tenant scope; each scope sees and changes only the groups and packages it owns (owner_scope_id), and another owner's package returns permission_denied. If-Match supplies the expected revision. A group referenced by an active package returns package_group_in_use; a stale revision returns version_conflict.
参数
deletePackageGroup 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
id | path | string(uuid) | 是 | Package group or package product UUID. |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
响应
deletePackageGroup 响应| 状态码 | 说明 |
|---|
204 | Group soft-deleted, or an identical idempotent request replayed. |
|---|
400 | 请求体或参数不合法。 |
|---|
401 | 认证失败或会话已失效。 |
|---|
403 | 当前身份没有执行该操作的权限。 |
|---|
404 | 请求的资源不存在。 |
|---|
409 | 请求的状态与已有资源或幂等记录冲突。 |
|---|
500 | 服务内部故障，请求未完成。 |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。500 结果未知：先按资源 ID 或列表回读确认，再决定是否用原 Idempotency-Key 重试。
↑ 回到列表