قبل البدء
يجب أن يكون لديك هذه المعلومات:
- زوج Id-Key الخاص بالتطبيق الخاص بك (لنفترض "appID" و "appKey" ، لكنهما لن يبدوان هكذا)
- نطاق الخدمة الخلفية (التي تتصل بها نظام إدارة التعلم (الذي تتصل به)
- نقطة معاودة الاتصال لتطبيقك / خدمتك حيث يمكن لنظام إدارة التعلم ارسل أزواج مفتاح معرف المستخدم عند طلبها
إنشاء حساب الخدمة وحصاد الرموز المميزة للمستخدم
سيحتاج تطبيقك إلى التشغيل باستخدام حساب خدمة أو حساب آخر يتمتع بامتيازات كافية لتنفيذ الإجراءات التي تحتاج إلى اتخاذها باستخدام واجهات برمجة التطبيقات. لذلك ، فإن الخطوة الأولى هي إنشاء حساب في بيئة التعلم بامتيازات كافية لإجراء استدعاءات واجهة برمجة التطبيقات التي تحتاج إلى إجرائها.
بمجرد إنشاء حساب خدمة:
- تحتاج إلى حصاد الرموز المميزة للمستخدم يدويا باستخدام أداة مساعدة مثل أداة اختبار واجهة برمجة التطبيقات () للمصادقة مع نظام إدارة التعلم الخاص بك.
- قم بتخزين هذه المفاتيح بشكل آمن، وقم بتكوين نظام إدارة التعلم الخاص بك لضمان أن تكون رموز المستخدم طويلة الأمد. تحتوي العديد من الأنظمة على مهلة رمزية مدتها 30 يوما ، ولكن عندما يكون التكامل مقطوعة الرأس في مكانه مثل التكامل الذي تقترحه ، فغالبا ما يكون من الجيد جعل المهلة غير محدودة. يمكنك الاتصال بدعم Desire2Learn للتحقق من قيمة المهلة للرموز المميزة للمستخدم.
ملاحظة: لا تعني "رموز المستخدم المميزة" أعلاه المهلة المحددة عبر d2l. إعداد خادم SessionTimeout. بدلا من ذلك ، يتم تعيين هذا عبر d2l. إعداد Security.Api.TokenTimeout.
لمزيد من التوضيح:
- ال d2l. يشير متغير تكوين SessionTimeout إلى فترة المهلة لجلسة الويب (أي المدة التي يمكن أن يظل فيها شخص ما خاملا قبل انتهاء مهلة واجهة مستخدم الويب LMS وتطالب المستخدم بتسجيل الدخول مرة أخرى). غالبا ما يتم تعيين هذه المهلة على فاصل زمني من عدة دقائق إلى ساعة.
- ال d2l. يشير متغير التكوين Security.Api.TokenTimeout إلى فترة المهلة لزوج معرف المستخدم\مفتاح المقترن بعملية مصادقة التكافؤ. بعبارة أخرى ، هذه الرموز المميزة هي القيمة x_b وأساس القيمة x_d التي يتم إرسالها كمعلمات استعلام في كل استدعاء لواجهة برمجة التطبيقات لتحديد المستخدم. غالبا ما يتم تعيين هذه المهلة على فاصل زمني مدته عدة أيام، أو يمكن ضبطها على مهلة عدم انتهاء المهلة أبدا. في الحالة الأخيرة، لا يمكن إبطال معرف المستخدم\زوج المفاتيح إلا عن طريق تغيير كلمة مرور المستخدم أو إبطال الوصول إلى التطبيق بشكل صريح. بمجرد أن يصبح معرف المستخدم\زوج المفاتيح غير صالح، سيتعين على التطبيق إعادة بدء عملية المصادقة لتلقي معرف مستخدم جديد\زوج مفتاح لتوقيع استدعاءات واجهة برمجة التطبيقات.
إنشاء سياق تطبيق
- إنشاء سياق تطبيق باستخدام D2LAppContext ("appID" ، "appKey" ، "") ؛ هذا يصمم سياق التطبيق الذي يمكنك استخدامه بعد ذلك لتقديم طلب لجلب زوج من معرف المستخدم من LMS
- authURL = DAC.createWebUrlForAuthentication( URI جديد("")); هذا يجعل "authURL" ، تحتاج إلى توجيه حاوية ويب (متصفح المستخدم) إلى عنوان URL هذا: الذي يطلب من LMS إرسال زوج معرف المستخدم مرة أخرى لجلسة المستخدم التي سيتم إنشاؤها داخل حاوية الويب الطالبة.
سيرسل LMS زوج معرف المستخدم عن طريق إعادة التوجيه العودة إلى مع إرفاق زوج معرف المستخدم كمعلمات استعلام على عنوان URL لإعادة التوجيه. دعنا نسمي هذا كامل عنوان URL لإعادة التوجيه 'fullRedirectUrl'.
إنشاء سياق مستخدم
- يمكنك اما إنشاء سياق مستخدم باستخدام fullRedirectUrlDAC.createUserContext( fullRedirectUrl):
- أو، يمكنك استخراج زوج معرف المستخدم من fullRedirectUrl (لنفترض "userID" و "userKey" ، لكنهما سيبدوان مختلفين) ، واستخدام: DAC.createUserContext ("userID" ، "userKey" )
إجراء مكالمات
- يمكنك الآن استخدام سياق المستخدم الخاص بك ، DUC ، لإجراء مكالمات: DUC.createAuthenticatedUri ("/d2l/api/lp/1.3/users/whoami", "GET")
ملاحظه: أنك هنا توفر مسار واجهة برمجة التطبيقات فقط، بالإضافة إلى طريقة HTTP (الأحرف الكبيرة)؛ تأكد من استخدام مسار في عقد واجهة برمجة التطبيقات الذي يدعمه نظام إدارة التعلم الخلفي - هنا نجري مكالمة Whoami من عقد واجهة برمجة التطبيقات v1.3، ولكن قد لا يدعم نظام إدارة التعلم هذا العقد (أو قد يدعم عقدا أحدث).
استكشاف الاخطاء
سؤال: لكي أكون واضحا ، أنا آخذ "... أو" المسار المذكور أعلاه ، عن طريق استخراج قيم معرف المستخدم ومفتاح المستخدم من apitest. desire2learnvalence.com، ثم القيام ب createUserContext باستخدام هذه القيم (جنبا إلى جنب مع اسم مضيف D2L ، والمنفذ ، وما إلى ذلك --- إصدار 6 معلمات من تلك الوظيفة).
أحصل على سياق مرة أخرى من هذه الطريقة وعندما أستخدمها لإجراء استدعاء واجهة برمجة التطبيقات ، ترجع الخدمة 403 "رمز غير صالح".
جواب: إذا لم يكن تطبيقك معروفا لنظام إدارة التعلم (أي لم يكن معرف تطبيق ممكنا) فستحصل على خطأ مختلف قليلا. هذا يخبرنا أن اما أنت لا تقوم بإجراء تطبيق صالح في استدعاء واجهة برمجة التطبيقات النهائي (مما يعني على الأرجح أن مفتاح التطبيق الخاص بك غير مناسب لمعرف التطبيق الخاص بك) ، أو مفتاح معرف المستخدم الذي تستخدمه غير مفيد بطريقة ما.
نوصي بشدة بالمرور عبر مستندات SDK لعميل Python حتى لو كنت لا تنوي استخدام Python على المدى الطويل. يمكنك متابعة هذه العملية بشكل تفاعلي وخطوة بخطوة ، وبالتالي الحصول على مزيد من التحكم المباشر في ما يحدث في كل خطوة في العملية لمعرفة ما يحدث. باستخدام تطبيق مؤسسي مبني من C # أو Java ، فأنت تنتقل إلى تقنيات تصحيح الأخطاء القياسية لتشعر بطريقك من خلال سير العمل - والتي تعمل أيضا بشكل جيد: ومع ذلك ، تتيح لك القشرة التفاعلية تنفيذ كل خطوة أثناء تقدمك وفحص النتائج.
لبدء استخدام python SDK كما هو الحال في هذه الإرشادات التفصيلية ، تحتاج إلى:
- لتثبيت Python ، ومن المفيد تثبيت حزمة "pip" للقيام بتثبيت وحدة python
- لتثبيت وحدة python "الطلبات" (التي يجب أن تجدها النقطة تلقائيا)
- لتثبيت وحدة python "d2lvalence" (التي يجب أن تجدها النقطة تلقائيا)
سؤال: ذهبت لإلقاء نظرة على صفحة مصادقة Python التي أشرت إليها ، لكنني في حيرة من أمري. تنصحني هذه الصفحة بالانتقال إلى المتصفح والتقاط عنوان URL لإعادة التوجيه بعد الحصول على النتيجة مرة أخرى من createUrlForAuthentication (باستخدام تنسيق php للوظيفة).
جواب:
الطريقة التي يعمل بها النموذج على مستوى عال هي كنموذج مصادقة ثلاثي الأرجل:
- لديك مستخدم حقيقي مع متصفح
- لديك خدمة أو تطبيق تابع لجهة خارجية يمكن للمستخدم زيارته (عادة) ويريد إجراء مكالمات واجهة برمجة تطبيقات التكافؤ نيابة عن هذا المستخدم
- لديك نظام إدارة التعلم الخلفي
عندما يزور المستخدم الحقيقي تطبيق الطرف الثالث ، قبل أن يتمكن من إجراء مكالمات واجهة برمجة التطبيقات ، يحتاج إلى أن يطلب من LMS زوج معرف مفتاح المستخدم للذهاب مع زوج معرف التطبيق الخاص به حتى يتمكن من إجراء مكالمات واجهة برمجة التطبيقات نيابة عن المستخدم. للقيام بذلك ، فإنه يعيد توجيه متصفح المستخدم إلى "مسار تسجيل الدخول" الخاص بنظام إدارة التعلم للتأكد من أن LMS "يعرف" من هو المستخدم / المتصفح:
- إذا كان متصفح المستخدم يحتوي بالفعل على جلسة ويب مع LMS ، فيمكن ل LMS أن يقول "أعرف من هو المستخدم" وإرسال زوج معرف المستخدم الصحيح إلى تطبيق الطرف الثالث.
- إذا لم يكن لدى متصفح المستخدم جلسة عمل حتى الآن ، فيمكن لنظام إدارة التعلم السعي إلى مصادقة المستخدم باستخدام الطريقة القياسية لنظام إدارة التعلم هذا. ثم يمكنه إرسال زوج معرف المستخدم الصحيح مرة أخرى إلى تطبيق الطرف الثالث. (لاحظ أنه في كلتا الحالتين ، يتم إنشاء زوج معرف المستخدم خصيصا لهذا المستخدم وتطبيق THAT: لا يمكن نقله إلى أي زوج آخر من مفاتيح معرف التطبيق.)
يعد نظام المصادقة ثلاثي الأرجل هذا منطقيا في حالة وجود ثلاثة أطراف منفصلة بالفعل. في حالات مثل حالتك ، حيث تريد كتابة تطبيق خدمة تكنولوجيا المعلومات (بدون رأس) لا يحتوي على "مستخدم يعمل حاليا مع متصفح الويب الخاص به" ، نوصي عادة بإنشاء حساب خدمة - غرض خاص ، "مستخدم" و "دور" يتم استخدامه فقط لتطبيق الخدمة الخاص بك.
في هذه الحالة ، يجب أن يكون لديك طريقة لمتابعة عملية المصادقة المذكورة أعلاه في كل مرة تحتاج فيها إلى زوج معرف مستخدم صالح لخدمة "المستخدم" هذه. هناك مجموعة من الطرق للقيام بذلك ، لكنها جميعا تنطوي على وجود (في مرحلة ما) مستخدم حقيقي لديه متصفح حقيقي يقف ويلعب دور تلك المحطة الثالثة في عملية المصادقة.
عادة ما تفعله هو إما استخدام نسخة مستضافة محليا من إحدى عيناتنا البسيطة ، أو "أداة اختبار API" عبر الإنترنت (https://apitesttool. desire2learnvalence.com/)، أو جلسة Python تفاعلية مع Python SDK (كما هو الحال في إرشادات المصادقة التي أشرت إليها). عادة ، للحصول على أفضل أمان ، نوصي بإجراء هذه العملية داخل بيئة آمنة ، لذلك ربما لا تكون أداة اختبار API هي الحل الأفضل ، خاصة إذا كنت لن تتصل ب HTTPS ، لأنها تجلس على الإنترنت. ومع ذلك ، إذا كنت تستخدم HTTPS لتوصيله بنظام إدارة التعلم الخاص بك ، فمن المحتمل أن يكون آمنا بدرجة كافية.
لعملية "جمع زوج معرف المستخدم ومفتاح المعرف" ، تحتاج إلى استخدام بيانات اعتماد مفتاح معرف التطبيق الخاص بك (أي الزوج الذي تلقيته للتطبيق / الخدمة التي تكتبها).
إذا كنت تفعل ذلك بشكل تفاعلي، فإنك تنشئ سياق تطبيق باستخدام بيانات الاعتماد هذه. إذا كنت تستخدم عينة أو أداة عبر الإنترنت ، فإنك توفر زوج معرف التطبيق الخاص بك كزوج لاستخدامه (وليس المفاتيح الافتراضية في النموذج: هذه مجموعة واحدة من المفاتيح العامة لأغراض العرض التوضيحي). يجب عليك تقديم اسم المضيف لنظام إدارة التعلم الخاص بك ، والمنفذ للاتصال به. ثم تمر ب "عملية المصادقة":
- إذا كنت تستخدم جلسة تفاعلية مع Python SDK ، فيمكنك إنشاء "عنوان URL للمصادقة" الذي ستقوم بقصه ولصقه في متصفحك ... للقيام بذلك ، تحتاج أيضا إلى توفير "عنوان URL لرد الاتصال" يخبر LMS بمكان إرسال مفتاح معرف المستخدم - نقترح المضيف المحلي لأنه سيعود إلى الكمبيوتر حيث يوجد متصفحك ، ومن المحتمل أن يشكو متصفحك من أنه لا يمكنه العثور على عنوان URL ، ولكن يمكنك بعد ذلك نسخ عنوان URL المكتمل من شريط العناوين.
- إذا كنت تستخدم النموذج أو الأداة عبر الإنترنت ، إخفاء "عنوان URL لرد الاتصال" عنك - يوفره النموذج تلقائيا: سيتم إرسال زوج معرف المستخدم مرة أخرى إلى خادم الويب الذي يقوم بتشغيل الأداة العينة / عبر الإنترنت.
عند إعادة زوج معرف المستخدم ، سيضعها LMS كمعلمات استعلام على "عنوان URL لرد الاتصال" الذي قدمته في الطلب الذي أرسلته للتو.
- إذا كنت تستخدم الأداة عبر الإنترنت أو عينة ، فيجب أن تقوم الأداة / العينة بتحليل عنوان URL لرد الاتصال هذا تلقائيا ، وإزالة بيانات الاعتماد وإظهارها لك.
- إذا كنت تستخدم جلسة Python تفاعلية، فسيقوم LMS بإعادة التوجيه إلى "المضيف المحلي" ومعالجة زوج معرف المستخدم في معلمات الاستعلام. انسخ عنوان URL بالكامل من شريط عنوان المتصفح ، وقم بإدخاله مرة أخرى في جلسة Python الخاصة بك لإنشاء "سياق المستخدم" - سيؤدي ذلك إلى تقشير مفاتيح معرف المستخدم من عنوان URI للنتيجة هذه ، وإنشاء سياق مستخدم لك يمكنك استخدامه لإجراء استدعاءات API بشكل تفاعلي ... يمكنك أيضا فحصه لمعرفة ماهية زوج معرف المستخدم ، وحفظه على القرص ، وما إلى ذلك.
على أي حال ، لم تنجح في "جمع زوج معرف المستخدم" لحساب الخدمة الخاص بك للذهاب مع مفتاح معرف التطبيق الخاص بك. يمكنك تخزين ذلك مؤقتا في مكان آمن يمكن الوصول إليه من خلال النص البرمجي / التطبيق المسؤول (كما هو الحال في ملف الضبط). نوصي بشدة بالتعامل مع زوج معرف التطبيق الخاص بتطبيقك وجميع مفاتيح معرف المستخدم التي تصاحبه كمعلومات حساسة للغاية - مع هذه الرموز المميزة يمكن لأي شخص إجراء مكالمة إلى نظام إدارة التعلم الخاص بك متظاهرا بأنه تطبيقك كمستخدم صالح ، لذلك ترغب في وضعها في مكان آمن مرئي فقط لعدد قليل من الأشخاص وللبرنامج النصي / التطبيق الذي يحتاج إلى استخدامها.
عندما تتغير كلمة المرور لحساب الخدمة هذا، ستحتاج إلى إجراء هذه العملية مرة أخرى لجمع زوج جديد من معرف المستخدم ومفتاح المعرف. إذا كان نظام إدارة التعلم الخاص بك يحتوي على رموز مميزة لواجهة برمجة التطبيقات تم تعيينها لتنتهي صلاحيتها في وقت محدد، فستحتاج أيضا إلى إعادة تنفيذ هذه العملية عند انقضاء هذا الوقت. يتم تعيين وقت انتهاء صلاحية LMSes بشكل افتراضي على "غير محدد" ولا تنتهي صلاحية الرموز المميزة لمفتاح معرف المستخدم إلا عندما تتغير كلمة مرور المستخدم ، أو يرفض مسؤول الموقع الوصول إلى تطبيقات الجهات الخارجية لهذا المستخدم.
للحصول على نقطة توضيح أخرى ، يمكنك الاطلاع على هذا الموضوع على مدونة المطورين الخاصة بنا: بدء مصادقة مفتاح معرف التطبيق. عمرها عدة سنوات ، لكن المادة لا تزال صحيحة ، وتختلف المخططات عن تلك التي تظهر في مستنداتنا عبر الإنترنت ، بحيث يمكن أن يساعد هذا التباين في الحصول على صورة مستديرة.https://d2l.someUniversity.eduhttps://yourServer.org/authCallback
https://apitesttool.desire2learnvalence.com/
https://d2l.someUniversity.eduhttps://yourServer.org/authCallbackhttps://yourServer.org/authCallback