المقدمة

يوضح هذا المستند كيفية الوصول إلى واجهات برمجة تطبيقات CaTC Northbound (Intent) API واستخدامها باستخدام عميل واجهة برمجة تطبيقات (API) وأدوات المطور المضمنة للنظام الأساسي.

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

وهو يغطي مفاهيم HTTP/REST الأساسية ويقدم أمثلة عملية للتشغيل التلقائي والاختبار.

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

المتطلبات

توصي Cisco بمعرفة الموضوعات التالية:

• بروتوكولات HTTP/1.1 ورموز الحالة.
• نمط معماري REST.
• الفهم الأساسي لمركز Cisco Catalyst (CAtc)
• الفهم الأساسي لبرونو (أو عملاء واجهة برمجة التطبيقات المشابهين مثل بوستمان).

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

تستند المعلومات الواردة في هذا المستند إلى إصدارات المكونات المادية والبرامج التالية:

• Cisco Catalyst Center، الإصدارات 2.3.7.x و 3.x
• Bruno الإصدار 4.1.0

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

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

تتيح واجهات برمجة تطبيقات Catalyst Center Northbound API (واجهات برمجة تطبيقات الوجهة) للمستخدمين التفاعل مع وحدة التحكم خارج واجهة المستخدم الرسومية. ويتيح ذلك أتمتة عمليات سير العمل المصممة خصيصا، والدمج مع أدوات الجهات الخارجية، وإدارة الشبكة بشكل فعال على نطاق واسع.

مقدمة إلى HTTP

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

طلب HTTP

يتكون طلب HTTP من أربعة أجزاء:

1. سطر الطلب: يحدد الأسلوب (بما في ذلك GET وPOST)، و URI، وإصدار البروتوكول (مثل GET /API/v1/node HTTP/1.1).
2. العنوان الرئيسي: توفير بيانات تعريف مثل بيانات اعتماد المصادقة ونوع المحتوى.
3. سطر فارغ: يفصل الرؤوس عن المتن.
4. نص الرسالة (إختياري): يحتوي على بيانات مرسلة إلى الخادم (شائع في POST/PUT/PATCH).

إستجابة HTTP

تعكس إستجابة HTTP بنية الطلب:

1. سطر الحالة: يتضمن رمز الحالة (مثل 200 موافق).
2. العنوان الرئيسي: تفاصيل حول الخادم وبيانات الاستجابة.
3. نص الرسالة: البيانات الفعلية المطلوبة (عادة بتنسيق JSON لمركز Catalyst).

أساليب HTTP (الأفعال)

• الحصول على: إسترداد البيانات من مورد.
• مادة النشر: إنشاء مورد جديد.
• PUT: إستبدال مورد موجود.
• تصحيح: تطبيق التعديلات الجزئية على مورد.
• حذف: إزالة مورد.

رموز حالة HTTP

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

يتم تجميع الرموز في خمس فئات رئيسية وفقا للرقم الأول الخاص بها.

• رموز 1xx هي رموز إعلامية وتشير إلى أنه تم تلقي الطلب وأن المعالجة مستمرة.
• تشير الرموز 2xx إلى نجاح الطلب، مما يعني أن الخادم قد تلقى الطلب وفهمه ومعالجته بنجاح.
• يتم إستخدام رموز 3xx لإعادة التوجيه وتشير إلى أنه يمكن طلب إجراء إضافي لإكمال الطلب.
• تمثل رموز 4xx أخطاء العميل، مما يعني وجود مشكلة في الطلب الذي تم إرساله من قبل العميل.
• تمثل رموز 5xx أخطاء الفاصل، مما يعني أن الخادم واجه مشكلة أثناء محاولة معالجة طلب.

نظرة عامة على الراحة

REST (نقل الحالة التمثيلي) هو أسلوب معماري لتصميم التطبيقات المتصلة بالشبكة. تستخدم واجهات برمجة تطبيقات RESTfull HTTP كآلية نقل وعادة ما تستخدم JSON لتبادل البيانات نظرا لطبيعتها خفيفة الوزن.

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

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

يلتزم تفاعل REST النموذجي بنموذج يستند إلى العميل (وقد ذكر ذلك سابقا في المقالة). يرسل العميل طلب HTTP باستخدام طرق مثل GET، أو POST، أو PUT، أو PATCH، أوDelete. يقوم الخادم بمعالجة إستجابة HTTP وإرجاعها تحتوي على المعلومات المطلوبة أو نتيجة العملية.

عادة ما تستخدم واجهات برمجة تطبيقات RESTful HTTP كآلية اتصال لتنفيذ العمليات على الموارد. في هذا النموذج، يحدد العميل موردا/نقطة نهاية ثم يستخدم أسلوب HTTP للإشارة إلى الإجراء الذي سيتم تنفيذه على هذا المورد. يمكن وصف واجهة برمجة تطبيقات REST باستخدام عدة عناصر رئيسية. أولا، يتم إستخدام URI لتحديد المورد أو نقطة النهاية التي يريد العميل الوصول إليها. يوفر URI موقع ذلك المورد أو معرفه داخل واجهة برمجة التطبيقات. ثانيا، يستخدم العميل طرق HTTP القياسية مثل GET، POST، PUT، PATCH وDELETE لتعريف عملية الطلب. على سبيل المثال، يمكن إستخدام GET لاسترداد مورد وPOST لإنشاء مورد وDELETE لإزالة مورد بالكامل. وأخيرا، يتم تبادل المورد عبر تمثيل، والذي يتم تعريفه بواسطة نوع الوسائط الخاص به. هذا التمثيل هو النموذج الذي يتم فيه نقل بيانات الموارد بين العميل والخادم، مثل JSON أو XML.

واجهات برمجة التطبيقات Catalyst Center & REST

يساعد CAtc ببساطة عمليات الشبكة في المجمعات من خلال تمركز الأتمتة والتهيئة وإدارة السياسات والمراقبة والتحليلات. أنا أسمح لمسؤولي الشبكات بنشر الأجهزة وإدارتها بكفاءة أكبر، والمحافظة على السياسات المتناسقة، ومراقبة سلوك الشبكة، وتحسين الرؤية التشغيلية الشاملة. ويمكن لهذه القدرات الوصول إليها من خلال واجهة المستخدم الرسومية (GUI) وكذلك من خلال واجهات برمجة التطبيقات وعمليات التكامل الخارجية.

كما يوفر النظام الأساسي ل CaTC واجهات برمجة التطبيقات (API) التي يمكن إستخدامها لبناء عمليات تكامل مخصصة وأتمتة عمليات الشبكة. من خلال دمج واجهات برمجة تطبيقات CaTC مع حلول Cisco الحالية أو تطبيقات الجهات الخارجية، يمكن للمؤسسات توسيع وظائف النظام الأساسي وإنشاء عمليات سير عمل مصممة خصيصا للعمليات المحددة أو متطلبات الأعمال.

بعد تغطية المفاهيم الأساسية، يركز هذا المستند على واجهات برمجة التطبيقات (API) الواردة في Northbound، والتي يشار إليها أيضا باسم واجهات برمجة التطبيقات (API) الوجهة، داخل مركز Cisco Catalyst. تكشف واجهات برمجة التطبيقات هذه عن قدرات مركز Catalyst المحددة من خلال تجريد مستند إلى السياسة للمقصد التجاري، مما يسمح للمسؤولين والمطورين بالتركيز على النتيجة المطلوبة بدلا من خطوات التكوين الفردية المطلوبة لتحقيقها. 

واجهات برمجة تطبيقات Catalyst Center هي واجهات برمجة تطبيقات RESTful التي تستخدم تنسيق بيانات JSON للتفاعل مع النظام الأساسي. يمكن إستخدامها لاكتشاف معلومات الشبكة، واسترداد البيانات التشغيلية، وأداء مهام التحكم والتشغيل التلقائي المدعومة عبر الشبكة.

إسترداد رمز مصادقة باستخدام Bruno

قبل إجراء مكالمات API، يجب عليك المصادقة لتلقي رمز مميز.

1. تحديد نقطة نهاية API

1. سجل الدخول إلى مركز Catalyst.
2. انتقل إلى القائمة > منصة > مجموعة أدوات المطور.
3. في القائمة اليسرى، حدد المصادقة > واجهة برمجة تطبيقات المصادقة.
   
   مجموعة أدوات مطور Catalyst Center
   
   
4. انسخ عنوان URL (عادة POST /dna/system/api/v1/auth/token).

2. تكوين Bruno للمصادقة

1. في برونو، قم بإنشاء طلب جديد.
2. ثبتت النوع إلى HTTP والأسلوب إلى POST.
   
   إنشاء طلب جديد في برونو
   
   
3. أدخل عنوان URL لواجهة برمجة تطبيقات المصادقة.
   
   إنشاء طلب جديد في برونو
   
   
4. انتقل إلى علامة التبويب المصادقة وحدد المصادقة الأساسية.
   
   المصادقة الأساسية لواجهة برمجة التطبيقات (API) للمصادقة
   
   
5. أدخل بيانات اعتماد مسؤول Catalyst Center المتميز.
6. طقطقة يرسل.
   
   تشغيل واجهة برمجة تطبيقات المصادقة
   

يقوم الخادم بإرجاع حالة 200 OK وحمولة JSON التي تحتوي على الرمز المميز.

Alternative (Terminal): You can also generate the token by base64-encoding your `username:password` and sending a cURL request or using the **Try** button in the Catalyst Center GUI to copy the generated token.

الحصول على ترميز base64 لاسم المستخدم وكلمة المرور

إدخال مصادقة أساسية مع اسم مستخدم وكلمة مرور قاعدة 64 مرمزة

الحصول على رمز المصادقة المميز من واجهة المستخدم الرسومية (GUI) لمركز Catalyst.

عند هذه النقطة يكون لديك رمز المصادقة المميز، إما على إستجابة Bruno أو على الاستجابة التي تم إجراؤها من Catalyst Center Developer Toolkit. 

الآن أضف الرمز المميز كرأس على إعدادات المجموعة في Bruno، فهذا يسهل أي طلب منشأ آخر داخل المجموعة لاستخدام الرمز المميز، بحيث لا تكون بحاجة إلى إدخال الرمز المميز يدويا كرأس لكل طلب.

3 - تعيين رأس عالمي في برونو

لتجنب إعادة المصادقة لكل طلب، قم بتعيين الرمز المميز كرأس مستوى تجميع:

1. انقر بزر الماوس الأيمن فوق مجموعتك وحدد الإعدادات.
   
   إعدادات التجميع
   
   
2. انتقل إلى علامة التبويب رؤوس الصفحات.
3. إضافة رأس جديد:
   • الاسم: رمز مصادقة X-Auth المميز
   • القيمة: [الصق الرمز المميز هنا]
     
     إدخال رؤوس عمومية لمجموعة API في Bruno.
     
4. انقر فوق حفظ.

عند هذه النقطة، قمت بإنشاء رمز المصادقة المميز لإجراء أي طلبات أخرى لواجهة برمجة تطبيقات Catalyst Center. 

مثال 1: إنشاء طابق موقع

يوضح هذا المثال كيفية إنشاء طابق ضمن التسلسل الهيكلي للشبكة (عمومي > TestArea > TestBuilding).

التسلسل الهرمي للشبكة

الخطوة 1: الحصول على معرف الأصل

أستخدم واجهة برمجة تطبيقات GET /dna/intent/api/v1/sites API للعثور على معرف TestBuilding.

• معلمة الاستعلام: nameHierarchy=global/TestArea/TestBuilding
• انسخ المعرف من الاستجابة؛ هذا هو معرف الأصل.

الحصول على طلب ل /dna/intent/api/v1/sites؟nameHierarchy=global/TestArea/TestBuilding

الخطوة 2: إنشاء الأرضية

1. إنشاء طلب POST ل /dna/intent/api/v2/floor.
2. أدخل في علامة التبويب النص (JSON) المعلمات المطلوبة:

{
  "name": "Floor 1",
  "parentId": "your-building-id-here",
  "floorNumber": 1,
  "rfModel": "Cubic-Office",
  "width": 100,
  "length": 100,
  "height": 10,
  "unitsOfMeasure": "feet"
}

3. طقطقة يرسل. الاستجابة الناجحة تؤكد إنشاء الأرضية.

طلب النشر لإنشاء الأرضية

الحصول على API للتحقق من إنشاء الأرضية من خلال طلب POST.

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

مثال 2: إسترداد معلومات الواجهة

يوضح هذا المثال كيفية إحضار حالة واجهة معينة على جهاز الشبكة.

الخطوة 1: تعريف معرف الجهاز

في واجهة المستخدم الرسومية Catalyst Center، انتقل إلى الجرد، وانقر على جهازك، وانظر إلى عنوان URL في المستعرض الخاص بك. المقطع الأخير هو معرف الجهاز.

الخطوة 2: إنشاء طلب ذي معلمات في برونو

1. قم بإنشاء طلب GET ل /dna/intent/api/v1/interface/network-device/{{deviceId}}.
2. في علامة التبويب Vars للطلب، قم بإضافة متغير باسم DeviceId ولصق المعرف الخاص بك.
3. للتصفية لمنفذ معين، أضف معلمة استعلام:
   • المفتاح: الاسم
   • القيمة: GigabitEthernet 1/0/5
     
     خلق متغيرات في برونو
     
     
4. طقطقة يرسل.

الحصول على طلب تطبيق استعلام

القرار

توفر واجهات برمجة التطبيقات (API) طراز Catalyst Center Northbound مرونة فائقة لمسؤولي الشبكات. من خلال الانتقال من الإدارة القائمة على واجهة المستخدم الرسومية (GUI) إلى عمليات سير العمل القائمة على واجهة برمجة التطبيقات (API)، يمكنك أتمتة المهام المتكررة وضمان تناسق التكوين ودمج ذكاء الشبكة في نظام تقنية المعلومات الأوسع لديك.

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

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