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

المقدمة

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

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

المتطلبات

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

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

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

• مركز إدارة Firepower الذي يدعم واجهات برمجة تطبيقات REST (الإصدار 7.4 أو أعلى) مع تمكين REST API
• برنامج API Explorer مدمج في FMC

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

القيود

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

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

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

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

سمات JSON التي تظل شائعة بين جميع أنواع كائنات الشبكة هي:

1. القيمة - توفر هذه السمة معلومات مثل قيمة الشبكة مع CIDR، على سبيل المثال، يمكن أن يكون للكائن المضيف x.x.x.x كعنوان IP ويمكن أن يكون للشبكة x.x.x.x/<prefix> كشبكة فرعية مع CIDR.
2. النوع - توفر هذه السمة معلومات حول نوع الكائن المستخدم لتكوين الكائن (المضيف والشبكة والخدمة والنطاق وFQDN).
3. الاسم - توفر هذه السمة معلومات حول اسم الكائن
4. الوصف - يمكن إستخدام هذه السمة لتقديم بعض المعلومات المفيدة أو التعليقات حول الكائن
5. قابل للتجاوز - يسمح لك تجاوز الكائن بتعريف قيمة بديلة لكائن، والتي يستخدمها النظام للأجهزة التي تحددها. هذه سمة إختيارية يمكن إستخدامها في إنشاء الكائنات.

التكوين

تمكين API على FMC

تمكين REST API على Cisco FMC. للحصول على معلومات تفصيلية حول "كيفية تمكين REST API" و"أفضل الممارسات"، ارجع إلى تمكين REST API على Cisco FMC

انتقل إلى النظام > التكوين > تفضيلات REST API > تحديد "تمكين REST API"

يتواجد مستكشف واجهة برمجة التطبيقات (API) في مركز الإدارة، ويمكن الوصول إليه من خلال مركز الإدارة:

https://<management_center_ip_or_name>:<https_port>/api/api-explorer 

ملاحظة: في حالة إستخدام منفذ HTTPS TCP 443 القياسي، فعليك إزالة ":<https_port" بشكل آمن من عنوان URL.

تمت مصادفة أخطاء شائعة

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

1. رمز الوصول المميز غير صالح:

إستجابة JSON لرمز الوصول المميز غير الصالح

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

2. التنسيق المستخدم غير صالح:

{
  "name": "API_1",
  "type": "Host",
  "value": "10.5.3.20"
  "description": "Test Description"
}

نموذج طلب JSON لإنشاء كائن

فشل إستجابة JSON بسبب الفواصل المفقودة

ملاحظة: غالبا ما تتم مواجهة هذا الخطأ عندما تكون هناك فاصلة مفقودة بتنسيق JSON. في المثال ("القيمة": "10.5.3.20") لا تحتوي على فاصلة تسببت في هذا الفشل. يجب ألا تحتوي آخر سمة بتنسيق JSON فقط على فاصلة، وإلا قد تتسبب في حدوث فشل.

3. إدخال غير صالح مستخدم في إنشاء الكائن:

{
  "name": "net2",
  "value": "1.1.0.0/24",
  "overridable": false,
  "description": "Network obj 2",
  "type": "Network"
}

فشل إستجابة JSON لنوع غير صالح

ملاحظة: في هذا المثال، تتم محاولة إنشاء الكائن في فئة الأجهزة المضيفة مع حمولة JSON لكائن الشبكة، وقد نتج عنها خطأ "عدم تطابق نوع الإدخال". أستخدم التنسيق الصحيح المعين لكل كائن شبكة (البيئات المضيفة والشبكة وشبكة FQDN والخدمة والنطاق).

4. إستخدام حمولة إستجابة GET لإنشاء الكائن

{
      "links": {
        "self": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/hosts/00000000-0000-0ed3-0000-034359741703",
        "parent": "https://10.197.207.3/api/fmc_config/v1/domain/e276abec-e0f2-11e3-8169-6d9ed49b625f/object/networkaddresses"
      },
      "type": "Host",
      "name": "API_2",
      "id": "00000000-0000-0ed3-0000-034359741703"
}

الحصول على طلب إحضار كائنات المضيف

فشل إستجابة JSON بسبب سمة القيمة المفقودة

فشل إستجابة JSON حيث تم إنشاء الكائن بتنسيق غير صحيح

ملاحظة: في هذا المثال، تكون سمة القيمة مفقودة في حمولة JSON التي تم استقدامها باستخدام أسلوب GET وتم تعيين المعلمة الموسعة على القيمة الافتراضية. هناك سمات إلزامية يمكن أن تكون في حمولة JSON لإنشاء الكائن وهو النوع والاسم والقيمة لمعظم كائنات الشبكة (البيئات المضيفة والشبكة والنطاق والخدمة و FQDN). عند إنشاء الكائن باستخدام حمولة JSON لأسلوب GET، أستخدم فقط المعلومات المتعلقة بالكائن الموجودة داخل سمة العناصر وقم بإزالة سمة id حتى لا يكون هناك تعارض مع UUID.

إنشاء كائن مضيف

كائن مضيف واحد

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائن مضيف واحد:

{
  "name": "Obj_API_100.1.1.1",
  "type": "Host",
  "value": "100.1.1.1",
  "description": "Host Object Pushed via API"
}

عملية ترحيل لإنشاء كائن مضيف

ملاحظة: أستخدم "المعلمة المجمعة" الافتراضية أثناء إستخدام عملية POST لكائن مضيف واحد.

كائن مضيف مجمع

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/hosts > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائنات المضيف المجمعة:

[
	{
	"name": "Obj_API_172.16.0.1",
	"type": "Host",
	"value": "172.16.0.1",
	"description": "Bulk API Operation"
	},
	{
	"name": "Obj_API_172.16.0.2",
	"type": "Host",
	"value": "172.16.0.2",
	"description": "Bulk API Operation"
	}
]

نموذج طلب JSON لإنشاء كائنات غير كبيرة

نموذج إستجابة JSON بعد إنشاء كائنات كبيرة

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

إنشاء كائن شبكة

كائن شبكة واحد

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائن شبكة واحد:

{
  "name": "Obj_API_network",
  "value": "7.0.0.0/24",
  "overridable": false,
  "description": "Single Network object created",
  "type": "Network"
}

نموذج طلب JSON لإنشاء كائن شبكة واحد

كائن الشبكة المجمعة

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/networks > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائنات الشبكة المجمعة:

[
  {
    "name": "Obj_API_net1",
    "value": "1.0.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  },
  {
    "name": "Obj_API_net2",
    "value": "1.1.0.0/24",
    "overridable": false,
    "description": "Bulk Operation",
    "type": "Network"
  }
]

نموذج طلب JSON لإنشاء كائنات شبكة كبيرة

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

إنشاء كائن نطاق الشبكة

كائن نطاق شبكة واحد

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/range > POST وانقر فوق تجربة ذلك.

تنسيق JSON المستخدم لدفع كائن نطاق واحد:

{
  "name": "Obj_API_TestRange",
  "value": "10.2.30.40-10.2.30.50",
  "type": "Range",
  "description": "Create Single Range Object"
}

كائن نطاق الشبكة المجمعة

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/range > POST وانقر فوق تجربة ذلك.

تنسيق JSON المستخدم لدفع كائنات النطاق المجمع:

[
  {
    "name": "Obj_API_TestRange1",
    "value": "10.4.30.40-10.4.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_TestRange2",
    "value": "10.5.30.40-10.5.30.50",
    "type": "Range",
    "description": "Bulk Operation"
  }
]

ملاحظة: عند إنشاء كائنات نطاق إجمالي، حدد المعلمة المجمعة ك true. يمكن إنشاء 1000 إدخال كحد أقصى للدفعة المجمعة الواحدة باستخدام طريقة POST.

إنشاء كائن FQDN

كائن FQDN واحد

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائن شبكة واحد:

{
  "name": "TestFQDN",
  "type": "FQDN",
  "value": "cloud.cisco.com",
  "dnsResolution": "IPV4_ONLY",
  "description": "Create Single FQDN Object"
}

كائن FQDN المجمع

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/fqdns > POST وانقر فوق Try Out.

تنسيق JSON المستخدم لدفع كائنات الشبكة المجمعة:

[
  {
    "name": "Obj_API_FQDN_1",
    "type": "FQDN",
    "value": "downloads.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  },
  {
    "name": "Obj_API_FQDN_2",
    "type": "FQDN",
    "value": "support.cisco.com",
    "dnsResolution": "IPV4_ONLY",
    "description": "Bulk Operation"
  }
]

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

إنشاء كائن خدمة

كائن خدمة واحد

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolToBjects > POST وانقر فوق تجربة ذلك.

تنسيق JSON المستخدم لدفع كائن خدمة واحد:

{
  "name": "Obj_API_Telnet_Port",
  "protocol": "TCP",
  "port": 23,
  "type": "ProtocolPortObject"
}

تنسيق JSON المستخدم لدفع كائن خدمة واحد مع النطاق:

{
  "name": "Obj_API_obj1",
  "protocol": "UDP",
  "port": "1025-65535",
  "type": "ProtocolPortObject"
}

ملاحظة: عند تحديد نطاق المنافذ بتنسيق JSON، أستخدم علامات تنصيص مزدوجة على سبيل المثال "المنفذ": "1111-1115" وإلا يمكنك مواجهة الخطأ: "الوصف": "الكيان غير القابل للمعالجة - حرف غير متوقع ('-' (الرمز 45): كان يتوقع أن تقوم الفاصلة بفصل إدخالات الكائن في السطر: 4، العمود: 17"

كائن الخدمة المجمعة

انتقل إلى Object > /api/fmc_config/v1/domain/{domainUUID}/object/protocolToBjects > POST وانقر فوق تجربة ذلك.

تنسيق JSON المستخدم لدفع كائنات الخدمة المجمعة:

[
  {
    "name": "Obj_API_UDP_Port",
    "protocol": "UDP",
    "port": 123,
    "type": "ProtocolPortObject"
  },
  {
    "name": "Obj_API_TCP_Range",
    "protocol": "TCP",
    "port": "1025-65535",
    "type": "ProtocolPortObject"
  }
]

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

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

• ارجع إلى المستند الخاص برمز حالة HTTP (أساسيات REST API)
• لا يمكن إستخدام بيانات اعتماد المستخدم لكل من واجهات REST API و GUI في وقت واحد، ويتم تسجيل خروج المستخدم دون سابق إنذار إذا تم إستخدامه لكلا الواجهات.
• يتم تسجيل جميع طلبات 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