نشر في الأصل في 20 فبراير 2019
لاحظ أن ساعي البريد هو أداة تطوير تابعة لجهة خارجية. توصي D2L بتقييم ملاءمة ساعي البريد داخل مؤسستك قبل استخدامها.
D2L ومعايير التكامل
في D2L ، لدينا وسنواصل أن نكون مؤيدين أقوياء لمعايير التكامل. في أواخر عام 2016، أضفنا دعم OAuth 2.0 لتطوير تطبيقات واجهة برمجة تطبيقات Brightspace. OAuth 2.0 هو إطار عمل مصادقة قياسي مفتوح يوفر تدفقات مصادقة متعددة، بما في ذلك تدفق OAuth ثلاثي الأرجل يسمح للمطورين بكتابة التطبيقات التي تصل إلى خدمات مختلفة نيابة عن المستخدم.
لاحظ أننا سنواصل دعم نموذج مصادقة زوج المعرف/المفاتيح، ولكن تركيزنا سينصب على الدعم المستمر والنمو ل OAuth 2.0. مثال على ذلك هو التحديث الأخير الذي أجريناه على تطبيق OAuth 2.0. في إصدار المنتج في مارس 2019، أضفنا دعما ل استخدام المعلمة Client_ID request لتعريف نفسه عند إرسال الطلبات إلى نقطة نهاية الرمز المميز. نأمل أن يكون هذا التحديث مفيدا للعديد من مطوري Brightspace.
لماذا أجرينا هذا التحديث؟
لن يؤثر تضمين قيمة Client_ID في أي من تطبيقات OAuth 2.0 الحالية. بخلاف كوننا أكثر التزاما بالمعيار ، سمعنا من عملائنا من خلال مجتمع المطورين أن تطبيق OAuth 2.0 الخاص بنا لم يكن متوافقا مع بعض أدوات واجهة برمجة التطبيقات التابعة لجهات خارجية. وبشكل أكثر تحديدا ، لم يتمكن مطورو Brightspace من استخدام Postman مع واجهة برمجة تطبيقات Brightspace لأنها تضمنت قيمة Client_ID في الطلب لإجراء تفاعل يستند إلى OAuth 2.0.
ما هو ساعي البريد؟
Postman هي أداة اختبار API الرائدة في السوق. وهو متاح للتنزيل على www.getpostman.com.
ساعي البريد قوي وسهل الاستخدام وله مركز الدعم مفيد جدا. من بين ميزاته العديدة ، نعتقد أن ما يلي سيكون مفيدا جدا لمطوري واجهة برمجة تطبيقات Brightspace:
- إنشاء بيئات تطوير (على سبيل المثال ، واحدة لموقع اختبار Brightspace الخاص بك وواحدة لموقع الإنتاج الخاص بك)
- إنشاء متغيرات البيئة (مثل Brightspace Domain وإصدار API)
- إنشاء مجموعات توفر القدرة على تشغيل استدعاءات واجهة برمجة تطبيقات متعددة بالتسلسل
- استخدام JavaScript لتمرير المتغيرات في استدعاء واجهة برمجة التطبيقات
- استخدام JavaScript لتخزين المتغيرات بعد استدعاء واجهة برمجة التطبيقات
ابدأ بتطبيق Brightspace OAuth 2.0
يتطلب استخدام Postman مع Brightspace تطبيق Brightspace OAuth 2.0. إذا لم يكن لديك بالفعل تطبيق OAuth 2.0، فيمكنك إما إنشاء تطبيق في مثيل Brightspace الخاص بك عن طريق الانتقال إلى كيفية بدء استخدام OAuth 2.0، أو استخدم التطبيق العام الموجود في بيئة تطوير Brightspace (تأكد من الانضمام إلى مجموعة مطوري البرامج للوصول إلى ملف "بيانات اعتماد مثيل المطور"، الذي يحتوي على تفاصيل تطبيق OAuth 2.0 العام).
إنشاء مجموعة ساعي بريد وربطها ب Brightspace
قبل البدء ، تأكد من أن لديك ساعي البريد المثبت. اتبع الخطوات التالية لإعداد مصادقة Postman باستخدام تطبيق Brightspace:
- قم بتشغيل ساعي البريد.
- يجب أن يطلب منك الشروع نافذة. تحت الإعداد الافتراضي إنشاء جديداختار مجموعة.
- حدد اسم لمجموعتك الجديدة (على سبيل المثال "اختبار واجهة برمجة تطبيقات Brightspace").
- حدد الزر إذن التبويب.
- من نوع القائمة المنسدلة، حدد OAuth 2.0.
- بالنسبة إلى إضافة بيانات المصادقة إلى القائمة المنسدلة، حدد رؤوس الطلب.
- نقر احصل على رمز وصول جديد.
- ال احصل على رمز وصول جديد تفتح النافذة. ستحتاج إلى تكوين كل حقل على النحو التالي:
- توفير اسم الرمز المميز القيمة (على سبيل المثال، "رمز بيئة Brightspace Dev").
- تعيين نوع المنحة إلى رمز التفويض.
- قم بتعيين عنوان URL لرد الاتصال على:
https://oauth.pstmn.io/v1/browser-callback
(حسب وثائق ساعي البريد OAuth 2.0) - قم بتعيين عنوان URL للمصادقة على: https://auth.brightspace.com/oauth2/auth
- قم بتعيين عنوان URL للرمز المميز للوصول إلى: https://auth.brightspace.com/core/connect/token
- معرف العميل يجب أن تتطابق مع قيمة معرف العميل من تطبيق Brightspace الخاص بك.
- سر العميل يجب أن تتطابق مع قيمة سر العميل من تطبيق Brightspace الخاص بك.
- نطاق يجب أن تتطابق مع قيمة النطاق من تطبيق Brightspace الخاص بك.
- حالة يمكن أن تكون أي قيمة. هذه القيمة هي ميزة أمان تهدف إلى الحماية من تزوير الطلبات عبر المواقع. لأغراض الاختبار ، هذه القيمة ليست مهمة جدا ؛ ولكن بالنسبة لتطبيقات الإنتاج ، تأكد من استخدام قيمة آمنة مشفرة.
- عميل إذن اضبط على إرسال كرأس مصادقة أساسية.
- نقر طلب رمز مميز. ستتم مطالبتك بنافذة تسجيل دخول لمثيل Brightspace الخاص بك. أدخل الرمز اسم المستخدم و شعار للمستخدم الذي ترغب في تنفيذ طلبات واجهة برمجة التطبيقات وانقر فوق تسجيل الدخول. إذا نجحت، يجب أن ترى مطالبة بالموافقة لتأكيد استخدام التطبيق. اقبل هذه المطالبة (لاحظ أن هذه المطالبة تحدث فقط للمستخدم في المرة الأولى التي يصل فيها إلى التطبيق).
- يجب أن تغلق النافذة وسترى رمز الوصول القيمة التي تم إدخالها في المجموعة. قم بالتمرير إلى أسفل النافذة وانقر على استخدم الرمز المميز.
- نقر خلق لإنشاء مجموعتك.
لديك الآن مجموعة ساعي بريد متصل ب Brightspace باستخدام OAuth 2.0. الخطوة التالية هي إضافة طلب واجهة برمجة تطبيقات إلى مجموعتك.
إضافة طلبات Brightspace إلى مجموعة Postman الخاصة بك
أحد الجوانب القوية ل Postman هو أنه يمكنك إضافة طلب واحد أو أكثر من طلبات واجهة برمجة التطبيقات إلى مجموعة.
لإضافة طلب إلى مجموعتك
- نقر الجديد.
- حدد طلب وأدخل اسم الطلب و وصف الطلب.
- تأكد من أن مجموعتك المحدد كموقع الحفظ. نقر حفظ في {مجموعتك}.
في هذه المرحلة ، ستتم إعادتك إلى الصفحة المقصودة لساعي البريد ، ولكن لديك الآن خيار إضافة طلب واجهة برمجة تطبيقات معين. يمكنك تزويد Postman بتفاصيل أي مسار Brightspace API تريد اختباره في هذه المرحلة. يمكنك إضافة طلب للحصول على قائمة بجميع الاختبارات الموجودة في مقرر دراسي معين.
- بالنسبة للحقل الأول، حدد حصل كأسلوب HTTP.
- في حقل عنوان URL للطلب، تحتاج إلى إنشاء نقطة نهاية واجهة برمجة التطبيقات الكاملة. يتضمن ذلك عنوان URL للمثيل.
- ابدأ بعنوان URL للمثيل.
- أدخل عنوان URL لواجهة برمجة التطبيقات التي تريد الاتصال بها (على سبيل المثال /d2l/api/le/(version)/(orgUnitId)/quizzes/).
- استبدل قيمة (الإصدار) بإصدار واجهة برمجة التطبيقات الحالي.
- استبدل orgUnitId الخاص بك بالمقرر الدراسي المراد استهدافه.
- انقر فوق الزر إذن علامة التبويب والتأكد من وراثة المصادقة من الأصل من أجل نوع تم تعيينه.
- مع إدخال تفاصيل الطلب وتحديد التفويض، انقر على ارسل لاختبار الطلب الجديد.
- يجب أن تتلقى الآن 200 رد مع سلسلة من الاختبارات المتوفرة حاليا للمستخدم لرؤيتها في orgUnit المحدد.
في حالة عدم وجود اختبارات ، يمكنك توقع خطأ 404 لعدم العثور على اختبارات. إذا لم يكن لدى المستخدم أذونات لمشاهدة الاختبارات ، فستتلقى خطأ 403 غير مصرح به.
الاستخدامات المتقدمة لساعي البريد
يحتوي Postman على ميزات إضافية توفر الوقت وتزيد من فهم مسار واجهة برمجة التطبيقات. يسمح ساعي البريد بالجمع و / أو البيئة المتغيرات. تمكنك هذه من استبدال القيم في طلباتك لإضافة نقاط نهاية جديدة بسرعة أو الاختبار في حالات مختلفة. فيما يلي بعض الأفكار لمساعدتك على البدء:
- قم بإنشاء متغير بيئة يحدد عنوان URL لمثيل Brightspace الخاص بك
- إنشاء متغير إصدار لتخزين القيمة المتوفرة في عناوين URL لواجهة برمجة التطبيقات
ميزة أخرى رائعة هي البرامج النصيه. يحتوي Postman على بيئة وقت تشغيل (استنادا إلى Node.js) تسمح لك بإضافة تعليمات برمجية ديناميكية إلى طلباتك إما عند الطلب المسبق أو بعد إجراء المكالمة مباشرة. يمكن للمستخدمين إضافة البرامج النصية للطلب المسبق واللاحق إلى مجلدات المجموعات أو الطلبات المحددة. تعد البرامج النصية رائعة لمواقف مثل:
- استقصاء إصدار واجهة برمجة التطبيقات للمثيل وتوفير القيمة في متغير لطلب لاحق
- حفظ قيمة OrgUnitId وتمريرها للبحث في طلب لاحق
- تنفيذ وظيفة حساب قبل إرسال البيانات في واجهة برمجة تطبيقات POST
مشكلات مع ساعي البريد و Brightspace
كان تقييمنا لساعي البريد واعدا وإيجابيا. ومع ذلك ، فقد واجهنا مشكلتين يجب أن تكون على دراية بهما.
مسح ملفات تعريف الارتباط: في وقت نشر هذا المقال ، لاحظنا أنه لا توجد مشكلات في المرة الأولى التي يتم فيها إنشاء رموز OAuth المميزة. ومع ذلك ، فإن المحاولات اللاحقة بها مشاكل. لحل هذه المشكلة، نوصي بما يلي: مسح ملفات تعريف الارتباط داخل ساعي البريد.
لا توجد إعادة توجيه لتسجيل الدخول: عند إنشاء رمز OAuth المميز، يتم إرسال المستخدم من ساعي البريد إلى صفحة تسجيل الدخول لمثيل Brightspace الذي يطور مقابله. لا توجد خيارات لإعادة التوجيه إلى صفحة تسجيل دخول مختلفة إلى Brightspace داخل متصفح Postman المدمج. هذه مشكلة فقط إذا لم يكن حساب المستخدم الذي تقوم بالتطوير به مسجلا لدى موفر الهوية لصفحة تسجيل الدخول الرئيسية.
نحن نقيم كلا المسألتين المذكورتين أعلاه. ومع ذلك ، نعتقد أنهما قضيتان داخل ساعي البريد. سنكون منفتحين على الاقتراحات حول كيفية تجاوز هذه المشكلات بشكل أفضل ، وسنقدم أي تحديثات نتلقاها في هذه المقالة.
استنتاج
أخبرنا بتجربتك في استخدام ساعي البريد وشاركنا أي مجموعات ساعي بريد تقوم بتطويرها. إذا كان هناك عميل اختبار واجهة برمجة تطبيقات آخر تفضله على Postman ، فنحن نود أن نعرف حتى نتمكن أيضا من اختباره.
لمزيد من التدريب على استخدام ساعي البريد ، راجع تعلم ساعي البريد مع بول.
الشكل: عرض تفاصيل الطلب على شاشة الطلب.
