إظهار التنقل من خلال API-Explorer الخاص بواجهة برمجة التطبيقات (API) لجدار الحماية الآمنة

المقدمة

يصف هذا المستند التنقل عبر واجهة برمجة التطبيقات (API) مستكشف Cisco FMC و Cisco FDM.

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

الفهم الأساسي لواجهة برمجة تطبيقات REST.

المتطلبات

يلزم أن يكون لهذا العرض التوضيحي إمكانية الوصول إلى واجهة المستخدم الرسومية (GUI) لمركز إدارة FirePOWER (FMC) باستخدام جهاز واحد على الأقل تتم إدارته بواسطة مركز إدارة FirePOWER (FMC) هذا. بالنسبة للجزء الخاص ب FDM من هذا العرض التوضيحي، يلزم توفر برنامج دفاع ضد تهديدات الطاقة النارية (FTD) يتم إدارته محليا لإتاحة إمكانية الوصول إلى واجهة المستخدم الرسومية (GUI) الخاصة بإدارة fdm.

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

• FMCv
• FTDv
• برنامج FTDv المدار محليا

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

مراجعة التنقل من خلال FMC API Explorer

للوصول إلى مستكشف واجهة برمجة تطبيقات FMC، انتقل إلى عنوان URL التالي:

https://<FMC_mgmt_IP>/API/API-Explorer

يجب تسجيل الدخول باستخدام نفس بيانات الاعتماد المستخدمة لواجهة المستخدم الرسومية (GUI) ل FMC. يتم إدخال بيانات الاعتماد هذه في نافذة مماثلة للنافذة التالية عند إدخال عناوين URL الخاصة بمستكشف واجهة برمجة التطبيقات.

بمجرد تسجيل الدخول، يظهر أن استعلامات API مقسمة حسب الفئات المقابلة للمكالمات المحتملة التي يمكنك إجراؤها باستخدام APIs.

عند النقر فوق فئة، فإنها تقوم بتوسيع إظهار المكالمات المختلفة المتوفرة لهذه الفئة. يتم عرض هذه الاستدعاءات مع أساليب REST الخاصة بها ومعرف الموارد العالمي (URI) لهذا الاستدعاء.

في المثال التالي، تقوم بإجراء طلب للاطلاع على سياسات الوصول التي تم تكوينها في وحدة التحكم في الوصول الموحدة (FMC). تقوم بالنقر فوق الطريقة المقابلة لتمديدها، ثم انقر فوق الزر تجربة.

هناك ما يجب التأكيد عليه وهو أنه يمكنك وضع معلمات على استفساراتك باستخدام المعلمات المتوفرة في كل مكالمة من مكالمات واجهة برمجة التطبيقات (API). فقط تلك التي تحتوي على نجمات حمراء إلزامية، والآخرين يمكن أن تترك فارغة.

على سبيل المثال، يكون domainUID إلزاميا لجميع إستدعاءات API، ولكن يتم تعبئته تلقائيا في مستكشف API.

تتمثل الخطوة التالية في النقر فوق تنفيذ لإجراء هذه المكالمة.

قبل النقر فوق "تنفيذ"، يمكنك مشاهدة أمثلة لاستجابات المكالمات للحصول على فكرة عن الاستجابات المحتملة التي يمكنك الحصول عليها بناء على ما إذا كان الطلب صحيحا أم لا.

بمجرد تنفيذ إستدعاء واجهة برمجة التطبيقات، يمكنك الحصول، مع حمولة الاستجابة، على رمز الاستجابة. في هذه الحالة 200، والتي تتطابق مع طلب OK. يمكنك أيضا الحصول على عنوان URL و URL الخاص بالمكالمة التي قمت بها للتو. تكون هذه المعلومات مفيدة إذا كنت تريد إجراء هذه المكالمة باستخدام عميل/برنامج خارجي.

ترجع الإجابة التي تم الحصول عليها ACPs التي تم تكوينها في FMC بالإضافة إلى ObjectID. في هذه الحالة، يمكنك رؤية هذه المعلومات في المربع الأحمر في الصورة التالية:

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

URIs التي تحتوي على قيم بين الأقواس المعقوفة {} هي قيم مطلوبة لإجراء هذه الاستدعاء.  تذكر أن domainUUID هي القيمة الوحيدة التي يتم تعبئتها تلقائيا.

يتم تحديد القيم المطلوبة لهذه المكالمات في وصف المكالمة. لإنشاء قواعد ل ACP، أنت تتطلب PolicyID، كما يمكنك أن ترى في الصورة التالية:

يتم إدخال PolicyID هذا في الحقل المحدد ك containerUUID، والحقل المطلوب الآخر لأساليب POST هو نص الحمولة أو الطلب. يمكنك إستخدام الأمثلة المقدمة للتعديل وفقا لاحتياجاتك.

مثال على الحمولة المعدلة:

{ "action": "ALLOW", "enabled": true, "type": "AccessRule", "name": "Testing API rule", "sendEventsToFMC": false, "logFiles": false, "logBegin": false, "logEnd": false, "sourceZones": { "objects": [ { "name": "Inside_Zone", "id": "8c1c58ec-8d40-11ed-b39b-f2bc2b448f0d", "type": "SecurityZone" } ] }, "destinationZones": { "objects": [ { "name": "Outside_Zone", "id": "c5e0a920-8d40-11ed-994a-900c72fc7112", "type": "SecurityZone" } ] }, "newComments": [ "comment1", "comment2" ] }

بمجرد تنفيذ المكالمة السابقة، تحصل على رمز إستجابة 201، يشير إلى أن الطلب نجح وأدى إلى إنشاء المورد.

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

ولهذا السبب، يتعين عليك الحصول على قائمة بالأجهزة التي تحتوي على تغييرات جاهزة للنشر.

يحتوي المثال على زوج من الأجهزة التي تم تكوينها في حالة التوفر العالي. يجب الحصول على معرف هذا HA، في حالة كونه جهازا مستقلا، يجب الحصول على معرف هذا الجهاز.

الاستعلام المطلوب للحصول على معرف الجهاز HA هو كما يلي:

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

بمجرد تنفيذ هذه المكالمة، إذا كان كل شيء صحيحا، ستحصل على إستجابة باستخدام الرمز 202.

مراجعة التنقل من خلال مستكشف واجهة برمجة التطبيقات (API) ل FDM

للوصول إلى مستكشف واجهة برمجة تطبيقات FDM، من الممكن إستخدام زر على واجهة المستخدم الرسومية (GUI) ل FDM للانتقال مباشرة إليه، كما هو موضح في الصورة التالية:

بمجرد أن تصبح في مستكشف واجهة برمجة التطبيقات، تلاحظ أن الاستعلامات تنقسم أيضا إلى فئات.

لتوسيع فئة، يجب النقر فوقها، ثم يمكنك توسيع كل عملية من العمليات بالنقر فوق أي منها. أول شيء يوجد داخل كل عملية هو مثال على إستجابة "موافق" لهذه المكالمة.

والشيء التالي الذي تراه هو المعاملات المتاحة لتقييد استجابات الاستدعاء الذي تقوم به. تذكر أن الحقول التي تم وضع علامة "مطلوب" عليها فقط هي الحقول الإلزامية لإجراء مثل هذا الاستدعاء.

وأخيرا، يمكنك العثور على رموز الاستجابة الممكنة التي يمكن أن ترجع إليها هذه المكالمة.

إذا كنت ترغب في إجراء هذه المكالمة، يجب النقر فوق تجربة ذلك. للعثور على هذا الزر، يجب أن تقوم بالتمرير لأسفل حتى تجد هذا الزر لأنه موجود في أسفل كل مكالمة.

عند النقر فوق الزر "تجربة ذلك"، إذا كان الاتصال لا يتطلب المزيد من الحقول، فإنه يتم تنفيذه على الفور ويعطيك الاستجابة.

استكشاف الأخطاء وإصلاحها

تقوم كل مكالمة بإنشاء رمز إستجابة HTTP ونص إستجابة. هذا يساعدك على تحديد مكان الخطأ.

التالي هو خطأ شائع يحدث عند انتهاء صلاحية جلسة العمل، مما يشير إلى أن الرمز المميز غير صالح لأنه انتهت صلاحيته.

وفيما يلي أمثلة على رموز إستجابة HTTP التي يمكن للاستدعاءات إرجاعها:

• الفئة 2xx: نجاح. هناك العديد من رموز الحالة: 200 (GET and PUT)، 201 (POST)، 202، 204 (DELETE). تشير إلى إستدعاء واجهة برمجة تطبيقات (API) ناجح.
• السلسلة 30x: إعادة التوجيه. يمكن إستخدامه عند إستخدام العميل ل HTTP في الأصل وإعادة توجيهه إلى HTTPS.
• الفئة 4xx: فشل من جانب العميل في إستدعاء واجهة برمجة التطبيقات (API) الذي تم إرساله من العميل إلى الخادم. يتضمن مثالان رمز حالة 401، يشير إلى أن جلسة العمل غير مصدق عليها، ورمز 403، يشير إلى محاولة وصول محظورة.
• الفئة 5xx: فشل الخادم أو الجهاز أو الخدمة. قد يكون هذا نتيجة تعطيل خدمة API للجهاز، أو تعذر الوصول إليها عبر شبكة IP