مشاركة عبر

استضافة ذاتية لبوابة مطور APIM

  • مقالة

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

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

هام

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

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

إشعار

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

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

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

لإنشاء بيئة تنمية محلية، يجب أن يكون لديك:

الخطوة 1: يُعد البيئة المحلية

لإعداد بيئتك المحلية، سيتعين عليك استنساخ المستودع، والتبديل إلى أحدث إصدار من بوابة المطور، وتثبيت حزم npm.

  1. استنساخ بوابة مطور إدارة واجهة برمجة التطبيقات من GitHub:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. انتقل إلى النسخة المحلية من مستودع:

    cd api-management-developer-portal

  3. تحقق من الإصدار الأحدث من البوابة.

    قبل تشغيل التعليمة البرمجية التالية، تحقق من علامة الإصدار الحالي في قسم الإصدارات في المستودع واستبدل قيمة <current-release-tag> بأحدث علامة إصدار.

    git checkout <current-release-tag>

  4. تثبيت أي حزم npm متاح:

    npm install

تلميح

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

الخطوة 2: تكوين ملفات JSON وموقع الويب الثابت وإعدادات CORS

يتطلب مدخل المطور APIM REST API لإدارة المحتوى.

ملف config.design.json

قم بالانتقال إلى src "المجلد" وافتح config.design.json "الملف".

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

التكوين الخاص بالملف:

  1. في managementApiUrl القيمة، استبدل <service-name> باسم مثيل APIM الخاص بك. إذا قمت بتكوين المجال المخصص، فاستخدمه بدلاً من ذلك (على سبيل https://management.contoso.com المثال).

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. إنشاء رمز SAS يدويا لتمكين الوصول المباشر لواجهة برمجة تطبيقات REST إلى مثيل APIM الخاص بك.

  3. نسخ رمز الوصول المميز الذي تم إنشاؤه ولصقه managementApiAccessToken كقيمة.

  4. في backendUrl القيمة، استبدل <service-name> باسم مثيل APIM الخاص بك. إذا قمت بتكوين المجال المخصص، فاستخدمه بدلاً من ذلك (على سبيل https://portal.contoso.com المثال).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

  5. إذا كنت ترغب في تمكين CAPTCHA في مدخل المطور، فعيّن "useHipCaptcha": true. تأكد من تكوين إعدادات CORS للواجهة الخلفية لمدخل المطور.

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

    إذا لم يكن لديك مفتاح بالفعل، يمكنك تكوين مفتاح باستخدام وحدة تحكم Google Cloud. اتبع الخطوات التالية:

    1. افتح وحدة تحكم Google Cloud.
    2. تحقق مما إذا كان قد تم تمكين واجهة برمجة تطبيقات مطور خطوط ويب. إذا لم يكن كذلك، فمكنه.
    3. حدد Create credentials>API key.
    4. في مربع الحوار المفتوح، انسخ المفتاح الذي تم إنشاؤه والصقه كقيمة apiKey في config.design.json الملف.
    5. حدد تحرير مفتاح واجهة برمجة التطبيقات لفتح محرر المفتاح.
    6. في المحرر، ضمن قيود واجهة برمجة التطبيقات، حدد تقييد المفتاح. في القائمة المنسدلة، حدد Web Fonts Developer API.
    7. حدد حفظ.

ملف config.publish.json

قم بالانتقال إلى src "المجلد" وافتح config.publish.json "الملف".

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

التكوين الخاص بالملف:

  1. انسخ والصق القيم managementApiUrl و managementApiAccessToken من ملف التكوين السابق.

  2. إذا كنت ترغب في تمكين CAPTCHA في مدخل المطور، فعيّن "useHipCaptcha": true. تأكد من تكوين إعدادات CORS للواجهة الخلفية لمدخل المطور.

ملف config.runtime.js

قم بالانتقال إلى src "المجلد" وافتح config.runtime.json "الملف".

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

التكوين الخاص بالملف:

  1. نسخ ولصق managementApiUrlالقيمة من ملف التكوين السابق.

  2. في backendUrl القيمة، استبدل <service-name> باسم مثيل APIM الخاص بك. إذا قمت بتكوين مجال مخصص، فاستخدمه بدلاً من ذلك (على سبيل المثال https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

تكوين موقع الويب الثابت

قم بتكوين ميزة موقع الويب الثابت في حساب التخزين الخاص بك عن طريق توفير المسارات إلى الفهرس وصفحات الخطأ:

  1. انتقل إلى حساب التخزين الخاص بك في مدخل Microsoft Azure وحدد موقع ويب ثابت من القائمة على اليسار.

  2. في الصفحة موقع ويب ثابت، حدد مُمكّن.

  3. في حقل اسم مستند الفهرس، أدخل index.html.

  4. في حقل مسار مستند خطأ، أدخل 404/index.html.

  5. حدد حفظ.

تكوين إعدادات CORS لحساب التخزين

تكوين إعدادات مشاركة الموارد عبر المنشأ (CORS) لحساب التخزين:

  1. انتقل إلى حساب التخزين الخاص بك في مدخل Microsoft Azure وحدد موقع الويب الثابت من القائمة على اليسار.

  2. في علامة التبويب خدمة كائن ثنائي كبير الحجم تكوين القواعد التالية:

    ‏‏قاعدة القيمة‬
    الأصول المسموح بها *
    الطرق المسموح بها قم بتحديد كافة أفعال HTTP.
    العناوين الرأسية المسموح بها *
    عناوين رأسية مكشوفة *
    MAX AGE 0

  3. حدد حفظ.

تكوين إعدادات CORS للواجهة الخلفية لمدخل المطور

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

  • التحقق من CAPTCHA
  • تخويل OAuth 2.0 في وحدة تحكم الاختبار
  • تفويض مصادقة المستخدم والاشتراك في المنتج

لإضافة إعدادات CORS:

  1. انتقل إلى مثيل APIM في مدخل Azure، وحددمدخل المطور>إعدادات المدخل من القائمة على اليسار.
  2. في علامة تبويب تكوين المدخل المستضاف ذاتيًا، أضف قيمة مجال أصل واحدة أو أكثر. على سبيل المثال:
    • المجال الذي تتم خلاله استضافة المدخل المستضاف ذاتيًا، مثل https://www.contoso.com
    • localhost للتطوير المحلي (إن أمكن)، مثل http://localhost:8080 أو https://localhost:8080
  3. حدد حفظ.

خطوة 3: تشغيل المدخل

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

شغّل الأمر التالي:

npm start

بعد فترة قصيرة، يفتح المستعرض الافتراضي تلقائيا باستخدام مثيل مدخل المطور المحلي. العنوان الافتراضي هو http://localhost:8080، ولكن يمكن تغيير المدخل إذا كان مشغولًا 8080 بالفعل. تؤدي أي تغييرات في قاعدة التعليمات البرمجية للمشروع إلى إعادة إنشاء نافذة المستعرض وتحديثها.

الخطوة 4: قم بالتحرير من خلال المحرر المرئي

قم باستخدم المحرر المرئي لتنفيذ هذه المهام:

  • تخصيص المدخل الخاص بك
  • المحتوى الخاص بالمؤلف
  • قم بتنظيم هيكل الموقع
  • قم بتجميل مظهره

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

الخطوة 5: انشر محليًا

تنشأ بيانات المدخل في شكل أنواع عناصر قوية. يترجمها الأمر التالي إلى ملفات ثابتة ويضع الإخراج في الدليل ./dist/website:

npm run publish

الخطوة 6: تحميل الملفات الثابتة إلى النقطة

قم باستخدام Azure CLI لتحميل الملفات الثابتة التي تم إنشاؤها محليا إلى النقطة، وتأكد من أن زوارك يمكنهم الوصول إليها:

  1. افتح موجه أوامر النوافذ أو PowerShell أو أي أوامر أخرى.

  2. قم بتشغيل أمر Azure CLI التالي.

    قم بالاستبدال <account-connection-string> بسلسلة الاتصال لحساب تخزين Azure الخاص بك. يمكنك الحصول عليه من قسم مفاتيح الاختصار في حساب التخزين الخاص بك.

    az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>

الخطوة 7: قم بالانتقال إلى موقع الويب الخاص بك

أصبح موقع الويب الخاص بك الآن نشطًا ضمن اسم المضيف المحدد في خصائص تخزين Azure ( نقطة نهاية أساسية في مواقع الويب الثابتة ).

الخطوة 8: قم بتغيير قوالب إخطارAPIM

قم باستبدال عنوان URL لمدخل المطور في قوالب إخطار APIM للإشارة إلى المدخل المستضاف ذاتيا. راجع كيفية تكوين التنبيهات وقوالب البريد الإلكتروني في APIM Azure.

بشكل خاص قم بتنفيذ التغييرات التالية إلى القوالب الافتراضية:

إشعار

تفترض القيم الموجودة في الأقسام المحدثة التالية أنك تستضيف المدخل على https://portal.contoso.com/.

تأكيد تغيير عنوان البريد الإلكتروني

تحديث عنوان URL لمطور المدخل في قالب إخطار تأكيد تغيير عنوان البريد الإلكتروني:

محتوى أصلي

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

تم التحديث

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

تأكيد حساب المطور الجديد

تحديث عنوان ويب URL لمطور المدخل في قالب إخطارتأكيد تغيير عنوان البريد الإلكتروني:

محتوى أصلي

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

تم التحديث

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

‏‏دعوة مستخدم

قم بتحديث عنوان URL لمطور المدخل في قالب إخطار تأكيد تغيير عنوان البريد الإلكتروني:

محتوى أصلي

<a href="$ConfirmUrl">$ConfirmUrl</a>

تم التحديث

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

تم عمل تنشيط اشتراك جديد

قم بتحديث عنوان URL لبوابة المطوِّر في نموذج الإخطار تنشيط اشتراك جديد :

محتوى أصلي

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

تم التحديث

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

محتوى أصلي

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

تم التحديث

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

محتوى أصلي

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

تم التحديث

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

محتوى أصلي

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

تم التحديث

<!--Remove the entire block of HTML code above.-->

قم بتأكيد تغيير كلمة المرور

قم بتحديث عنوان URL لمطور المدخل في قالب إخطار تأكيد تغيير عنوان البريد الإلكتروني:

محتوى أصلي

<a href="$DevPortalUrl">$DevPortalUrl</a>

تم التحديث

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

كافة القوالب

تحديث عنوان ويب URL المدخل المطور في أي قالب يحتوي على ارتباط في تذييل الصفحة:

محتوى أصلي

<a href="$DevPortalUrl">$DevPortalUrl</a>

تم التحديث

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

قم بالانتقال من مدخل المطور المدار إلى المستضاف ذاتيًا

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

عملية المرحلة الانتقالية

يمكنك الانتقال من الإصدار المدار إلى الإصدار ذاتي الاستضافة ضمن نفس مثيل خدمة APIM. تحتفظ العملية بالتعديلات التي أجريتها في الإصدار المُدار من المدخل. قم بالتأكد من إجراء احتياطية لمحتوى المدخل مسبقا. يمكنك العثور على البرنامج النصي للنسخ الاحتياطي في scripts مجلد بوابة مطور APIM GitHub repo .

تكاد تكون عملية التحويل مطابقة لإعداد بوابة عامة ذاتية الاستضافة، كما هو موضح في الخطوات السابقة في هذه المقالة. هناك استثناء واحد في خطوة التكوين. يجب أن يكون حساب التخزين في ملف config.design.json هو نفسه حساب التخزين للإصدار المُدار من المدخل. راجع البرنامج التعليمي: استخدم هوية مخصصة لنظام Linux VM للوصول إلى Azure Storage عبر بيانات اعتماد SAS للحصول على إرشادات حول كيفية استرداد عنوان URL الخاص بـSAS.

تلميح

نوصي باستخدام حساب تخزين منفصل في ملف config.publish.json. يمنحك هذا النهج مزيدًا من التحكم ويبسط إدارة خدمة استضافة المدخل الخاص بك.

الخطوات التالية