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

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

هام

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

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

ملاحظة

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

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

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

لإعداد بيئة تطوير محلية، يجب أن يكون لديك:

مثيل خدمة APIM. إذا لم يكن لديك واحد، فشاهد التشغيل السريع - إنشاء مثيل إدارة واجهة برمجة تطبيقات Azure.

إذا قمت بإنشاء المثيل الخاص بك في طبقة خدمة v2، فبادر أولا بتمكين مدخل المطور.
1. في قائمة الشريط الجانبي، ضمن مدخل المطورين، حدد إعدادات البوابة الإلكترونية.
2. في نافذة إعدادات المدخل، حدد ممكن. حدد حفظ. قد يستغرق الأمر بضع دقائق لتمكين مدخل المطور.
حساب تخزين Azure blob، والذي ستستخدمه لتمكين ميزة مواقع الويب الثابتة. راجع إنشاء حساب تخزين.
Git على جهازك. ثبته باتباع هذا البرنامج التعليمي Git.
Node.js (إصدار الدعم طويل الأجل (LTS) أو v10.15.0 إصدار أحدث) و npm على جهازك. راجع تنزيل وتثبيت Node.js وnpm.
Azure CLI اتبع خطوات تثبيت Azure CLI.
أذونات لإنشاء تسجيل تطبيق Microsoft Entra.

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

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

استنساخ api-management-developer-portal repo من GitHub:

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

انتقل إلى نسختك المحلية من المستودع:
```
cd api-management-developer-portal
```
تحقق من أحدث إصدار من المدخل.

قبل تشغيل التعليمات البرمجية التالية، تحقق من علامة الإصدار الحالية في قسم Releases في المستودع واستبدل <current-release-tag> القيمة بأحدث علامة إصدار.
```
git checkout <current-release-tag>
```
تثبيت أي حزم npm متوفرة:
```
npm install
```

تلميح

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

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

ملف config.design.json

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

في subscriptionId، resourceGroupNameو serviceName، أدخل قيما للاشتراك ومجموعة الموارد واسم الخدمة لمثيل إدارة واجهة برمجة التطبيقات. أنا

الإعدادات الاختيارية في config.design.json

اختياريا، قم بتكوين الإعدادات التالية في الملف config.design.json :

إذا كنت ترغب في تمكين CAPTCHA في مدخل المطور، فقم بتعيين "useHipCaptcha": true. تأكد من تكوين إعدادات CORS للواجهة الخلفية لمدخل المطور.
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
في integration، ضمن googleFonts، قم بتعيين apiKey اختياريا إلى مفتاح واجهة برمجة تطبيقات Google الذي يسمح بالوصول إلى واجهة برمجة تطبيقات مطور خطوط الويب. هذا المفتاح مطلوب فقط إذا كنت تريد إضافة خطوط Google في قسم الأنماط في محرر مدخل المطور.
```
{
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}
```
إذا لم يكن لديك مفتاح بالفعل، يمكنك تكوين مفتاح باستخدام وحدة تحكم 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",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

انسخ قيم ، resourceGroupNameووالصقها subscriptionIdserviceName من ملف التكوين السابق.

ملف config.runtime.json

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

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

استبدل < service name > باسم مثيل إدارة واجهة برمجة التطبيقات المستخدم في ملفات التكوين السابقة.

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

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

في مدخل Microsoft Azure، انتقل إلى حساب التخزين الخاص بك في مدخل Microsoft Azure.
في قائمة الشريط الجانبي، حددموقع ويب ثابتلإدارة> البيانات.
في صفحة موقع ويب ثابت ، حدد ممكن.
في حقل اسم مستند الفهرس ، أدخل index.html.
في حقل مسار مستند الخطأ ، أدخل 404/index.html.
حدد حفظ.

لاحظ عنوان URL لنقطة النهاية الأساسية . ستقوم بتكوينه لاحقا للوصول إلى البوابة الإلكترونية المستضافة ذاتيا.

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

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

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

في علامة التبويب خدمة Blob ، قم بتكوين القواعد التالية:

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

حدد حفظ.

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

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

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

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

انتقل إلى مثيل إدارة واجهة برمجة التطبيقات في مدخل Microsoft Azure.
في قائمة الشريط الجانبي، حددإعدادات مدخل >المطورين.
في علامة التبويب تكوين المدخل المستضاف ذاتيا ، أضف قيمة مجال أصل واحدة أو أكثر. على سبيل المثال:
- المجال الذي تتم فيه استضافة المدخل المستضاف ذاتيا، مثل https://contoso.developer.azure-api.net
- localhost للتنمية المحلية (إن أمكن)، مثل http://localhost:8080 أو https://localhost:8080
حدد حفظ.

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

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

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

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

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

تخصيص المدخل الخاص بك
محتوى الكاتب
تنظيم بنية الموقع
نمط مظهره

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

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

شغّل npm run publish. تتم مطالبتك بالمصادقة عبر متصفحك. حدد بيانات اعتماد Microsoft للمتابعة.
بعد مرور بعض الوقت، يتم نشر المحتوى في المجلد dist/website .

الخطوة 6: تحميل ملفات ثابتة إلى كائن ثنائي كبير الحجم

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

افتح موجه أوامر Windows أو PowerShell أو shell أوامر أخرى.
قم بتشغيل الأمر التالي az storage blog upload-batch . استبدل <connection-string> بسلسلة اتصال لحساب التخزين الخاص بك. يمكنك الحصول عليه من قسم مفاتيح الوصول إلى الأمان + الشبكات> في حساب التخزين الخاص بك.
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"
```

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

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

استضافة محرر الموقع

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

لهذا ، تحتاج إلى تطبيق Microsoft Entra ID في المستأجر الخاص بك:

قم بتسجيل تطبيق في مستأجر معرف Microsoft Entra الخاص بك. لاحظ معرف التطبيق (العميل)ومعرف الدليل (المستأجر). يمكنك تكوينها في خطوة لاحقة.
قم بتكوين عنوان URI لإعادة توجيه الويب (عنوان URL للرد) في هذا التطبيق للإشارة إلى نقطة نهاية تطبيق الويب حيث يتم استضافة المصمم. عادة ما يكون هذا هو موقع موقع الويب المستند إلى تخزين الكائن الثنائي كبير الحجم. مثال: https://<your-storage-account-name>z13.web.core.windows.net/.
إذا كنت ترغب في نشر المدخل في مسارات (GitHub Actions)، فقم أيضا بإنشاء سر عميل لهذا التطبيق. لاحظ القيمة السرية التي تم إنشاؤها وقم بتخزينها في مكان آمن.

بعد ذلك، اتبع هذه الخطوات لاستضافة محرر موقع الويب:

إضافة clientId حقول إلى tenantIdconfig.design.json الملف.

{
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

قم بتشغيل npm run build-designer الأمر لإنشاء مصمم.

انتقل إلى المجلد الذي تم إنشاؤه /dist/designer ، والذي يحتوي على ملف config.json يحتوي على المحتوى التالي:

{
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

قم بتأكيد تكوين subscriptionId، resourceGroupName و serviceName، اللازمة للاتصال بخدمة إدارة واجهة برمجة التطبيقات باستخدام واجهات برمجة تطبيقات Azure Resource Manager.

نشر المدخل في المسارات (GitHub Actions)

يمكنك نشر المدخل المستضاف ذاتيا في مسار مثل GitHub Actions.

يحتاج المسار أيضا إلى بيانات اعتماد تطبيق معرف Entra لتنفيذ النشر باستخدام خطوط الأنابيب. يمكنك استخدام نفس تطبيق معرف Entra الموضح في الخطوات السابقة. يجب الاحتفاظ ب tenantId، clientId، وخاصة clientSecret في وحدة تخزين المفاتيح المعنية. راجع استخدام الأسرار في GitHub Actions لمزيد من التفاصيل.

مثال على مسار إجراءات GitHub YAML:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

تغيير قوالب إعلام إدارة واجهة برمجة التطبيقات

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

على وجه الخصوص، قم بتنفيذ التغييرات التالية على القوالب الافتراضية:

ملاحظة

تفترض القيم الموجودة في الأقسام المحدثة التالية أنك تستضيف المدخل على 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.v3 مجلد API Management developer portal GitHub repo.

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

تلميح

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

تعرف على النهج البديلة للاستضافة الذاتية

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-10-30

مشاركة عبر

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

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

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

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

ملف config.design.json

الإعدادات الاختيارية في config.design.json

ملف config.publish.json

ملف config.runtime.json

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

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

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

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

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

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

الخطوة 6: تحميل ملفات ثابتة إلى كائن ثنائي كبير الحجم

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

استضافة محرر الموقع

نشر المدخل في المسارات (GitHub Actions)

تغيير قوالب إعلام إدارة واجهة برمجة التطبيقات

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

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

دعوة المستخدم

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

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

كافة القوالب

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

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

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

الملاحظات

الموارد الإضافية