方法路径摘要认证
GET/v1/site-defaults网站列表 > 默认设置 (the caller's defaults for new sites)登录会话
POST/v1/site-defaultsAdd a site default登录会话
PATCH/v1/site-defaults/{id}Change a site default's value or enable / disable it登录会话
DELETE/v1/site-defaults/{id}Delete a site default登录会话

契约文件:api/openapi/v1/sites.yaml

接口详情

GET /v1/site-defaults

网站列表 > 默认设置 (the caller's defaults for new sites)

operationId
listSiteDefaults
认证
  • 登录会话:主控登录后的 Bearer 会话,由客户本人在自己的主控里使用;插件不能要求客户交出会话。
所需权限

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

说明(契约原文)

Requires sites.read. A tenant sees only its own scope. Defaults fill the fields a new site's create request leaves out; group rows win over global ones; existing sites are never changed.

参数

listSiteDefaults 参数
名称位置类型必填说明
pagequeryinteger否—
limitqueryinteger否—
setting_namequerystring否—
enabledqueryboolean否—

响应

listSiteDefaults 响应
状态码说明
200One page.

字段:items: array<SiteUserDefault> total: integer(int64) page: integer limit: integer

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
500The operation failed without exposing internal details.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发;不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域;不要换更高权限账号绕过。
  • 500 结果未知:先按资源 ID 或列表回读确认,再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

POST /v1/site-defaults

Add a site default

operationId
createSiteDefault
认证
  • 登录会话:主控登录后的 Bearer 会话,由客户本人在自己的主控里使用;插件不能要求客户交出会话。
所需权限

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

说明(契约原文)

Requires sites.manage and Idempotency-Key. 409 site_default_conflict: the setting already has a default in the same scope (global, or the same group).

参数

createSiteDefault 参数
名称位置类型必填说明
Idempotency-Keyheaderstring是Stable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

请求体

application/json · 必填:是

createSiteDefault 请求体
名称类型必填说明
target_scope_idstring(uuid)否platform only
owner_idstring(uuid)否platform only
setting_namestring是Ports are space separated; balance_way is round_robin, ip_hash, url_hash, least_conn or random; backend_https_port 1-65535; ups_keepalive_timeout seconds 1-300; cc_ban_seconds 1-86400 and cc_pass_seconds 60-604800 (filled into a new CC policy that names none); dns_provider is the ID of a verified DNS account of the scope (checked when saved; a create that names none uses it when the creator has dns.manage, and skips the records if it is no longer usable); cc_policy, waf_policy and acl_policy are the ID of one of the owner's own rule libraries of that kind (not a subscribed one; checked when saved), copied into a library of the new site's own and bound to it in the create (later changes of the library or the default leave existing sites alone; a library gone by then, or a package without the feature, skips the copy); block_proxy 1 adds rules blocking requests with a Via, X-Forwarded-For or Forwarded header to the new site's WAF library (identified by proxy headers: users behind a corporate proxy are blocked too); req_header is one "Name: value" per line (up to 8192 characters), set on requests to the origin; post_size_limit is the upload limit in MB 1-1024 (client_max_body_size). req_header and post_size_limit become the new site's HTTP policy when the creator has http_policies.manage; http2, http3 and ssl_prefer_server_ciphers fill the new site's http2_enabled, http3_enabled and tls_prefer_server_ciphers; proxy_cache is a cache policy document (JSON, the document of /v1/cache-policies/{site_id}; up to 65536 characters) written as the new site's first cache policy revision in the create; cond_origin is {"routes": [...]} of conditional origin rules (as the site's conditional origin document) whose pool_id is the placeholder "@default", replaced by the new site's own default origin pool (no origin addresses are stored); block_region is abrord_inc (block outside mainland China, Hong Kong, Macao and Taiwan included), abrord_no_inc (outside CN/HK/MO/TW), china_inc (CN, HK, MO and TW), china_not_inc (CN only) or none, the competitor's values: a preset adds one WAF rule on the client's country (by the node's IP intelligence library) to the new site's WAF library as block_proxy does, none adds nothing; ssl_cipher_preset is modern, compatible, legacy or custom; ssl_cipher_suites is the custom preset's colon-separated suite list (the same whitelist and rules as the site's tls_cipher_suites), and a custom ssl_cipher_preset applies to a new site only together with it; the rest are 1 (on) or 0 (off).
setting_valuestring是at most 256, req_header 8192, proxy_cache and cond_origin 65536
scope_namestring: global / group否—
group_idstring(uuid) | null(uuid)否required when scope_name is group

响应

createSiteDefault 响应
状态码说明
201Created.

字段:id: string(uuid) display_id: string scope_id: string(uuid) owner_user_id: string(uuid) setting_name: string setting_value: string scope_name: string: global / group group_id: string(uuid) | null(uuid) group_name: string | null enabled: boolean version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
409Domain, version, idempotency, website lock-state, or origin-section conflict.
500The operation failed without exposing internal details.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发;不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域;不要换更高权限账号绕过。
  • 409 先回读资源当前状态;同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知:先按资源 ID 或列表回读确认,再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

PATCH /v1/site-defaults/{id}

Change a site default's value or enable / disable it

operationId
updateSiteDefault
认证
  • 登录会话:主控登录后的 Bearer 会话,由客户本人在自己的主控里使用;插件不能要求客户交出会话。
所需权限

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

说明(契约原文)

Requires sites.manage and Idempotency-Key; another tenant's ID is 404.

参数

updateSiteDefault 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

请求体

application/json · 必填:是

updateSiteDefault 请求体
名称类型必填说明
expected_versioninteger(int64)是—
setting_valuestring否at most 256, req_header 8192, proxy_cache and cond_origin 65536
enabledboolean否—

响应

updateSiteDefault 响应
状态码说明
200Updated.

字段:id: string(uuid) display_id: string scope_id: string(uuid) owner_user_id: string(uuid) setting_name: string setting_value: string scope_name: string: global / group group_id: string(uuid) | null(uuid) group_name: string | null enabled: boolean version: integer(int64) created_at: string(date-time) updated_at: string(date-time)

400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
404The site is absent, deleted, or outside the tenant scope.
409Domain, version, idempotency, website lock-state, or origin-section conflict.
500The operation failed without exposing internal details.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发;不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域;不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 409 先回读资源当前状态;同一操作重试保持原 Idempotency-Key 和原请求内容。
  • 500 结果未知:先按资源 ID 或列表回读确认,再决定是否用原 Idempotency-Key 重试。

↑ 回到列表

DELETE /v1/site-defaults/{id}

Delete a site default

operationId
deleteSiteDefault
认证
  • 登录会话:主控登录后的 Bearer 会话,由客户本人在自己的主控里使用;插件不能要求客户交出会话。
所需权限

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

说明(契约原文)

Requires sites.manage and Idempotency-Key; another tenant's ID is 404.

参数

deleteSiteDefault 参数
名称位置类型必填说明
idpathstring(uuid)是—
Idempotency-Keyheaderstring是Stable per-actor key. Reuse with different normalized input returns 409 idempotency_conflict.

响应

deleteSiteDefault 响应
状态码说明
204Deleted.
400Invalid JSON, field, or query input.
401Authentication is required.
403The principal lacks sites.read or sites.manage.
404The site is absent, deleted, or outside the tenant scope.
500The operation failed without exposing internal details.

失败时怎么办

  • 400 按字段说明修正参数或请求体再发;不要原样重试。
  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域;不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。
  • 500 结果未知:先按资源 ID 或列表回读确认,再决定是否用原 Idempotency-Key 重试。

↑ 回到列表