อ้างอิง API

CSD มี API เฉพาะที่ /api/shape/csd/ สำหรับการจัดการโดเมน สคริปต์ การบรรเทาภัยคุกคาม และการตรวจสอบ นอกจากนี้ CSD ยังสามารถเปิดใช้งานบน HTTP Load Balancers ผ่าน API การกำหนดค่า load balancer ได้ด้วย

การยืนยันตัวตน

การเรียก API ทั้งหมดต้องใช้ API token สร้าง token ได้ใน XC Console ภายใต้ การบริหาร → Credentials → API Credentials

ตั้งค่าตัวแปรสภาพแวดล้อมของคุณตามที่อธิบายไว้ใน การทำงานอัตโนมัติ API — การตั้งค่าสภาพแวดล้อม:

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

ตัวอย่าง curl ทั้งหมดใช้รูปแบบ placeholder xTOKENx แทนที่ด้วยตัวแปรสภาพแวดล้อมของคุณหรือใช้ฟอร์มแบบโต้ตอบที่ด้านบนของหน้า ตัวอย่างเช่น xF5XC_API_TOKENx ตรงกับ $F5XC_API_TOKEN

-H "Authorization: APIToken xF5XC_API_TOKENx"

แนวปฏิบัติของ API

หมายเหตุ

แนวปฏิบัติเหล่านี้ใช้กับ endpoint การกำหนดค่า F5 Distributed Cloud (F5 XC) และ CSD API ทั้งหมด การทำความเข้าใจแนวปฏิบัติเหล่านี้ช่วยป้องกันข้อผิดพลาดที่พบบ่อยในการทำงานอัตโนมัติ

Response Bodies

• POST คืนค่าออบเจ็กต์ที่สร้างขึ้นเป็น JSON
• PUT และ DELETE คืนค่า \{\} ว่างเปล่าเมื่อ HTTP 200 — นี่เป็นเรื่องปกติ ไม่ใช่ข้อผิดพลาด อย่าถือว่า response body ว่างเปล่าเป็นความล้มเหลว

List vs GET Endpoints

List endpoints (เช่น /healthchecks, /origin_pools, /protected_domains) และ GET endpoints แต่ละรายการ (เช่น /healthchecks/\{name\}) คืนค่า โครงสร้าง response ที่แตกต่างกัน:

ประเภท Endpoint	ตัวอย่าง path	โครงสร้าง response
List	/origin_pools	รายการมี .name, .namespace, .tenant ระดับบนสุด พร้อม metadata: null และ get_spec: null
Individual GET	/origin_pools/\{name\}	ออบเจ็กต์มี .metadata.name, .spec.* พร้อมการกำหนดค่าเต็มรูปแบบ

ใช้ path jq ที่ถูกต้องสำหรับแต่ละรายการ ตัวอย่างเช่น หากต้องการแยก names จาก list endpoint ให้ใช้ .items[].name ไม่ใช่ .items[].metadata.name

ตัวระบุ Protected Domain

สำหรับการดำเนินการ GET และ DELETE ของ protected domain พารามิเตอร์ path \{name\} คือ ค่าโดเมนนั้นเอง (เช่น bankexample.com) ไม่ใช่ชื่อออบเจ็กต์ตามอำเภอใจ ซึ่งแตกต่างจากออบเจ็กต์ F5 XC อื่น ๆ ที่ชื่อเป็นตัวระบุที่ผู้ใช้เลือกเอง

CSD API Endpoints

Base path: /api/shape/csd/namespaces/\{namespace\}/

สถานะและการเริ่มต้น

การดำเนินการ	Method	Path
เปิดใช้งาน 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

Protected Domains

การดำเนินการ	Method	Path
แสดงรายการ	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\}

Detected Domains

การดำเนินการ	Method	Path
แสดงรายการที่ตรวจพบ	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
ดูรายละเอียด	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

Allowed Domains

การดำเนินการ	Method	Path
แสดงรายการ	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\}

Mitigated Domains

การดำเนินการ	Method	Path
แสดงรายการ	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\}

สคริปต์

การดำเนินการ	Method	Path
แสดงรายการสคริปต์	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
แสดงรายการสคริปต์ (legacy)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
ดูภาพรวมสคริปต์	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
แสดงรายการ Behaviors	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
แสดงรายการการโต้ตอบเครือข่าย	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
อัปเดต Justification	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
ลบ 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

Form Fields

การดำเนินการ	Method	Path
แสดงรายการ Form Fields	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
แสดงรายการ Form Fields (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
ดู Form Field	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 สำหรับ tenant:

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 .

Protected Domains

แสดงรายการ Protected Domains

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

เพิ่ม Protected Domain

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 .

ลบ Protected Domain

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

Detected Domains

แสดงรายการ Detected Domains

Query parameters: 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 .

แสดงรายการ Behaviors ของสคริปต์

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 .

การบรรเทาภัยคุกคาม

เพิ่ม Mitigated Domain

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 .

แสดงรายการ Mitigated Domains

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"

Allowed Domains

เพิ่ม Allowed 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 .

แสดงรายการ Allowed Domains

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

ลบ Allowed Domain

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

การกำหนดค่า JS Injection

ดูการกำหนดค่าปัจจุบัน

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

การกำหนดค่า CSD บน HTTP Load Balancer

การ inject JavaScript ของ CSD สามารถเปิดใช้งานได้โดยตรงบน HTTP Load Balancer ผ่าน API การกำหนดค่าที่ /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}

ฟิลด์ client_side_defense ภายใน spec ของ load balancer ควบคุมการ inject:

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

policy รับค่าหนึ่งในรายการต่อไปนี้:

ฟิลด์	คำอธิบาย
js_insert_all_pages	Inject ในทุกหน้า
js_insert_all_pages_except	Inject ในทุกหน้ายกเว้นกฎการยกเว้น
js_insertion_rules	Inject เฉพาะในหน้าที่ตรงกับกฎ
disable_js_insert	ไม่ต้อง inject

หากต้องการปิดใช้งาน CSD บน load balancer ให้แทนที่ client_side_defense ด้วย disable_client_side_defense: \{\}

อ่านการกำหนดค่า CSD จาก Load Balancer

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 บน Load Balancer

ดึงข้อมูล แก้ไข และนำไปใช้:

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'

การจับคู่โดเมนและ Path สำหรับกฎการยกเว้น

เมื่อใช้ js_insert_all_pages_except หรือ js_insertion_rules แต่ละกฎจะจับคู่กับโดเมนและ path

โดเมน (เลือกหนึ่งรายการ):

ฟิลด์	ตัวอย่าง
any_domain: \{\}	ทุกโดเมน
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

Path (เลือกหนึ่งรายการ):

ฟิลด์	ตัวอย่าง
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

อ้างอิง API

• CSD API Reference — เอกสาร endpoint ฉบับสมบูรณ์
• Configure CSD — คู่มือการกำหนดค่าผ่าน Console
• API Credentials — สร้าง API tokens