دفع الكائنات في الوضع المجمع إلى FMC باستخدام REST-API

المقدمة

يوضح هذا المستند الكيفية التي يمكن بها لمسؤول واجهة برمجة التطبيقات (API) دفع كائنات الشبكة والمنفذ وعنوان URL بشكل مجمع إلى مركز إدارة Firepower (FMC).

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

المتطلبات

توصي Cisco بأن تكون لديك معرفة بالمواضيع التالية:

• فهم العديد من مكالمات REST API. (ما هي واجهات REST API؟)
• مراجعة دليل البدء السريع ل FMC API
• مراجعة كائنات FMC القابلة لإعادة الاستخدام
• معرفة أساسية بمكتبة طلبات Python

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

• مركز إدارة Firepower الذي يدعم واجهات برمجة تطبيقات REST (الإصدار 6.1 أو أعلى) مع تمكين REST API
• تفاعلات REST API باستخدام Python.

القيود

• لا تقبل FMC اسم الكائن ليكون أكبر من 64 حرفا.
• يجب ألا يحتوي اسم الكائن على مساحة في بداية اسم الكائن والفواصل المنقوطة في النهاية.
• لا يمكن أن تحتوي الحمولة على أكثر من 1000 إدخال في دفعة مجمعة واحدة.
• لا يمكن أن يكون حجم الحمولة أكثر من 2 ميجابايت في دفعة واحدة غير كبيرة.

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

أصبحت واجهات REST API شائعة بشكل متزايد بسبب النهج خفيف الوزن القابل للبرمجة الذي يمكن لمديري الشبكات إستخدامه لتكوين شبكاتهم وإدارتها. تدعم FMC التكوين والإدارة باستخدام أي عميل REST كما تستخدم مستكشف واجهة برمجة التطبيقات (API) المدمجة.

يأخذ المثال في هذا المستند ملف CSV كمدخل ويدفع الكائنات إلى FMC عبر واجهة واجهة REST API. يغطي المستند دفع مجمع الشبكة المضيفة فقط ويمكن توسيع منطق مماثل للكائنات الأخرى. يتم إرفاق نموذج شفرة بالمستند لعنوان URL وكائنات المنفذ. 

هنا ال API مرجع ل POST على شبكة مضيف أن يكون استعملت، كما هو موضح في الصورة:

التكوين

الخطوة 1. تمكين REST API وإنشاء رمز مصادقة مميز. للحصول على خطوات التكوين والأمثلة التفصيلية، ارجع إلى إنشاء رمز مصادقة مميز على FMC.

import requests
import csv
import json
from requests.auth import HTTPBasicAuth
from getpass import getpass

address = input("Enter IP Address of the FMC: ")
username = input ("Enter Username: ")
password = getpass("Enter Password: ")

api_uri = "/api/fmc_platform/v1/auth/generatetoken"
url = "https://" + address + api_uri

response = requests.request("POST", url, verify=False, auth=HTTPBasicAuth(username, password))


accesstoken = response.headers["X-auth-access-token"]
refreshtoken = response.headers["X-auth-refresh-token"]
DOMAIN_UUID = response.headers["DOMAIN_UUID"]

الخطوة 2.قم بتحويل ملف CSV المتوفر إلى قاموس لاستخدامه كحمولة JSON للطلب. نموذج ملف CSV لكل نوع كائن مرتبط بالمستند. 

csvFilePath = input("Please enter the CSV Filepath (For eg. : path/to/file/objects.csv) :")


host = []

with open(csvFilePath, encoding='utf-8-sig') as csvf:
	csvReader = csv.DictReader(csvf)

for rows in csvReader:
	if rows['type'] == "Host":
		host.append(rows)

host_payload = json.dumps(host)

يبدو host_payload في هذه المرحلة كما هو موضح في الصورة:

[{
		"name": "Host-1",
		"description": "Host-1",
		"type": "Host",
		"value": "10.10.10.10"
	},
	{
		"name": "Host-2",
		"description": "Host-2",
		"type": "Host",
		"value": "10.10.10.1"
	},
	{
		"name": "Host-3",
		"description": "Host-3",
		"type": "Host",
		"value": "10.10.10.2"
	}
]

الخطوة 3. قم بإنشاء الطلب من الإدخال الذي تم إستلامه من الخطوات السابقة وأرسل الطلب إذا لم تكن الحمولة فارغة.

host_api_uri = "/api/fmc_config/v1/domain/" + DOMAIN_UUID + "/object/hosts?bulk =true"
host_url = "https://" + address + host_api_uri
headers = { 'Content-Type': 'application/json', 'x-auth-access-token': accesstoken }

if host != []:
	response = requests.request("POST", host_url, headers=headers, data = host_payload, verify = False)
else :
    print("Please Validate that the CSV file provided is correct or at correct location")

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

• قم بطباعة رمز حالة الاستجابة للتحقق من نجاح الطلب أو فشله، كما هو موضح هنا.

if response.status_code == 201 or response.status_code == 202:
	print("Host Objects successfully pushed")
else:
	print("Host Object creation failed")

• تسجيل الدخول إلى FMC انتقل إلى كائن > إدارة الكائن > الشبكة وتحقق من كائنات المضيف، كما هو موضح في الصورة:

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

• عند إستخدام عميل REST، قد ترى أخطاء متعلقة بمشكلة شهادة SSL بسبب شهادة موقعة ذاتيا. يمكنك إيقاف تشغيل عملية التحقق هذه وفقا للعميل الذي تستخدمه.
• تكون رموز مصادقة REST API الخاصة بوحدة التحكم في إدارة الإطارات (FMC) صالحة لمدة 30 دقيقة ويمكن تحديثها ثلاث مرات.
• يمكن إستخراج الخطأ المرتبط بالطلب من نص الاستجابة. يمكن تجميع هذا كملف سجل للمساعدة في أستكشاف الأخطاء وإصلاحها. 

logfile = "requestlog.txt"
log = open(logfile,"w+")
log.write(response.text)
log.close

• يتم تسجيل جميع طلبات REST في ملفي السجل هذين على FMC. البحث عن عنوان URL الخاص بك (على سبيل المثال. .../object/hosts) مع العملية الصحيحة (إذا كنت تبحث عن خطأ في عملية GET، تأكد من أن السجل يبدأ شيء مثل GET ...كائن/مضيف)

tail -f /var/opt/CSCOpx/MDC/tomcat/logs/stdout.logs  
tail -f /var/opt/CSCOpx/MDC/log/operation/usmsharedsvcs.log