نظرة عامة على مدخل المطور

  • مقالة

ينطبق على: المطور | أساسي | الإصدار 2 الأساسي | قياسي | الإصدار 2 القياسي | بريميوم

مدخل مطور APIM هو موقع ويب تم إنشاؤه تلقائيا وقابل للتخصيص بالكامل مع وثائق واجهات برمجة التطبيقات الخاصة بك. إنه المكان الذي يمكن لمستهلكي واجهة برمجة التطبيقات اكتشاف واجهات برمجة التطبيقات الخاصة بك، وتعلم كيفية استخدامها، وطلب الوصول، وتجربتها.

تقدم هذه المقالة ميزات مدخل المطور وأنواع المحتوى الذي يقدمه المدخل وخيارات لإدارة وتوسيع مدخل المطور لمستخدمين وسيناريوهات محددة.

إشعار

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

لقطة شاشة لمدخل مطور APIM.

ينطبق على: المطور | أساسي | قياسي | بريميوم

المفاهيم البنيوية لمدخل المطور

يمكن منطقياً تقسيم مكونات المدخل إلى فئتين: التعليمة البرمجية والمحتوى.

رمز

يتم الاحتفاظ بالتعليمة البرمجية في مدخل مطور APIM لمستودع GitHub ويتضمن:

  • عناصر واجهة المستخدم - تمثل العناصر المرئية والجمع بين HTML، JavaScript، والقدرة على التصميم، والإعدادات، ورسم خرائط المحتوى. ومن الأمثلة على ذلك الصورة، الفقرة النصية، النموذج، قائمة من واجهات برمجة التطبيقات إلخ.
  • تعريفات التصميم - حدد كيف يمكن تصميم عناصر واجهة المستخدم
  • المحرك - الذي يؤدي إلى إنشاء صفحات ويب ثابتة من محتوى المدخل ومكتوب في JavaScript
  • المحرر المرئي - يسمح بالتخصيص في المستعرض وتجربة التأليف

المحتوى

ينقسم المحتوى إلى فئتين فرعيتين: محتوى المدخل وبيانات APIM.

  • محتوى المدخل خاص بموقع المدخل على الويب ويتضمن:

    • الصفحات - على سبيل المثال، الصفحة المقصودة، البرامج التعليمية لواجهة برمجة التطبيقات، منشورات المدونة

    • الوسائط - الصور والرسوم المتحركة والمحتوى المستند إلى الملفات الأخرى

    • التخطيطات - القوالب المتطابقة مع عنوان URL وتحديد كيفية عرض الصفحات

    • الأنماط - قيم لتعريفات التصميم، مثل الخطوط والألوان والحدود

    • الإعدادات - تكوينات مثل favicon، بيانات تعريف الموقع

      يتم التعبير عن محتوى المدخل، باستثناء الوسائط، كمستندات JSON.

  • تتضمن بيانات APIM كيانات مثل واجهات برمجة التطبيقات والعمليات والمنتجات والاشتراكات التي تتم إدارتها في مثيل APIM.

تخصيص المدخل ونمطه

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

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

للحصول على معاينة خطوة بخطوة لتخصيص ونشر مدخل المطور، راجع البرنامج التعليمي: الوصول إلى مدخل المطور وتخصيصه.

هام

  • يتطلب الوصول إلى مدخل المطور من قبل ناشري API والمستهلكين اتصال الشبكة بكل من نقطة نهاية مدخل المطور (الافتراضي: https://<apim-instance-name>.portal.azure-api.net) ونقطة نهاية إدارة مثيل APIM (الافتراضي: https://<apim-instance-name>.management.azure-api.net).
  • يتطلب نشر مدخل المطور اتصالا إضافيا لتخزين الكائن الثنائي كبير الحجم الذي تديره إدارة واجهة برمجة التطبيقات في منطقة غرب الولايات المتحدة.
  • إذا تم نشر مثيل APIM في VNet، فتأكد من أن أسماء مضيفي مدخل المطور ونقطة نهاية الإدارة تحل بشكل صحيح وأنك تمكن الاتصال بالتبعيات المطلوبة لمدخل المطور. اعرف المزيد.

Visual editor

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

بصفتك مسؤولا، يمكنك تخصيص محتوى المدخل باستخدام المحرر المرئي.

لقطة شاشة للمحرر المرئي في مدخل المطور.

  • استخدم خيارات القائمة على اليسار لإنشاء صفحات أو وسائط أو تخطيطات أو قوائم أو أنماط أو إعدادات موقع ويب أو تعديلها.

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

  • أيضا، احفظ التغييرات التي تجريها أو تراجعها، أو انشر موقع الويب.

  • حدد عناصر النص والعنوان الموجودة لتحرير المحتوى وتنسيقه.

  • أضف مقطعا إلى صفحة عن طريق تمرير الماوس فوق منطقة فارغة ثم انقر فوق أيقونة زرقاء بعلامة الجمع. اختر من بين العديد من تخطيطات المقاطع.

    لقطة شاشة تعرض أيقونة إضافة قسم في مدخل المطور.

  • أضف عنصر واجهة مستخدم (على سبيل المثال، النص أو الصورة أو عنصر واجهة المستخدم المخصص أو قائمة واجهات برمجة التطبيقات) عن طريق تمرير الماوس فوق منطقة فارغة، ثم انقر فوق أيقونة رمادية بعلامة الجمع.

    لقطة شاشة تعرض أيقونة إضافة عنصر واجهة مستخدم في مدخل المطور.

  • إعادة ترتيب العناصر في صفحة عن طريق السحب والإفلات.

التخطيطات والصفحات

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

يتم تطبيق تخطيط الصفحة من خلال مطابقة قالب عنوان URL الخاص به مع عنوان URL للصفحة. على سبيل المثال، يتم تطبيق تخطيط مع قالب URL لكل /wiki/* صفحة مع /wiki/ المقطع في عنوان URL: /wiki/getting-started، /wiki/styles، وما إلى ذلك.

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

لقطة شاشة لمحتوى التخطيط في مدخل المطور.

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

إشعار

نظراً لاعتبارات التكامل، لا يمكن إزالة الصفحات التالية أو نقلها ضمن عنوان URL مختلف: /404, /500, /captcha, /change-password, /config.json, /confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password, /internal-status-0123456789abcdef, /publish, /signin, /signin-sso, /signup.

أنماط

لقطة شاشة لدليل التصميم في مدخل المطور.

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

لتحرير متغير، حدده وحدد تحرير النمط في الخيارات التي تظهر أعلىه. بعد إجراء التغييرات في النافذة المنبثقة، أغلقها.

توسيع وظائف المدخل

في بعض الحالات، قد تحتاج إلى وظائف تتجاوز خيارات التخصيص والتصميم المزودة في مدخل المطور المُدار. إذا كنت بحاجة إلى تنفيذ منطق مُخصص، وهو غير مدعوم خارج الصندوق، تتوفر لديك العديد من الخيارات:

  • أضف HTML مخصص مباشرة من خلال عنصر واجهة مستخدم مدخل المطور المُصمم للتخصيصات الصغيرة - على سبيل المثال، إضافة HTML لنموذج أو لتضمين مشغل فيديو. يتم عرض التعليمات البرمجية المخصصة في إطار مضمن (IFrame).
  • إنشاء وتحميل عنصر واجهة مستخدم مخصص لتطوير وإضافة ميزات مدخل مخصصّة أكثر تعقيدًا.
  • المضيف الذاتي للمدخل، فقط إذا كنت بحاجة إلى إجراء تعديلات على الذاكرة الأساسية لقاعدة التعليمات البرمجية لمدخل المطور. يتطلب هذا الخيار تكوينًا متقدمًا. تقتصر مساعدة دعم Azure فقط على الإعداد الأساسي للمداخل ذاتية الاستضافة.

إشعار

نظرًا لأنه يتم الاحتفاظ بقاعدة التعليمات البرمجية لمدخل مطور APIM على GitHub، يمكنك فتح المشكلات وتقديم طلبات سحب لفريق APIM لدمج وظائف جديدة في أي وقت.

التحكم في الوصول إلى محتوى المدخل

تتم مزامنة مدخل المطور مع مثيل APIM لعرض محتوى مثل واجهات برمجة التطبيقات والعمليات والمنتجات والاشتراكات وملفات تعريف المستخدمين. يجب أن تكون واجهات برمجة التطبيقات والمنتجات في حالة منشورة لتكون مرئية في مدخل المطور.

رؤية المحتوى والوصول إليه

في APIM، يتم استخدام مجموعات من المستخدمين لإدارة رؤية المنتجات وواجهات برمجة التطبيقات المرتبطة بها للمطورين. بالإضافة إلى استخدام المجموعات المضمنة، يمكنك إنشاء مجموعات مخصصة لتناسب احتياجاتك. تظهر المنتجات أولاً للمجموعات، وبعد ذلك يمكن للمطورين في هذه المجموعات عرض المنتجات المرتبطة بالمجموعات والاشتراك فيها.

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

إشعار

يتم دعم عناصر التحكم في الرؤية والوصول فقط في مدخل المطور المدار. وهي غير مدعومة في المدخل المستضاف ذاتيا.

  • عند إضافة صفحة أو تحرير إعدادات صفحة موجودة، قم بإجراء تحديد ضمن Access للتحكم في المستخدمين أو المجموعات التي يمكنها رؤية الصفحة

    لقطة شاشة لإعدادات التحكم في الوصول إلى الصفحة في مدخل المطور.

    تلميح

    لتحرير إعدادات صفحة موجودة، حدد أيقونة الترس بجوار اسم الصفحة في علامة التبويب صفحات .

  • عند تحديد محتوى الصفحة مثل مقطع صفحة أو قائمة أو زر للتحرير، حدد أيقونة تغيير الوصول للتحكم في المستخدمين أو المجموعات التي يمكنها رؤية العنصر على الصفحة

    لقطة شاشة لزر تغيير الوصول في مدخل المطور.

    • يمكنك تغيير رؤية محتوى الصفحة التالية: المقاطع والقوائم والأزرار وتسجيل الدخول لتخويل OAuth.

    • ترث ملفات الوسائط مثل الصور على صفحة رؤية العناصر التي تحتوي عليها.

عندما يزور مستخدم مدخل المطور مع تطبيق عناصر التحكم في الرؤية والوصول:

  • يخفي مدخل المطور تلقائيا الأزرار أو عناصر التنقل التي تشير إلى صفحات لا يملك المستخدم حق الوصول إليها.

  • تؤدي محاولة مستخدم للوصول إلى صفحة غير مصرح له بالوصول إليها إلى خطأ 404 Not Found.

تلميح

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

سياسة أمان المحتوى

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

لتمكين نهج أمان المحتوى:

  1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.
  2. في القائمة اليسرى، ضمن مدخل المطور، حدد إعدادات المدخل.
  3. في علامة التبويب نهج أمان المحتوى، حدد ممكن.
  4. ضمن المصادر المسموح بها، أضف اسم مضيف واحدا أو أكثر يحدد المواقع الموثوق بها التي يمكن لمدخل المطور تحميل الموارد منها. يمكنك أيضا تحديد حرف بدل للسماح بكافة المجالات الفرعية للمجال. على سبيل المثال، *.contoso.com يسمح بجميع المجالات الفرعية ل contoso.com.
  5. حدد حفظ.

وحدة تحكم اختبار تفاعلية

يوفر مدخل المطور إمكانية "Try it" على الصفحات المرجعية لواجهة برمجة التطبيقات بحيث يمكن لزوار المدخل اختبار واجهات برمجة التطبيقات الخاصة بك مباشرة من خلال وحدة تحكم تفاعلية.

لقطة شاشة لوحدة تحكم الاختبار في مدخل مطور APIM.

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

هام

للسماح لزوار المدخل الخاص بك باختبار واجهات برمجة التطبيقات من خلال وحدة التحكم التفاعلية المضمنة، قم بتمكين نهج CORS (مشاركة الموارد عبر المنشأ) على واجهات برمجة التطبيقات الخاصة بك. للحصول على التفاصيل، راجع تمكين CORS لوحدة التحكم التفاعلية في مدخل مطور APIM.

إدارة تسجيل المستخدم وتسجيل الدخول

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

يدعم المدخل العديد من الخيارات لتسجيل المستخدم وتسجيل الدخول:

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

  • اعتمادا على السيناريوهات الخاصة بك، قم بتقييد الوصول إلى المدخل عن طريق مطالبة المستخدمين بالتسجيل أو تسجيل الدخول باستخدام معرف Microsoft Entra أو حساب Azure AD B2C .

  • إذا كنت تدير بالفعل تسجيل دخول المطور وتسجيل الدخول من خلال موقع ويب موجود، ففوض المصادقة بدلا من استخدام المصادقة المضمنة لمدخل المطور.

تعرف على المزيد حول خيارات تأمين اشتراك المستخدم وتسجيل الدخول إلى مدخل المطور.

تقارير للمستخدمين

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

إشعار

تعرض التقارير في مدخل المطور بيانات المستخدم المصادق عليه فقط. يمكن لناشري API والمسؤولين الوصول إلى بيانات الاستخدام لجميع مستخدمي مثيل APIM - على سبيل المثال، عن طريق إعداد ميزات المراقبة مثل Azure Application Insights في المدخل.

حفظ محتوى موقع ويب ونشره

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

حفظ التغييرات

لقطة شاشة لزر

كلما قمت بإجراء تغيير في المدخل، تحتاج إلى حفظه يدويا عن طريق تحديد الزر حفظ في القائمة في الأعلى، أو الضغط على [Ctrl]+[S]. إذا كنت بحاجة إلى ذلك، يمكنك التراجع عن آخر تغييرات تم حفظها. تكون التغييرات المحفوظة مرئية لك فقط ولا تكون مرئية لزوار المدخل حتى تنشرها.

إشعار

يتلقى مدخل المطور المدار تحديثات البرامج ويطبقها تلقائيا. تظل التغييرات التي قمت بحفظها ولكن لم يتم نشرها على مدخل المطور في هذه الحالة أثناء التحديث.

نشر المدخل

لجعل مدخلك وآخر التغييرات التي تمت متاحة للزائرين تحتاج إلى نشره. يمكنك نشر المدخل داخل الواجهة الإدارية للمدخل أو من مدخل Microsoft Azure.

هام

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

النشر من خلال الواجهة الإدارية

  1. تأكد من حفظ التغييرات عن طريق تحديد الزر حفظ .

  2. في القائمة الموجودة في الأعلى، حدد Publish site. قد تستغرق هذه العملية بضع دقائق.

    لقطة شاشة لزر نشر موقع الويب في مدخل المطور.

النشر من مدخل Microsoft Azure

  1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

  2. في القائمة اليسرى، ضمن مدخل Developer، حدد Portal overview.

  3. في نافذة Portal overview، حدد Publish.

    لقطة شاشة لنشر مدخل المطور من مدخل Microsoft Azure

استعادة مراجعة المدخل السابقة

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

إشعار

يتم تطبيق تحديثات برامج مدخل المطور تلقائيا عند استعادة مراجعة. تظل التغييرات المحفوظة ولكن غير المنشورة في الواجهة الإدارية في تلك الحالة عند نشر مراجعة.

لاستعادة مراجعة المدخل السابقة:

  1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.
  2. في القائمة اليسرى، ضمن مدخل Developer، حدد Portal overview.
  3. في علامة التبويب مراجعات ، حدد قائمة السياق (...) للمراجعة التي تريد استعادتها، ثم حدد جعل الحالي والنشر.

إعادة تعيين المدخل

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

إشعار

لا تؤدي إعادة تعيين مدخل المطور إلى حذف الإصدار المنشور من مدخل المطور.

لإعادة تعيين مدخل المطور:

  1. في الواجهة الإدارية، في القائمة الموجودة على يسار المحرر المرئي، حدد الإعدادات.
  2. في علامة التبويب خيارات متقدمة ، حدد نعم، أعد تعيين موقع الويب إلى الحالة الافتراضية.
  3. حدد حفظ.

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

تعرف على المزيد حول مدخل المطور:

استعراض الموارد الأخرى: