إستخدام واجهة برمجة تطبيقات Umbrella Reporting API عبر Postman

المقدمة

يوضح هذا المستند كيفية إستخدام واجهة برمجة تطبيقات Cisco Umbrella Reporting API في Postman.

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

المتطلبات

لا توجد متطلبات خاصة لهذا المستند.

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

تستند المعلومات الواردة في هذا المستند إلى Cisco Umbrella.

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

نظرة عامة

تم إصدار واجهة برمجة التطبيقات (API) Umbrella في سبتمبر 2022، مما يوفر نظاما أساسيا آمنا وسهل الاستخدام يمكن المستخدمين من البناء عليه وتوسيعه ودمجه مع Umbrella.

تتم إستضافة نقاط نهاية واجهة برمجة التطبيقات (API) Umbrella على api.umbrella.com، مع المسارات المجمعة لكل حالة إستخدام. يمكن إدارة مفاتيح API في كل من لوحة معلومات Umbrella، وتحت Admin > مفاتيح API، وبرمجية مع KeyAdmin API. ويمكن تكوين كل مفتاح بشكل شامل باستخدام نطاقات متعددة مجمعة ضمن خمس حالات إستخدام أساسية:

• تمكنك نقاط نهاية واجهة برمجة التطبيقات للمسؤول من توفير مفاتيح واجهة برمجة التطبيقات (API) ل Umbrella والمستخدمين وإدارتها وعرض الأدوار وإدارة العملاء لمزودي الخدمة والمزودين الذين تتم إدارتهم.
• تمكنك نقاط نهاية واجهة برمجة التطبيقات للمصادقة من تفويض عمليات تكامل الخدمات الأخرى مع النظام الأساسي Umbrella.
• تمكنك نقاط نهاية واجهة برمجة التطبيقات لعمليات النشر من توفير الشبكات والكيانات المختلفة الأخرى ومراقبتها وإدارتها وتأمينها من خلال تكوينها في سياسات Umbrella الحالية لديك.
• تمكنك نقاط نهاية واجهة برمجة التطبيقات الخاصة بالسياسات من تزويد وإدارة قوائم الوجهة والوجهات لكل قائمة.
• تمكنك نقاط نهاية واجهة برمجة تطبيقات التقارير من قراءة معلومات الأمان في الوقت الفعلي حول عمليات النشر ومراجعتها. توفر واجهة برمجة تطبيقات Umbrella App Discovery رؤى حول تطبيقاتك المستندة إلى السحابة.

توضح هذه المقالة كيفية جمع تقارير البحث عن النشاط عبر واجهة برمجة التطبيقات.

إجراء المظلة

1. من لوحة معلومات Umbrella، انتقل إلى Admin > مفاتيح API.

2. حدد مفاتيح API > إضافة.

3. ضمن النطاق الرئيسي، حدد التقارير، ثم قم بإنشاء المفتاح.

21495050167956

يمكن للمسؤولين ضبط مستوى الوصول لكل نطاق بين "القراءة/الكتابة" و"القراءة فقط"، وفقا للاستخدام المقصود لكل مفتاح API، بينما يمكن تكوين مفاتيح API بحيث تنتهي صلاحيتها في تاريخ محدد مسبقا. مطلوب منك تجميع مفتاح/سر واجهة برمجة التطبيقات في هذه الخطوة، نظرا لرؤيتهم حاليا، ولا يمكنهم الظهور بعد ذلك. 

تقوم بيانات اعتماد واجهة برمجة التطبيقات بإنشاء رموز وصول API المميزة الصالحة لمدة 60 دقيقة. يدعم هذا الإجراء تدفق بيانات اعتماد عميل OAuth 2.0. في بيئات Umbrella متعددة المؤسسات أو مزودي الخدمة، يمكن إستخدام بيانات اعتماد واجهة برمجة التطبيقات (API) الخاصة بالمؤسسة الأصلية لإنشاء رموز مميزة للوصول بنفس النطاقات الخاصة بمؤسسة فرعية محددة أثناء عملية التخويل.

إجراء ساعي البريد

في البداية، مطلوب منك إنشاء رمز مميز للوصول OAuth 2.0. تبدأ مسارات مصادقة واجهة برمجة التطبيقات (API) Umbrella ب https://api.umbrella.com/auth/v2. عند إرسال استعلام POST ومفتاح واجهة برمجة التطبيقات (API) الخاصة بالمستخدم وكلمة مرور واجهة برمجة التطبيقات (API) ككلمة مرور، يتم إنشاء رمز مميز للوصول.

21606708808468

21607051456276

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

أنت مطالب بتحديد أسلوب GET وإدخال كل من مسار واجهة برمجة التطبيقات (بما في ذلك المعلمة التي تطلبها) ورمز Access المميز. في هذا المثال، يمكنك إسترداد 100 تقرير من البحث عن النشاط بشكل حصري لحركة مرور DNS لمدة 7 أيام.

21607952074772

في مثال آخر، يمكنك محاولة إستخراج 1000 تقرير من البحث عن النشاط، حصريا لحركة مرور DNS لمدة 7 أيام الأخيرة، خاصة للمجال "gsa.apple.com".

21607927544468

يمكنك مراجعة معلمات استعلام الطلب لاكتشاف معلمات إضافية يمكنك إستخدامها في استعلام API.

ملاحظة: إذا لم ينشأ طلب عميل HTTP من القارة نفسها كموقع مستودع بيانات Umbrella، فإن خادم Umbrella يستجيب مع 302 الذي تم العثور عليه. لإعادة توجيه طلبات HTTP تلقائيا والاحتفاظ برأس تخويل HTTP، يمكنك تعيين علامات إضافية أو تمكين إعداد إعادة التوجيه.

كيرل: يجب أن تقوم بتمرير علامات -L أو —الموقع، و— الثقة بالموقع لإعادة توجيه طلب HTTP المتداخل والاحتفاظ برأس التخويل.

21608126036628

البريد: ضمن بيئة PostMan، انتقل إلى واجهة برمجة تطبيقات (API) وحدد طريقة GET. انتقل إلى الإعدادات > تمكين متابعة رأس التفويض للحفاظ على رأس التفويض لطلبات إعادة التوجيه.

21608126042388

الاستجابات

بعد إرسال إجراء GET إلى عنوان URL، يمكنك تلقي العديد من رموز الحالة:

• الحالة:200: نجح الطلب في أخذ المعلومات التي طلبتها.
• الحالة: 400: طلب غير صالح. يمكن أن يكون مرتبطا بعنوان URL الذي أرسلته للاستعلام. معلمة واحدة أو أكثر غير صحيحة.
• الحالة: 401: غير مصرح به. رأس التخويل مفقود أو الرمز المميز غير مصرح به.
• الحالة:403: ممنوع. الرمز المميز غير صالح.