تكوين قاموس ESA باستخدام Python و AsyncOS REST API

المقدمة

يصف هذا وثيقة كيف أن يستعمل Python نصي أن يضيف قاموس جديد إلى cisco بريد إلكتروني أمن تطبيق (ESA) ب يستعمل ال AsyncOS API (REST API).

المتطلبات الأساسية

راجع هذه المتطلبات الأساسية:

• لغة برمجة بايثون
• وحدة طلبات Python
• جسون
• أجهزة أمان البريد الإلكتروني Cisco Email Security Appliance (ESA)

المتطلبات

أستخدم البرنامج والوصول التاليين لتشغيل البرنامج النصي:

• جهاز Cisco Email Security Appliance (ESA) الذي يعمل بنظام التشغيل AsyncOS 14.x أو إصدار أحدث
• بايثون 3
• وحدة طلبات Python
• بيانات اعتماد مسؤول ESA مع الإذن باستخدام واجهة برمجة تطبيقات AsyncOS (REST API)
• الوصول إلى واجهة إدارة ESA عبر HTTPS على المنفذ 6443 (مستحسن)

المكونات المستخدمة

تم إستخدام هذه المكونات لإكمال هذا المختبر:

1) Cisco ESA - 15.0.0-104

2) محرر النصوص الفرعية

تم إنشاء المعلومات الواردة في هذا المستند من الأجهزة الموجودة في بيئة معملية خاصة. بدأت جميع الأجهزة المُستخدمة في هذا المستند بتكوين ممسوح (افتراضي). إذا كانت شبكتك قيد التشغيل، فتأكد من فهمك للتأثير المحتمل لأي أمر.

النقل والمصادقة

• النقل: أستخدم HTTPS على المنفذ 6443 لواجهة برمجة تطبيقات AsyncOS عند توفرها. أستخدم HTTP/6080 فقط في بيئات غير الإنتاج أو المختبرات.
• المصادقة: يستخدم هذا المثال مصادقة HTTP الأساسية. توفير تخويل الرأس: أساسي <base64(username:password)>. لا تلصق بيانات الاعتماد الحقيقية في البرنامج النصي.

معلومات أساسية

لهذا المستند:

الهدف: قم بإضافة قاموس إلى ESA باستخدام برنامج نصي Python وواجهة برمجة تطبيقات AsyncOS (REST API).

النتيجة المتوقعة: ترجع واجهة برمجة التطبيقات (API) إستجابة ناجحة ويظهر القاموس الجديد في تكوين ESA.

التكوين

قم بتمكين خدمة AsyncOS API (REST API) على واجهة إدارة ESA قبل تشغيل البرنامج النصي.

1. في واجهة المستخدم الرسومية (GUI)، انتقل إلى الشبكة أو صفحة الواجهة التي تحتوي على إعدادات HTTP لواجهة برمجة التطبيقات (API) ل AsyncOS وAsyncOS.
2. قم بتمكين HTTPS لواجهة برمجة التطبيقات AsyncOS والتحقق من المنفذ 6443.
3. (إختياري) قم بتمكين HTTP لواجهة برمجة التطبيقات AsyncOS والتحقق من المنفذ 6080 لاستخدام المختبر.
4. انقر فوق حفظ.

الصورة 1: تحقق من تمكين HTTPS لواجهة الإدارة ل AsyncOS (المنفذ 6443).

تكوين تسجيل واجهة برمجة التطبيقات لاستكشاف أخطاء طلبات واجهة برمجة التطبيقات AsyncOS وإصلاحها.

1. في واجهة المستخدم الرسومية (GUI)، انتقل إلى إدارة النظام > تسجيل الاشتراكات.
2. انقر فوق إضافة اشتراك السجل.
3. من القائمة المنسدلة نوع السجل، حدد سجلات API.
4. أدخل الحقول المطلوبة المتبقية، مثل اسم السجل واسم الملف، ثم انقر فوق إرسال.

حددAPI LogsمنLog Typeالقائمة المنسدلة وأدخل التفاصيل المتبقية المطلوبة.

نص

أستخدم الوحدة النمطية لطلبات HTTP POST من Python لإنشاء قاموس.

أستخدم هذه المعلمات لطلب POST:

بارامتر	الموقع	إستوجبتا	ملاحظات
device_type	سلسلة استعلام URL	نعم	تعيين إلى ESA.
تجاهل	حمولة JSON	نعم	0 = حساس لحالة الأحرف، 1 = غير حساس لحالة الأحرف.
كلمات كبدية	حمولة JSON	نعم	0 = مطابقة سلسلة فرعية، 1 = مطابقة كلمة كاملة.
ترميز	حمولة JSON	نعم	أستخدم UTF-8 ما لم يكن هناك تشفير مختلف مطلوب.
كلمات	حمولة JSON	نعم	صفيف من الإدخالات. أستخدم ["المصطلح"] لمصطلح حرفي. بالنسبة للمعرفات الذكية، أستخدم تنسيق مجموعة مثل ["*credit"، 2، "prefix"] كما هو مدعوم من قبل ESA.
نمط	سلسلة استعلام URL	لا	مطلوب فقط لعمليات نشر المجموعات/المجموعات (على سبيل المثال، mode=cluster).

import base64
import requests

# ESA management IP address or FQDN
host = ""

# Dictionary name to create
dictionary_name = ""

# AsyncOS API endpoint (HTTPS recommended)
url = f"https://{host}:6443/esa/api/v2.0/config/dictionaries/{dictionary_name}?device_type=esa"

payload = {
    "data": {
        "ignorecase": 0,
        "wholewords": 1,
        "words": [
            ["*credit", 2, "prefix"],
            ["*aba"],
            ["Example Term"]
        ],
        "encoding": "utf-8"
    }
}

# Basic authentication header
username = ""
password = ""
creds = base64.b64encode(f"{username}:{password}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Basic {creds}"
}

response = requests.post(url, headers=headers, json=payload, timeout=30, verify=False)
print(f"Status code: {response.status_code}")
try:
    print(response.json())
except ValueError:
    print(response.text)

if response.status_code != 201:
    raise SystemExit("Dictionary creation failed.")

في النص التنفيذي، يتم تضمين اسم القاموس () في مسار عنوان الربط الخاص بالطلب.

تضمين المعلمات المطلوبة (ignorecase، wholewordsوwords، و encoding) في حمولة JSON. إضافة device_type إلى سلسلة استعلام URL.

المعلمة mode مطلوبة فقط عندما تكون ESAs في نظام مجموعة أو مجموعة. في هذه الحالة، قم بإلحاق mode=cluster إلى سلسلة استعلام URL بنفس الطريقة مثل device_type.

*credit ويتم*abaإضافتها إلى الحمولة لتمكين المعرفات الذكية لأرقام بطاقات الائتمان وأرقام توجيه ABA، كما هو موضح في لقطة الشاشة:

يتم Example Term إضافة المصطلح إلى الحمولة كعنصر قاموس لمطابقته.

التحقق من الصحة

عندما ينجح طلب POST، يحتوي سجل واجهة برمجة التطبيقات على إدخال مماثل لهذا:

API log example
Thu October 5 12:58:19 2023 Info: 198.51.100.10 - - 05/Oct/2023 12:58:19 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 201 -

الاستجابة المتوقعة:

{"data": {"message": "Added Successfully"}}

إذا كان القاموس موجودا بالفعل وتم تشغيل طلب POST مرة أخرى، يحتوي سجل API على إدخال مماثل لهذا:

API log example
Thu October 5 13:00:31 2023 Info: 198.51.100.10 - - 05/Oct/2023 13:00:31 +0000 POST /esa/api/v2.0/config/dictionaries/ExampleDictionary?device_type=esa HTTP/1.1 409 -

الاستجابة المتوقعة:

{"error": {"message": "Dictionary already exists.", "code": "409", "explanation": "409 = Request conflict."}}

معلومات ذات صلة

أستخدم الموارد الخارجية التالية للحصول على خلفية إضافية (الإجراء الوارد في هذا المستند قائم بذاته):

إضافة قواميس باستخدام REST API + Python 

يتضمن هذا المستند طريقة المصادقة المطلوبة والإجراء الأدنى. إستخدام مصادقة HTTP الأساسية باستخدام تفويض الرأس: أساسي <base64(username:password)> ويفضل HTTPS على ميناء 6443.

REST API و Cisco ESA 

بالإضافة إلى ذلك، يمكن إستخراج كود Python المستخدم في هذا الإجراء من Postman. راجع تمرين الفيديو هذا إذا لزم الأمر:

ساعي البريد - كيفية توليد نصوص بايثون 

محفوظات المراجعة

المراجعة	تاريخ النشر	التعليقات
1.0	26-Aug-2026	الإصدار الأولي