تكوين اسم مجال مخصص لمثيل Azure APIM الخاص بك

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

عند إنشاء مثيل خدمة Azure API Management (APIM) في سحابة Azure، يقوم Azure بتعيينه azure-api.net مجالاً فرعياً (على سبيل المثال، apim-service-name.azure-api.net). يمكنك أيضًا عرض نقاط النهاية الخاصة بـAPIM باستخدام اسم المجال المخصص الخاص بك، مثل contoso.com. توضح لك هذه المقالة كيفية تعيين اسم DNS مخصص موجود لنقاط النهاية المكشوفة بواسطة مثيلAPI Management (APIM).

هام

تقبل APIM الطلبات التي تتطابق مع قيم عنوان المضيف فقط:

• اسم المجال الافتراضي الخاص بالبوابة
• أي من أسماء المجالات المخصصة المكونة للبوابة

إشعار

حاليا، أسماء المجالات المخصصة غير مدعومة في بوابة مساحة العمل.

هام

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

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

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

• مثيل API Management. لمزيد من المعلومات، راجع إنشاء مثيل Azure API Management.

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

• اختيارياً، شهادة صالحة بمفتاح عام وخاص (.PFX). يجب أن يتطابق الموضوع أو الاسم البديل للموضوع (SAN) مع اسم المجال (وهذا يمكّن مثيل إدارة واجهة برمجة التطبيقات من كشف عناوين URL بشكل آمن عبر TLS).

  راجع خيارات شهادة المجال.

• سجلات DNS المستضافة على خادم DNS لتعيين اسم المجال المخصص إلى اسم المجال الافتراضي لمثيل إدارة API الخاص بك. لا يوفر هذا الموضوع إرشادات بشأن كيفية استضافة سجلات DNS.

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

نقاط النهاية للمجالات المخصصة

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

نقطة النهاية	الإعداد الافتراضي
بوابة	رقم الافتراضي هو: <apim-service-name>.azure-api.net. البوابة هي نقطة النهاية الوحيدة المتوفرة للتكوين في طبقة الاستهلاك. يظل تكوين نقطة نهاية البوابة الافتراضية متاحاً بعد إضافة مجال بوابة مخصص.
مدخل المطور (جميع المستويات باستثناء الاستهلاك)	رقم الافتراضي هو: <apim-service-name>.developer.azure-api.net
الإدارة (المستويات الكلاسيكية فقط)	رقم الافتراضي هو: <apim-service-name>.management.azure-api.net
واجهة برمجة تطبيقات تكوين البوابة المستضافة ذاتيا (v2)	رقم الافتراضي هو: <apim-service-name>.configuration.azure-api.net
SCM (المستويات الكلاسيكية فقط)	رقم الافتراضي هو: <apim-service-name>.scm.azure-api.net

الاعتبارات

• يمكنك تحديث أي من نقاط النهاية المدعومة في طبقة الخدمة الخاصة بك. عادة ما يقوم العملاء بتحديث البوابة (يتم استخدام عنوان URL هذا لاستدعاء واجهات برمجة التطبيقات المكشوفة من خلال APIM) ومدخل المطور (عنوان URL لمدخل المطور).
• تظل نقطة نهاية البوابة الافتراضية متوفرة بعد تكوين اسم مجال بوابة مخصص ولا يمكن حذفها. بالنسبة لنقاط نهاية API Management الأخرى (مثل مدخل المطور) التي تقوم بتكوينها باستخدام اسم مجال مخصص، لم تعد نقطة النهاية الافتراضية متوفرة.
• يمكن لمالكي مثيل API Management فقط استخدام نقاط نهاية ManagementوSCM داخليا. يتم تعيين اسم مجال مخصص لنقاط النهاية هذه بشكل أقل بشكل متكرر.
• تدعم مستويات Premium و Developer تعيين أسماء مضيفين متعددة لنقطة نهاية البوابة .
• أسماء مجالات حرف البدل، مثل *.contoso.comمدعومة في كافة طبقاتها باستثناء طبقة الاستهلاك. قد تكون لشهادة مجال فرعي محدد (على سبيل المثال، api.contoso.com) الأسبقية على شهادة حرف بدل (*.contoso.com) لطلبات api.contoso.com.
• عند تكوين مجال مخصص لمدخل المطور، يمكنك تمكين CORS لاسم المجال الجديد. هذا مطلوب لزوار مدخل المطور لاستخدام وحدة التحكم التفاعلية في الصفحات المرجعية لواجهة برمجة التطبيقات.

خيارات شهادة المجال

تدعم إدارة API شهادات بروتوكول أمان طبقة النقل (TLS) المخصصة أو الشهادات المستوردة من Azure Key Vault. يمكنك أيضاً تمكين شهادة مجانية مُدارة.

تحذير

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

تقليد

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

• تم تصديره كملف PFX، مشفر باستخدام DES الثلاثي، ومحمي بكلمة مرور اختيارياً.
• تحتوي على مفتاح خاص بطول 2048 بت على الأقل
• تحتوي على جميع الشهادات المتوسطة والشهادة الجذرية في سلسلة الشهادات.

Key Vault

نوصي باستخدام Azure Key Vault لإدارة شهاداتك وتعيينها إلى autorenew.

إذا كنت تستخدم Azure Key Vault لإدارة شهادة TLS لمجال مخصص، فتأكد من إدراج الشهادة في Key Vault كشهادة، وليس سرا.

تنبيه

عند استخدام شهادة key vault في إدارة API، احرص على عدم حذف الشهادة أو key vault أو الهوية المُدارة المستخدمة للوصول إلى key vault.

لإحضار شهادة TLS/SSL، يجب أن يكون لدى APIM القائمة والحصول على أذونات الأسرار على «Azure Key Vault» الذي يحتوي على الشهادة.

• عند استخدام مدخل Microsoft Azure لاستيراد الشهادة، يتم إكمال جميع خطوات التكوين الضرورية تلقائياً.

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

  1. في صفحة الهويات المدارة لمثيل API Management، قم بتمكين هوية مدارة معينة من قبل النظام أو معينة من قبل المستخدم. لاحظ المعرف الأساسي في تلك الصفحة.
  2. تعيين أذونات للهوية المدارة للوصول إلى مخزن المفاتيح. استخدم الخطوات في القسم التالي.

  تكوين الوصول إلى key vault

  1. في المدخل، انتقل إلى خزنة المفاتيح الخاصة بك.
  2. في القائمة اليسرى، حدد Access configuration. لاحظ نموذج الإذن الذي تم تكوينه.
  3. اعتمادا على نموذج الإذن، قم بتكوين إما نهج الوصول إلى مخزن المفاتيح أو الوصول إلى التحكم في الوصول استنادا إلى الدور في Azure للهوية المدارة لإدارة واجهة برمجة التطبيقات.

  لإضافة نهج الوصول إلى مخزن المفاتيح:

  1. في القائمة اليسرى، حدد Access policies.
  2. في صفحة Access policies ، حدد + Create.
  3. في علامة التبويب أذونات ، ضمن أذونات سرية، حدد الحصول على وقائمة، ثم حدد التالي.
  4. في علامة التبويب Principal ، حدد Principal، وابحث عن اسم المورد للهوية المدارة، ثم حدد Next. إذا كنت تستخدم هوية معينة من قِبل النظام، فإن الأساسي هو اسم مثيل إدارة API الخاص بك.
  5. حدد التالي مرة أخرى. في علامة التبويب Review + create ، حدد Create.

  لتكوين الوصول إلى Azure RBAC:

  1. في القائمة اليمنى، حدد Access control (IAM).
  2. في صفحة Access control (IAM)، حدد Add role assignment.
  3. في علامة التبويب Role ، حدد Key Vault Certificate User.
  4. في علامة التبويب Members ، حدد Managed identity>+ Select members.
  5. في نافذة تحديد الهويات المدارة ، حدد الهوية المدارة المعينة من قبل النظام أو الهوية المدارة المعينة من قبل المستخدم المقترنة بمثيل إدارة واجهة برمجة التطبيقات، ثم انقر فوق تحديد.
  6. حدد Review + assign.

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

لمزيد من المعلومات، راجع استخدام الهويات المدارة في Azure API Management.

تقدم إدارة واجهة برمجة التطبيقات شهادة بروتوكول أمان طبقة النقل (TLS) مجانية مُدارة لنطاقك، إذا كنت لا ترغب في شراء وإدارة شهادتك الخاصة. يتم تجديد الشهادة تلقائياً.

إشعار

شهادة TLS المدارة المجانية قيد المعاينة. حاليا، لا يتوفر في مستويات الخدمة v2.

القيود

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

قم بتعيين اسم المجال المخصص - المدخل

اختر الخطوات وفقا لشهادة المجال التي تريد استخدامها.

تقليد

1. انتقل إلى مثيل APIM في مدخل Microsoft Azure.
2. في جزء التنقل الأيمن، حدد Custom domains.
3. حدد +إضافة، أو حدد نقطة نهاية موجودة تريد تحديثها.
4. في النافذة على اليمين، حدد نوع نقطة النهاية للمجال المخصص.
5. في الحقل اسم المضيف ، حدد الاسم الذي تريد استخدامه. على سبيل المثال، api.contoso.com
6. ضمن الشهادة، حدد مخصص
7. حدد ملف الشهادة لتحديد شهادة وتحميلها.
8. تحميل صالح . ملف PFX وتوفير كلمة المرور الخاصة به، إذا كانت الشهادة محمية بكلمة مرور.
9. عند تكوين نقطة نهاية البوابة، حدد خيارات أخرى أو قم بإلغاء تحديدها حسب الضرورة، بما في ذلك التفاوض على شهادة العميل أو ربط SSL الافتراضي.
10. حدد إضافة، أو حدد تحديث لنقطة نهاية موجودة.
11. حدد حفظ.

Key Vault

1. انتقل إلى مثيل APIM في مدخل Microsoft Azure.
2. في جزء التنقل الأيمن، حدد Custom domains.
3. حدد +إضافة، أو حدد نقطة نهاية موجودة تريد تحديثها.
4. في النافذة على اليمين، حدد نوع نقطة النهاية للمجال المخصص.
5. في الحقل اسم المضيف ، حدد الاسم الذي تريد استخدامه. على سبيل المثال، api.contoso.com
6. ضمن الشهادة، حدد Key Vault ثم حدد.
   1. حدد الاشتراك من القائمة المنسدلة.
   2. حدد Key vault من القائمة المنسدلة.
   3. بمجرد تحميل الشهادات، حدد الشهادة من القائمة المنسدلة. انقر فوق تحديد.
   4. في Client identity، حدد هوية معينة من قبل النظام أو هوية مدارة معينة من قبل المستخدم تم تمكينها في المثيل للوصول إلى مخزن المفاتيح.
7. عند تكوين نقطة نهاية البوابة، حدد خيارات أخرى أو قم بإلغاء تحديدها حسب الضرورة، بما في ذلك التفاوض على شهادة العميل أو ربط SSL الافتراضي.
8. حدد إضافة، أو حدد تحديث لنقطة نهاية موجودة.
9. حدد حفظ.

1. انتقل إلى مثيل APIM في مدخل Microsoft Azure.
2. في جزء التنقل الأيمن، حدد Custom domains.
3. حدد +إضافة، أو حدد نقطة نهاية موجودة تريد تحديثها.
4. في النافذة على اليمين، حدد نوع نقطة النهاية للمجال المخصص.
5. في الحقل اسم المضيف ، حدد الاسم الذي تريد استخدامه. على سبيل المثال، api.contoso.com
6. ضمن Certificate، حدد Managed لتمكين شهادة مجانية تديرها APIM. الشهادة المُدارة متاحة في المعاينة لنقطة نهاية البوابة فقط.
7. انسخ القيم التالية واستخدمها لتكوين DNS:
   • سجل TXT
   • سجل CNAME
8. عند تكوين نقطة نهاية البوابة، حدد خيارات أخرى أو قم بإلغاء تحديدها حسب الضرورة، بما في ذلك التفاوض على شهادة العميل أو ربط SSL الافتراضي.
9. حدد إضافة، أو حدد تحديث لنقطة نهاية موجودة.
10. حدد حفظ.

تكوين DNS

• قم بتكوين سجل CNAME لمجالك الخاص.
• عند استخدام شهادة مُدارة مجانية من API Management، قم أيضاً بتكوين سجل TXT لتأكيد ملكيتك للمجال.

إشعار

يتم إصدار الشهادة المجانية من DigiCert. بالنسبة لبعض المجالات، يجب السماح صراحة ب DigiCert كمصدر شهادة عن طريق إنشاء سجل مجال CAA بالقيمة: 0 issue digicert.com.

سجل CNAME

قم بتكوين سجل CNAME الذي يشير من اسم المجال المخصص الخاص بك (على سبيل المثال، api.contoso.com) إلى اسم مضيف خدمة إدارة واجهة برمجة التطبيقات (على سبيل المثال، <apim-service-name>.azure-api.net). يكون سجل CNAME أكثر استقراراً من سجل A في حالة تغيير عنوان IP. لمزيد من المعلومات، راجع عناوين IP لإدارة واجهة برمجة تطبيقات Azureوالأسئلة المتداولة حول إدارة واجهة برمجة التطبيقات.

إشعار

يسمح لك بعض مسجلي المجال فقط بتعيين المجالات الفرعية عند استخدام سجل CNAME، مثل www.contoso.com، وليس أسماء الجذر، مثل contoso.com. لمزيد من المعلومات حول سجلات CNAME، راجع الوثائق المقدمة من المسجل أو أسماء مجالات IETF - التنفيذ والمواصفات.

تنبيه

عند استخدام الشهادة المجانية المدارة وتكوين سجل CNAME مع موفر DNS الخاص بك، تأكد من حله إلى اسم مضيف خدمة APIM الافتراضي (<apim-service-name>.azure-api.net). حاليا، لا تقوم APIM تلقائيا بتجديد الشهادة إذا لم يتم حل سجل CNAME إلى اسم مضيف APIM الافتراضي. على سبيل المثال، إذا كنت تستخدم الشهادة المجانية المدارة وكنت تستخدم Cloudflare كموفر DNS، فتأكد من عدم تمكين وكيل DNS في سجل CNAME.

سجل TXT

عند تمكين الشهادة المجانية المُدارة لإدارة API، قم أيضاً بتكوين سجل TXT في منطقة DNS الخاصة بك لإثبات ملكيتك لاسم المجال.

• اسم السجل هو اسم مجالك المخصص مسبوقاً بـ apimuid. مثال:apimuid.api.contoso.com.
• القيمة عبارة عن معرّف ملكية النطاق يتم توفيره بواسطة مثيل إدارة واجهة برمجة التطبيقات.

عند استخدام المدخل لتكوين الشهادة المجانية المُدارة لمجالك المخصص، يتم عرض اسم وقيمة سجل TXT الضروري تلقائياً.

يمكنك أيضا الحصول على معرف ملكية المجال عن طريق استدعاء Get Domain Ownership Identifier REST API.

كيفية استجابة خادم وكيل APIM مع شهادات SSL في تأكيد اتصال TLS

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

العملاء الذين يتصلون بعنوان إشارة اسم الخادم (SNI)

إذا كان لديك مجال مخصص واحد أو أكثر تم تكوينه لنقطة نهاية البوابة، يمكن لإدارة واجهة برمجة التطبيقات الاستجابة لطلبات HTTPS من أيٍّ من:

• المجال المخصص (على سبيل المثال، contoso.com)
• المجال الافتراضي (على سبيل المثال، apim-service-name.azure-api.net).

استناداً إلى المعلومات الموجودة في عنوان SNI، تستجيب إدارة API بشهادة الخادم المناسبة.

العملاء الذين يتصلون بدون عنوان SNI

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

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

• إذا قامت الخدمة بتكوين مجالات مخصصة متعددة للبوابة (مدعومة في مستوى المطوروالمتميزة )، يمكنك تعيين الشهادة الافتراضية عن طريق تعيين الخاصية defaultSslBinding إلى true ("defaultSslBinding":"true"). في المدخل، حدد خانة الاختيار Default SSL binding .

  إذا لم تقم بتعيين الخاصية، فإن الشهادة الافتراضية هي الشهادة التي تم إصدارها لمجال البوابة الافتراضية المستضاف على *.azure-api.net.

دعم طلب PUT/POST مع حمولة كبيرة

يدعم الخادم الوكيل لإدارة واجهة برمجة التطبيقات الطلبات ذات الحمولات الكبيرة (>40 كيلوبايت) عند استخدام الشهادات من جانب العميل في HTTPS. لمنع تجميد طلب الخادم، يمكنك تعيين الخاصية negotiateClientCertificate إلى true ("negotiateClientCertificate": "true") على اسم مضيف البوابة. في المدخل، حدد خانة الاختيار Negotiate client certificate .

في حالة تعيين الخاصية إلى true، تُطلب شهادة العميل في وقت اتصال SSL/TLS، قبل أي تبادل لطلب HTTP. نظرا لأن الإعداد ينطبق على مستوى اسم مضيف البوابة ، فإن جميع طلبات الاتصال تطلب شهادة العميل. يمكنك التغلب على هذا القيد وتكوين ما يصل إلى 20 مجالا مخصصا للبوابة (مدعومة فقط في المستوى المتميز ).

تقييد اسم المجال المخصص في المستوى القياسي v2

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

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

استكشاف الأخطاء وإصلاحها: فشل تدوير شهادة اسم المضيف من Azure Key Vault

بسبب تغيير التكوين أو مشكلة في الاتصال، قد يتعذر على مثيل APIM إحضار شهادة اسم مضيف من Azure Key Vault بعد تحديث الشهادة أو تدويرها هناك. عند حدوث ذلك، يستمر مثيل API Management في استخدام شهادة مخزنة مؤقتا حتى يتلقى شهادة محدثة. إذا انتهت صلاحية الشهادة المخزنة مؤقتا، حظر حركة مرور وقت التشغيل إلى البوابة. يمكن لأي خدمة مصدر مثل Application Gateway التي تستخدم تكوين شهادة اسم المضيف أيضا حظر حركة مرور وقت التشغيل إلى البوابة عند استخدام شهادة مخزنة مؤقتا منتهية الصلاحية.

للتخفيف من هذه المشكلة، تأكد من وجود مخزن المفاتيح، ويتم تخزين الشهادة في مخزن المفاتيح. إذا تم نشر مثيل API Management في شبكة ظاهرية، فتأكد من الاتصال الصادر بعلامة خدمة AzureKeyVault. تحقق مما إذا كانت الهوية المدارة المستخدمة للوصول إلى خزنة المفاتيح موجودة. تأكد من أذونات الهوية المدارة للوصول إلى مخزن المفاتيح. راجع إعداد اسم مجال مخصص - Key Vault، في وقت سابق من هذه المقالة، للحصول على خطوات تكوين مفصلة. بعد استعادة التكوين، سيتم تحديث شهادة اسم المضيف في APIM في غضون 4 ساعات.

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

ترقية الخدمة وتوسيع نطاقها