API 参考

CSD 在 /api/shape/csd/ 提供了专用 API，用于管理域名、脚本、缓解措施和监控。也可以通过负载均衡器配置 API 在 HTTP 负载均衡器上启用 CSD。

认证

所有 API 调用均需要 API 令牌。请在 XC 控制台的 Administration → Credentials → API Credentials 中生成令牌。

按照 API 自动化 — 环境配置中的说明设置您的环境变量：

set -a && source .env && set +a

所有 curl 示例均使用 xTOKENx 占位符格式。请替换为您的环境变量，或使用页面顶部的交互式表单。例如，xF5XC_API_TOKENx 对应 $F5XC_API_TOKEN。

-H "Authorization: APIToken xF5XC_API_TOKENx"

API 约定

响应体

POST 以 JSON 格式返回已创建的对象。
PUT 和 DELETE 在 HTTP 200 时返回空的 \{\} — 这是正常现象，并非错误。请勿将空响应体视为失败。

列表端点与 GET 端点

列表端点（如 /healthchecks、/origin_pools、/protected_domains）与单个 GET 端点（如 /healthchecks/\{name\}）返回不同的响应结构：

端点类型	示例路径	响应结构
列表	`/origin_pools`	条目具有顶层 `.name`、`.namespace`、`.tenant`，`metadata: null` 和 `get_spec: null`
单个 GET	`/origin_pools/\{name\}`	对象具有 `.metadata.name`、`.spec.*` 以及完整配置

请针对每种情况使用正确的 jq 路径。例如，从列表端点提取名称时，请使用 .items[].name，而非 .items[].metadata.name。

受保护域名标识符

对于受保护域名的 GET 和 DELETE 操作，路径参数 \{name\} 是域名值本身（例如 bankexample.com），而非任意对象名称。这与其他 F5 XC 对象不同，后者的名称是用户自定义的标识符。

CSD API 端点

基础路径：/api/shape/csd/namespaces/\{namespace\}/

状态与初始化

操作	方法	路径
启用 CSD	`POST`	`/api/shape/csd/namespaces/system/init`
获取状态	`GET`	`/api/shape/csd/namespaces/\{namespace\}/status`
获取 JS 配置	`GET`	`/api/shape/csd/namespaces/\{namespace\}/js_configuration`
测试 JS	`POST`	`/api/shape/csd/namespaces/\{namespace\}/testjs`
更新域名	`POST`	`/api/shape/csd/namespaces/\{namespace\}/update_domains`

受保护域名

操作	方法	路径
列表	`GET`	`/api/shape/csd/namespaces/\{namespace\}/protected_domains`
获取	`GET`	`/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}`
创建	`POST`	`/api/shape/csd/namespaces/\{namespace\}/protected_domains`
删除	`DELETE`	`/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}`

已检测域名

操作	方法	路径
列出已检测域名	`GET`	`/api/shape/csd/namespaces/\{namespace\}/detected_domains`
获取详情	`GET`	`/api/shape/csd/namespaces/\{namespace\}/domain_details`

允许的域名

操作	方法	路径
列表	`GET`	`/api/shape/csd/namespaces/\{namespace\}/allowed_domains`
获取	`GET`	`/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}`
创建	`POST`	`/api/shape/csd/namespaces/\{namespace\}/allowed_domains`
删除	`DELETE`	`/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}`

已缓解域名

操作	方法	路径
列表	`GET`	`/api/shape/csd/namespaces/\{namespace\}/mitigated_domains`
获取	`GET`	`/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}`
创建	`POST`	`/api/shape/csd/namespaces/\{namespace\}/mitigated_domains`
删除	`DELETE`	`/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}`

脚本

操作	方法	路径
列出脚本	`POST`	`/api/shape/csd/namespaces/\{namespace\}/scripts`
列出脚本（旧版）	`GET`	`/api/shape/csd/namespaces/\{namespace\}/scripts`
获取脚本概览	`GET`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard`
列出行为	`GET`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors`
列出网络交互	`GET`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions`
更新说明	`POST`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification`
删除说明	`DELETE`	`/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}`
更新已读状态	`POST`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus`
列出受影响用户	`POST`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers`

表单字段

操作	方法	路径
列出表单字段	`GET`	`/api/shape/csd/namespaces/\{namespace\}/formFields`
列出表单字段（POST）	`POST`	`/api/shape/csd/namespaces/\{namespace\}/formFields`
获取表单字段	`GET`	`/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}`
按脚本列出	`GET`	`/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields`
更新字段分析	`POST`	`/api/shape/csd/namespaces/\{namespace\}/formFields/analysis`

启用 CSD

为租户初始化 CSD：

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/system/init"

获取 CSD 状态

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/status" \
  | jq .

受保护域名

列出受保护域名

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

添加受保护域名

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "my-app",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

删除受保护域名

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains/my-app"

已检测域名

列出已检测域名

查询参数：locations（按位置过滤）、risk（按风险级别过滤）。

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains" \
  | jq .

按高风险过滤：

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains?risk=high" \
  | jq .

获取域名详情

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/domain_details?name=suspicious.example.com" \
  | jq .

脚本

列出所有脚本

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts" \
  | jq .

获取脚本概览

SCRIPT_ID="your-script-id"

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/dashboard" \
  | jq .

列出脚本行为

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/behaviors" \
  | jq .

列出网络交互

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/networkInteractions" \
  | jq .

缓解措施

添加已缓解域名

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "blocked-domain",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

列出已缓解域名

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

移除缓解措施

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains/blocked-domain"

允许的域名

添加允许的域名

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "trusted-cdn",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

列出允许的域名

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

移除允许的域名

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains/trusted-cdn"

JS 注入配置

获取当前配置

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/js_configuration" \
  | jq .

HTTP 负载均衡器 CSD 配置

也可以通过 /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\} 上的配置 API，直接在 HTTP 负载均衡器上启用 CSD JavaScript 注入。

负载均衡器规格中的 client_side_defense 字段用于控制注入：

{
  "client_side_defense": {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
}

policy 接受以下之一：

字段	描述
`js_insert_all_pages`	在所有页面上注入
`js_insert_all_pages_except`	在所有页面上注入，排除规则中指定的页面除外
`js_insertion_rules`	仅在匹配规则的页面上注入
`disable_js_insert`	不注入

如需在负载均衡器上禁用 CSD，请将 client_side_defense 替换为 disable_client_side_defense: \{\}。

从负载均衡器读取 CSD 配置

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

在负载均衡器上启用 CSD

检索、修改并应用：

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  > lb-config.json

jq '.spec |= (
  del(.disable_client_side_defense) |
  .client_side_defense = {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
)' lb-config.json > lb-config-updated.json

curl -s -X PUT \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d @lb-config-updated.json \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

排除规则的域名和路径匹配

使用 js_insert_all_pages_except 或 js_insertion_rules 时，每条规则匹配域名与路径的组合。

域名（选择其一）：

字段	示例
`any_domain: \{\}`	所有域名
`domain.exact_value`	`"app.example.com"`
`domain.suffix_value`	`".example.com"`
`domain.regex_value`	`".*\\.example\\.com"`

路径（选择其一）：

字段	示例
`path.path`	`"/login"`
`path.prefix`	`"/checkout"`
`path.regex`	`"/user/[0-9]+"`

API 参考

CSD API 参考 — 完整端点文档
配置 CSD — 控制台配置指南
API 凭据 — 生成 API 令牌