ابدأ مع واجهة برمجة تطبيقات Microsoft Learn Platform

تساعدك هذه المقالة في البدء باستخدام واجهة برمجة تطبيقات Microsoft Learn Platform. إذا لم تكن على دراية بتفاصيل واجهة برمجة التطبيقات أو حالات استخدامها، ننصحك بمراجعة مقالة نظرة عامة على واجهة برمجة تطبيقات Microsoft Learn Platform أولا.

تعلم مصادقة واجهة برمجة التطبيقات للمنصة

تستخدم واجهات برمجة التطبيقات REST الخاصة بمنصة التعلم Microsoft Entra ID للمصادقة. قبل إجراء استدعاءات API، تحتاج إلى اختيار طريقة وصول، ويجب أن يتحقق تطبيق العميل الخاص بك ببيانات اعتماد صحيحة.

الوصول إلى التطبيق فقط

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

للبدء، تحتاج إلى هوية صالحة على منصة Microsoft Identity، والتي قد تكون تسجيل تطبيق أو هوية مدارة. من الناحية المثالية، يجب أن يكون لكل شريك هوية واحدة لتبسيط إدارة الحصص والشريك. استخدام هوية مدارة معينة من قبل المستخدم يمكن أن يساعد في توحيد الهويات المدارة عبر خدمات مختلفة.

بمجرد إعداد هوية Entra ID الخاصة بك، احصل على رمز وصول من Entra ID مع تعيين النطاق كدليل على المصادقة. أدرج رمز الوصول في رأس تفويض HTTP عند إجراء طلبات REST API للتعلم.

الوصول المفوض

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

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

• : يتيح هذا النطاق للمستخدمين الوصول إلى المحتوى العام على Learn وهم ينتفون بأنه المستخدم المسجل.

فهم إصدار إعدادات واجهة برمجة التطبيقات لمنصة Microsoft Learn

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

يتم تحديد نسخة API كمعامل استعلام إصدار API وتستخدم yyyyy-MM-dd للإصدارات المستقرة وyyyy-MM-dd-preview للإصدارات المسبقة. معامل استعلام إصدار API مطلوب لكل طلب واجهة برمجة تطبيقات (API).

عند إصدار نسخة جديدة مستقرة من واجهة برمجة التطبيقات (ABI)، يتم دعم النسخة السابقة من الواجهة المستقرة لمدة لا تقل عن 24 شهرا إضافية بعد إصدار النسخة الجديدة. تمتلك واجهات برمجة التطبيقات المسبقة دورة دعم أقصر بثلاثة أشهر إضافية بعد إصدار واجهات برمجة التطبيقات الجديدة للمعاينة.

الإصدار الحالي هو 2023-11-01-preview.

مقطع /v1/ قبل كل واجهة برمجة تطبيقات هو جزء من الرابط الأساسي وليس نسخة API. وهو مخصص لتغييرات كبيرة في بروتوكولات وأنماط API في المستقبل.

تعلم تحديد معدل واجهة برمجة التطبيقات للمنصة

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

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

افتراضيا، الحد الأقصى للمعدل هو 100 استدعاء API في الدقيقة، محسوبة خلال نافذة مدتها 5 دقائق. إذا كنت بحاجة إلى حد أعلى للإنتاج، يمكنك التواصل مع دعم Learn Integrations لطلب زيادة.

بعض واجهات برمجة التطبيقات، مثل واجهة بحث المعرفة، تطبق أيضا تحديد معدل الرموز المعتمدة على الرموز. يعتمد ذلك على عدد رموز Microsoft Azure OpenAI المستهلكة، مع حد افتراضي يبلغ 10,000 رمز في الدقيقة. لزيادة هذا الحد في الإنتاج، تواصل مع دعم Learn Integrations.

تعلم ترقيم واجهة برمجة التطبيقات للمنصة

جميع موارد واجهات برمجة التطبيقات العليا تدعم الاسترجاع الجماعي عبر طرق "قائمة" في واجهات برمجة التطبيقات (API). على سبيل المثال، يمكنك استرجاع قوائم الوحدات أو الامتحانات. تعيد هذه الطرق ردودا مصفحة وفقا لنهج موحد.

تستخدم طرق واجهات برمجة التطبيقات القائمة التصفحات القائمة على المؤشر الترقيم المعتمد على المؤشر، ويشار إليه بحقل nextLink في جسم الاستجابة. يحتوي هذا الحقل على عنوان URL غير شفاف يحتوي على المعلومات اللازمة لجلب الصفحة التالية من النتائج. بشكل افتراضي، تعيد واجهات برمجة التطبيقات القائمة 30 عنصرا لكل طلب، لكن يمكنك تعديل حجم الصفحة باستخدام معامل maxpagesize.

توفر مكتبات SDK لعملائنا مساعدين في التصفح التلقائي لتصفح جميع صفحات القائمة.

المحتوى ذو الصلة

• البدء السريع: إعداد واستخدام بيانات كتالوج واجهة برمجة تطبيقات Microsoft Learn Platform
• مرجع مطور بيانات فهرس واجهة برمجة تطبيقات منصة التعلم
• الأسئلة الشائعة حول واجهة برمجة تطبيقات Learn Platform