Skip to main content

替换完整可信网络白名单

用提交的集合整体替换企业的可信网络白名单，数组中未包含的网段会被移除。带主机位的 CIDR 会被规整为网络地址，规整后重复的条目会被拒绝。

  • Scope：admin.v1.trusted-network.manage
  • 权限项：可信网络管理（trusted-network）
  • 权限类型：管理
  • 接口：PUT/api/openapi/v1/network-ranges

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。
名称位置类型必填说明示例
Authorizationheaderstring是应用 API Key，使用 Bearer 方式传递。Bearer qwk_***
X-Request-Idheaderstring否可选的调用追踪标识；未传入时由服务端生成。req-20260831-001

请求参数

名称位置类型必填说明示例
ip_whitelistbodyarray<string>必填IP addresses or CIDR ranges. CIDRs with host bits are normalized to their network address, preserving the prefix length (42.120.72.78/16 becomes 42.120.0.0/16). Duplicate normalized entries are rejected.["<string>"]
显式 ip_whitelist: [] 表示解除公网 IP 白名单限制；字段不能缺失或为 null。只提交名单，不提交 access_mode 或版本号，由中心检查当前模式；最多 100 条。

请求示例

curl --request PUT \
  --url 'https://example.invalid/api/openapi/v1/network-ranges' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "ip_whitelist": [
    "<string>"
  ]
}'

响应

200 OK

名称类型必填说明示例
successboolean是中心已保存名单并由 Operations 接受修改；不代表网关策略已经完成收敛。true
{
  "success": true
}
私网拒绝修改：HTTP 403 
{
  "error": "Forbidden",
  "detail": "The public IP whitelist cannot be modified in private mode",
  "code": "tenant_ip_whitelist_private_network"
}
模式无法确认：HTTP 503 / tenant_network_config_unavailable。其他上游故障仍返回 502；超时等结果不确定时，读取确认后再手动操作，不自动重试或补偿。

default Flat business error

名称类型必填说明示例
codestring否Stable business error code"<string>"
detailstring是Human-readable error description"<string>"
detailsOpenapiErrorDetails否错误详情-
errorstring是Stable HTTP error type"<string>"

details 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
fieldstring否校验失败的请求字段
reasonstring否校验失败的原因代码
suggestionstring否建议使用的规范化值
{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}