إعداد المجال المخصص

  • مقالة
  • قراءة خلال 4 دقائق

يقوم هذا البرنامج النصي النموذجي بإعداد مجال مخصص على الوكيل ونقطة نهاية البوابة الإلكترونية لخدمة إدارة واجهة برمجة التطبيقات.

ملاحظة

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

استخدام Azure Cloud Shell

Azure يستضيف Azure Cloud Shell، بيئة تفاعلية يمكن استخدامها من خلال المستعرض. يمكنك استخدام Bash أو PowerShell مع Cloud Shell للعمل مع خدمات Azure. يمكنك استخدام أوامر Cloud Shell المثبتة مسبقًا لتشغيل التعليمات البرمجية في هذه المقالة دون الحاجة إلى تثبيت أي شيء على البيئة المحلية.

لبدء Azure Cloud Shell:

خيار مثال/ رابط
انقر فوق ⁧⁩جربه⁧⁩ في الزاوية العلوية اليسرى من كتلة التعليمات البرمجية. تحديد ⁧⁩جربه⁧⁩ لا يقوم بنسخ التعليمات البرمجية تلقائيًا إلى Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
انتقل إلى ⁧⁩⁧ https://shell.azure.com⁩⁧⁩، أو حدد زر ⁩تشغيل Cloud Shell لفتح Cloud Shell في المتصفح لديك. Screenshot that shows how to launch Cloud Shell in a new window.
حدد زر ⁧⁩Cloud Shell⁧⁩ في شريط القوائم في أعلى اليمين في ⁧⁩مدخل Azure⁧⁩. Screenshot that shows the Cloud Shell button in the Azure portal

لتشغيل التعليمة البرمجية في هذا المقال في Azure Cloud Shell:

  1. ابدأ تشغيل Cloud Shell.

  2. حدد الزر ⁧⁩نسخ⁧⁩ على كتلة التعليمات البرمجية لنسخ التعليمات البرمجية.

  3. ألصق تعليمة البرمجية في جلسة Cloud Shell بتحديد Ctrl+Shift+Vعلى Windows وLunix، أو بتحديد Cmd+Shift+Vعلى macOS.

  4. اكتب ⁧⁩"Enter"⁧⁩ لتشغيل الأمر.

إذا اخترت تثبيت PowerShell واستخدامه محلياً، فإن هذا البرنامج التعليمي يتطلب إصدار الوحدة النمطية Azure PowerShell 1.0 أو إصدار أحدث. قم بتشغيل Get-Module -ListAvailable Az للعثور على الإصدار. إذا كنت بحاجة إلى الترقية، فراجع تثبيت الوحدة النمطية Azure PowerShell. إذا كنت تقوم بتشغيل PowerShell محلياً، تحتاج أيضاً إلى تشغيل Connect-AzAccount لإنشاء اتصال مع Azure.

عينة برنامج نصي

##########################################################
#  Script to setup custom domain on proxy and portal endpoint
#  of api management service.
###########################################################

$random = (New-Guid).ToString().Substring(0,8)

#Azure specific details
$subscriptionId = "my-azure-subscription-id"

# Api Management service specific details
$apimServiceName = "apim-$random"
$resourceGroupName = "apim-rg-$random"
$location = "Japan East"
$organisation = "Contoso"
$adminEmail = "admin@contoso.com"

# Set the context to the subscription Id where the cluster will be created
Select-AzSubscription -SubscriptionId $subscriptionId

# Create a resource group.
New-AzResourceGroup -Name $resourceGroupName -Location $location

# Create the Api Management service. Since the SKU is not specified, it creates a service with Developer SKU. 
New-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apimServiceName -Location $location -Organization $organisation -AdminEmail $adminEmail

# Certificate related details
$proxyHostname = "proxy.contoso.net"
# Certificate containing Common Name CN="proxy.contoso.net" or CN=*.contoso.net
$proxyCertificatePath = "C:\proxycert.pfx"
$proxyCertificatePassword = "certPassword"

$portalHostname = "portal.contoso.net"
# Certificate containing Common Name CN="portal.contoso.net" or CN=*.contoso.net
$portalCertificatePath = "C:\portalcert.pfx"
$portalCertificatePassword = "certPassword"

# Upload the custom ssl certificate to be applied to Proxy endpoint / Api Gateway endpoint
$proxyCertUploadResult = Import-AzApiManagementHostnameCertificate -Name $apimServiceName -ResourceGroupName $resourceGroupName `
                        -HostnameType "Proxy" -PfxPath $proxyCertificatePath -PfxPassword $proxyCertificatePassword

# Upload the custom ssl certificate to be applied to Portal endpoint
$portalCertUploadResult = Import-AzApiManagementHostnameCertificate -Name $apimServiceName -ResourceGroupName $resourceGroupName `
                        -HostnameType "Portal" -PfxPath $portalCertificatePath -PfxPassword $portalCertificatePassword

# Create the HostnameConfiguration object for Portal endpoint
$PortalHostnameConf = New-AzApiManagementHostnameConfiguration -Hostname $proxyHostname -CertificateThumbprint $proxyCertUploadResult.Thumbprint

# Create the HostnameConfiguration object for Proxy endpoint
$ProxyHostnameConf = New-AzApiManagementHostnameConfiguration -Hostname $portalHostname -CertificateThumbprint $portalCertUploadResult.Thumbprint

# Apply the configuration to API Management
Set-AzApiManagementHostnames -Name $apimServiceName -ResourceGroupName $resourceGroupName `
        -PortalHostnameConfiguration $PortalHostnameConf -ProxyHostnameConfiguration $ProxyHostnameConf

تنظيف الموارد

عندما لم تعد هناك حاجة، يمكنك استخدام الأمر Remove- AzResourceGroup لإزالة مجموعة الموارد وجميع الموارد ذات الصلة.

Remove-AzResourceGroup -Name myResourceGroup

كيف يستجيب الخادم الوكيل لإدارة واجهة برمجة التطبيقات مع شهادات SSL في مصافحة TLS

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لمزيد من المعلومات حول وحدة Azure PowerShell، راجع وثائق Azure PowerShell.

يمكن العثور على عينات Azure PowerShell الإضافية لإدارة Azure API في عينات PowerShell.