开放接口

`/v1/regions`

6 个接口

方法	路径	摘要	认证
GET	`/v1/regions`	List platform regions	登录会话
POST	`/v1/regions`	Create a platform region	登录会话
GET	`/v1/regions/{id}`	Get a platform region	登录会话
PUT	`/v1/regions/{id}`	—	登录会话
PATCH	`/v1/regions/{id}`	Replace the editable fields of a platform region	登录会话
DELETE	`/v1/regions/{id}`	Delete an unused platform region	登录会话

契约文件：api/control-regions.openapi.yaml

接口详情

GET `/v1/regions`

List platform regions

operationId

listPlatformRegions

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：regions.read

参数

listPlatformRegions 参数
名称	位置	类型	必填	说明
`limit`	query	`integer`	否	Legacy selector mode. Zero returns the complete platform catalog and cannot be combined with page or page_size.
`page`	query	`integer`	否	Table page number. Enables paginated mode together with page_size.
`page_size`	query	`integer`	否	Table page size. Enables paginated mode together with page.
`search`	query	`string`	否	Literal case-insensitive match against name and description.

响应

listPlatformRegions 响应
状态码	说明
`200`	Stable list ordered by sort value and immutable short ID 字段：`count: integer(int64)` `data: array<Region>`
`400`	Request validation failed (regions_validation_error)
`401`	Authentication is required (regions_unauthenticated)
`403`	Required region permission is missing (regions_permission_denied)
`503`	Region catalog is unavailable (regions_unavailable)

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

POST `/v1/regions`

Create a platform region

operationId

createPlatformRegion

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：regions.manage

参数

createPlatformRegion 参数
名称	位置	类型	必填	说明
`Idempotency-Key`	header	`string`	是	—

请求体

application/json · 必填：是

createPlatformRegion 请求体
名称	类型	必填	说明
`name`	`string`	是	—
`country_code`	`string`	否	ISO 3166-1 alpha-2 country code, "" = not set (market conditional origins map node regions by it).
`province_code`	`string`	否	GB/T 2260 province-level code, only with country_code CN; "" = whole country / not set.
`description`	`string`	是	—
`l2_check_port`	`integer`	是	—
`sort`	`integer`	是	—

响应

createPlatformRegion 响应
状态码	说明
`201`	Region created or an exact completed request replayed 字段：`id: string` `name: string` `code: string` `country_code: string` `province_code: string` `description: string` `l2_check_port: integer` `sort: integer` `revision: integer(int64)` `created_at: string(date-time)` `updated_at: string(date-time)`
`400`	Request validation failed (regions_validation_error)
`401`	Authentication is required (regions_unauthenticated)
`403`	Required region permission is missing (regions_permission_denied)
`409`	Region name
`503`	Region catalog is unavailable (regions_unavailable)

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

GET `/v1/regions/{id}`

Get a platform region

operationId

getPlatformRegion

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：regions.read

参数

getPlatformRegion 参数
名称	位置	类型	必填	说明
`id`	path	`string`	是	—

响应

getPlatformRegion 响应
状态码	说明
`200`	Current region 字段：`id: string` `name: string` `code: string` `country_code: string` `province_code: string` `description: string` `l2_check_port: integer` `sort: integer` `revision: integer(int64)` `created_at: string(date-time)` `updated_at: string(date-time)`
`400`	Request validation failed (regions_validation_error)
`401`	Authentication is required (regions_unauthenticated)
`403`	Required region permission is missing (regions_permission_denied)
`404`	Region does not exist (regions_not_found)
`503`	Region catalog is unavailable (regions_unavailable)

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
404 资源不存在或不属于当前租户。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

PUT `/v1/regions/{id}`

operationId

replacePlatformRegion

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

契约没有单独标注权限码，权限要求见下方说明与 403 响应。

参数

replacePlatformRegion 参数
名称	位置	类型	必填	说明
`id`	path	`string`	是	—

↑ 回到列表

PATCH `/v1/regions/{id}`

Replace the editable fields of a platform region

operationId

updatePlatformRegion

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：regions.manage

参数

updatePlatformRegion 参数
名称	位置	类型	必填	说明
`id`	path	`string`	是	—
`If-Match`	header	`string`	是	Exact strong ETag revision read from the current region.
`Idempotency-Key`	header	`string`	是	—

请求体

application/json · 必填：是

updatePlatformRegion 请求体
名称	类型	必填	说明
`name`	`string`	是	—
`country_code`	`string`	否	ISO 3166-1 alpha-2 country code, "" = not set (market conditional origins map node regions by it).
`province_code`	`string`	否	GB/T 2260 province-level code, only with country_code CN; "" = whole country / not set.
`description`	`string`	是	—
`l2_check_port`	`integer`	是	—
`sort`	`integer`	是	—

响应

updatePlatformRegion 响应
状态码	说明
`200`	Region updated or an exact completed request replayed 字段：`id: string` `name: string` `code: string` `country_code: string` `province_code: string` `description: string` `l2_check_port: integer` `sort: integer` `revision: integer(int64)` `created_at: string(date-time)` `updated_at: string(date-time)`
`400`	Request validation failed (regions_validation_error)
`401`	Authentication is required (regions_unauthenticated)
`403`	Required region permission is missing (regions_permission_denied)
`404`	Region does not exist (regions_not_found)
`409`	Region name
`412`	Region revision changed (regions_revision_conflict)
`428`	If-Match is required (regions_precondition_required)
`503`	Region catalog is unavailable (regions_unavailable)

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
404 资源不存在或不属于当前租户。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

DELETE `/v1/regions/{id}`

Delete an unused platform region

operationId

deletePlatformRegion

认证

登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。

所需权限

全部需要：regions.manage

参数

deletePlatformRegion 参数
名称	位置	类型	必填	说明
`id`	path	`string`	是	—
`If-Match`	header	`string`	是	Exact strong ETag revision read from the current region.
`Idempotency-Key`	header	`string`	是	—

响应

deletePlatformRegion 响应
状态码	说明
`204`	Region deleted or an exact completed request replayed
`400`	Request validation failed (regions_validation_error)
`401`	Authentication is required (regions_unauthenticated)
`403`	Required region permission is missing (regions_permission_denied)
`404`	Region does not exist (regions_not_found)
`409`	Region name
`412`	Region revision changed (regions_revision_conflict)
`428`	If-Match is required (regions_precondition_required)
`503`	Region catalog is unavailable (regions_unavailable)

失败时怎么办

400 按字段说明修正参数或请求体再发；不要原样重试。
401 检查凭据格式、是否过期或被轮换。
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
404 资源不存在或不属于当前租户。
409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
428 缺少前置条件：回读资源，带 If-Match（或页面要求的验证）再提交。
503 依赖暂不可用：稍后用原 Idempotency-Key 重试。

↑ 回到列表

/v1/regions

接口详情

GET /v1/regions

参数

响应

失败时怎么办

POST /v1/regions

参数

请求体

响应

失败时怎么办

GET /v1/regions/{id}

参数

响应

失败时怎么办

PUT /v1/regions/{id}

参数

PATCH /v1/regions/{id}

参数

请求体

响应

失败时怎么办

DELETE /v1/regions/{id}

参数

响应

失败时怎么办

`/v1/regions`

GET `/v1/regions`

POST `/v1/regions`

GET `/v1/regions/{id}`

PUT `/v1/regions/{id}`

PATCH `/v1/regions/{id}`

DELETE `/v1/regions/{id}`