cdnca

开放接口

/v1/firewall-actions

3 个接口

← 全部分组 · 第一次调用？先看教程：认证、权限、请求与响应、常见失败

方法路径摘要认证
GET/v1/firewall-actions/policyRead the desired, active, and last-known-good firewall action policy登录会话
PUT/v1/firewall-actions/policyCreate the next immutable firewall action policy candidate登录会话
POST/v1/firewall-actions/policy/recoverCreate a monotonic recovery candidate from the last-known-good policy登录会话

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

接口详情

GET /v1/firewall-actions/policy

Read the desired, active, and last-known-good firewall action policy

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

全部需要：firewall.read

参数

getFirewallActionPolicy 参数
名称位置类型必填说明
target_scope_idquerystring(uuid)是—
site_idquerystring(uuid)是—

响应

getFirewallActionPolicy 响应
状态码说明
200Desired, active, and LKG state

字段：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time)

401Authentication required
403Permission denied
404Policy absent or outside actor scope

失败时怎么办

  • 401 检查凭据格式、是否过期或被轮换。
  • 403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。
  • 404 资源不存在或不属于当前租户。

↑ 回到列表

PUT /v1/firewall-actions/policy

Create the next immutable firewall action policy candidate

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

全部需要：firewall.manage

参数

putFirewallActionPolicy 参数
名称位置类型必填说明
target_scope_idquerystring(uuid)是—
site_idquerystring(uuid)是—
If-Matchheaderstring是—
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring(uuid)是—

请求体

application/json · 必填：是

putFirewallActionPolicy 请求体
名称类型必填说明
normal_actionstring: disconnect / return_page是—
escalated_actionstring: nftables是—
engage_thresholdinteger是—
recover_thresholdinteger是—
recovery_windowsinteger是—
block_networksarray<string>是—
trusted_proxiesarray<string>是—
trusted_crawlersarray<TrustedCrawler>是—
return_pageReturnPage是—

响应

putFirewallActionPolicy 响应
状态码说明
200Immutable candidate accepted for publication

字段：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time)

400Invalid policy or request metadata
401Authentication required
403Permission denied
409Revision, idempotency, or LKG conflict

失败时怎么办

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

↑ 回到列表

POST /v1/firewall-actions/policy/recover

Create a monotonic recovery candidate from the last-known-good policy

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

全部需要：firewall.manage

说明（契约原文）

Creates a new monotonic candidate from the durable last-known-good document; it never rewinds revisions.

参数

recoverFirewallActionLKG 参数
名称位置类型必填说明
target_scope_idquerystring(uuid)是—
site_idquerystring(uuid)是—
If-Matchheaderstring是—
Idempotency-Keyheaderstring是—
X-Request-IDheaderstring(uuid)是—

请求体

application/json · 必填：是

响应

recoverFirewallActionLKG 响应
状态码说明
200LKG recovery candidate accepted

字段：normal_action: string: disconnect / return_page escalated_action: string: nftables engage_threshold: integer recover_threshold: integer recovery_windows: integer block_networks: array<string> trusted_proxies: array<string> trusted_crawlers: array<TrustedCrawler> return_page: ReturnPage id: string(uuid) tenant_scope_id: string(uuid) site_id: string(uuid) revision: integer active_revision: integer lkg_revision: integer deployment_state: string: pending / active / failed host_escalation: string: owned / shared_unsupported document_sha256: string created_at: string(date-time) updated_at: string(date-time)

400Invalid policy or request metadata
401Authentication required
403Permission denied
409Revision, idempotency, or LKG conflict

失败时怎么办

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

↑ 回到列表