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

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

عند إنشاء مثيل خدمة Azure API Management (APIM) في سحابة Azure، يقوم Azure بتعيينه azure-api.net مجالاً فرعياً (على سبيل المثال، apim-service-name.azure-api.net). يمكنك أيضًا عرض نقاط النهاية الخاصة بـAPIM باستخدام اسم المجال المخصص الخاص بك، مثل contoso.com. توضح لك هذه المقالة كيفية تعيين اسم DNS مخصص موجود لنقاط النهاية المكشوفة بواسطة مثيلAPI Management (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 هذا لاستدعاء واجهات برمجة التطبيقات المكشوفة من خلال إدارة واجهة برمجة التطبيقات) وبوابة المطور (عنوان URL لمدخل المطور).
• تظل نقطة نهاية البوابة الافتراضية متوفرة بعد تكوين اسم مجال بوابة مخصص ولا يمكن حذفها. بالنسبة لنقاط نهاية API Management الأخرى (مثل مدخل المطور) التي تقوم بتكوينها باستخدام اسم مجال مخصص، لم تعد نقطة النهاية الافتراضية متوفرة.
• يمكن لمالكي مثيلات APIM فقط استخدام نقاط النهاية للإدارةوSCM داخليًا. يتم تعيين اسم مجال مخصص لنقاط النهاية هذه بشكل أقل بشكل متكرر.
• تدعم مستويات Premium وDeveloper إعداد أسماء مضيف متعددة لنقطة نهاية Gateway.
• أسماء مجالات حرف البدل، مثل *.contoso.comمدعومة في كافة طبقاتها باستثناء طبقة الاستهلاك. قد تكون لشهادة مجال فرعي محدد (على سبيل المثال، api.contoso.com) الأسبقية على شهادة حرف بدل (*.contoso.com) لطلبات api.contoso.com.

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

تدعم إدارة 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. في صفحة Managed identities لمثيل إدارة واجهة برمجة التطبيقات، قم بتمكين الهوية المُدارةمخصصة من قبل النظام أو من قبل المستخدم. لاحظ المعرف الأساسي في تلك الصفحة.
  2. تعيين أذونات للهوية المدارة للوصول إلى مخزن المفاتيح. استخدم الخطوات في القسم التالي.

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

  1. في المدخل، انتقل إلى key vault.

  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. على الجانب الأيسر، حدد التحكم بالوصول (IAM).
     2. في صفحة Access control (IAM)، حدد Add role assignment.
     3. في علامة التبويب Role ، حدد Key Vault Secrets User.
     4. في علامة التبويب Members ، حدد Managed identity>+ Select members.
     5. في صفحة تحديد الهوية المدارة، حدد الهوية المدارة المعينة من قبل النظام أو الهوية المدارة المعينة من قبل المستخدم المقترنة بمثيل إدارة واجهة برمجة التطبيقات، ثم حدد تحديد.
     6. حدد مراجعة + تعيين.

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

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

مُدار

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

إشعار

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

القيود

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

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

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

مخصص

1. انتقل إلى مثيل APIM فيمدخل Microsoft Azure.
2. في شريط التنقل الأيسر، حدد Custom domains.
3. حدد +Add، أو حدد endpoint موجودة تريد تحديثها.
4. في النافذة بالجانب الأيمن، حدد «نوع» نقطة النهاية للمجال المخصص.
5. في الحقل «اسم المضيف»، حدد الاسم الذي تريد استخدامه. على سبيل المثال، api.contoso.com
6. ضمن الشهادة، حدد Custom
7. حدد Certificate file لتحديد شهادة وتحميلها.
8. حمّل ملف PFX صالح وقدّم كلمة المرورالخاصة به، إذا كانت الشهادة محمية بكلمة مرور.
9. عند تكوين نقطة نهاية بوابة، حدد أو ألغ تحديد other options as necessary، بما في ذلك مفاوضة شهادة العميل أو ربط SSL الافتراضي.
10. حدد Add، أو حدد Update لنقطة نهاية موجودة.
11. حدد حفظ.

Key Vault

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

مُدار

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

إشعار

قد تستغرق عملية تعيين الشهادة 15 دقيقة أو أكثر بناءً على حجم النشر. تحتوي طبقة المطور على فترة تعطل، بينما لا توجد فترات تعطل في المستويات الأساسية والعالية.

تكوين 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 API و الأسئلة المتداولة بشأن إدارة واجهة برمجة التطبيقات.

إشعار

يسمح لك بعض مسجلي المجال فقط بتعيين المجالات الفرعية عند استخدام سجل 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 الضروري تلقائياً.

يمكنك أيضاً الحصول على معرف ملكية المجال عن طريق استدعاء الحصول على معرف ملكية المجال واجهة برمجة تطبيقات REST.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Upgrade and scale your service