API 參考

CSD 提供專用 API，路徑為 /api/shape/csd/，用於管理網域、腳本、緩解措施及監控。CSD 也可透過負載平衡器設定 API 在 HTTP 負載平衡器上啟用。

驗證

所有 API 呼叫均需要 API 權杖。請在 XC Console 的 Administration → Credentials → API Credentials 中產生。

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 設定

CSD JavaScript 注入也可透過設定 API 直接在 HTTP 負載平衡器上啟用，路徑為 /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}。

負載平衡器規格中的 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 — Console 設定指南
API 憑證 — 產生 API 權杖