مرجع API

يمتلك CSD واجهة API مخصصة على /api/shape/csd/ لإدارة النطاقات والسكريبتات والتخفيف والمراقبة. يمكن أيضاً تفعيل CSD على موازنات تحميل HTTP عبر واجهة API لتهيئة موازن التحميل.

المصادقة

تستلزم جميع استدعاءات API رمز API. قم بإنشاء رمز في وحدة تحكم XC ضمن الإدارة → بيانات الاعتماد → بيانات اعتماد API.

قم بإعداد متغيرات البيئة الخاصة بك كما هو موضح في أتمتة API — إعداد البيئة:

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

تستخدم جميع أمثلة curl صيغة العنصر النائب xTOKENx. استبدلها بمتغيرات البيئة الخاصة بك أو استخدم النموذج التفاعلي في أعلى الصفحة. على سبيل المثال، xF5XC_API_TOKENx يقابل $F5XC_API_TOKEN.

-H "Authorization: APIToken xF5XC_API_TOKENx"

اتفاقيات API

ملاحظة

تنطبق هذه الاتفاقيات على جميع نقاط نهاية تهيئة F5 Distributed Cloud (F5 XC) ونقاط نهاية CSD 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 .

تهيئة CSD على موازن تحميل HTTP

يمكن أيضاً تفعيل حقن JavaScript الخاص بـ CSD مباشرةً على موازن تحميل HTTP عبر واجهة API للتهيئة على /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 — دليل التهيئة عبر وحدة التحكم
• بيانات اعتماد API — إنشاء رموز API