Configurare un dominio personalizzato

Questo script di esempio configura un dominio personalizzato nell'endpoint proxy e del portale del servizio Gestione API.

Nota

Questo articolo usa il modulo Azure Az PowerShell, che è il modulo PowerShell consigliato per interagire con Azure. Per iniziare a usare il modulo Az PowerShell, vedere Installare Azure PowerShell. Per informazioni su come eseguire la migrazione al modulo AZ PowerShell, vedere Eseguire la migrazione di Azure PowerShell da AzureRM ad Az.

Usare Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser. È possibile usare Bash o PowerShell con Cloud Shell per usare i servizi di Azure. È possibile usare i comandi Cloud Shell preinstallati per eseguire il codice in questo articolo, senza dover installare alcun elemento nell'ambiente locale.

Per avviare Azure Cloud Shell:

Opzione Esempio/Collegamento
Selezionare Prova nell'angolo superiore destro di un blocco di codice. La selezione di Prova non comporta la copia automatica del codice in Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser. Screenshot that shows how to launch Cloud Shell in a new window.
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo in alto a destra del portale di Azure. Screenshot that shows the Cloud Shell button in the Azure portal

Per eseguire il codice di questo articolo in Azure Cloud Shell:

  1. Avviare Cloud Shell.

  2. Selezionare il pulsante Copia in un blocco di codice per copiare il codice.

  3. Incollare il codice nella sessione di Cloud Shell selezionandoCTRLShiftV++ in Windows e Linux oppure selezionando CmdShiftV++ in macOS.

  4. Premere INVIO per eseguire il codice.

Se si sceglie di installare e usare PowerShell in locale, per questa esercitazione è necessario il modulo Azure PowerShell versione 1.0 o successiva. Eseguire Get-Module -ListAvailable Az per trovare la versione. Se è necessario eseguire l'aggiornamento, vedere Installare e configurare Azure PowerShell. Se si esegue PowerShell in locale, è anche necessario eseguire Connect-AzAccount per creare una connessione con Azure.

Script di esempio

##########################################################
#  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

Pulire le risorse

Quando non servono più, è possibile usare il comando Remove-AzResourceGroup per rimuovere il gruppo di risorse e tutte le risorse correlate.

Remove-AzResourceGroup -Name myResourceGroup

Come Gestione API server proxy risponde con i certificati SSL nella handshake TLS

Quando si configura un dominio personalizzato per l'endpoint gateway, è possibile impostare proprietà aggiuntive che determinano il modo in cui Gestione API risponde con un certificato server, a seconda della richiesta client.

Client che chiamano con l'intestazione SNI (Server Name Indication)

Se si dispone di uno o più domini personalizzati configurati per l'endpoint gateway, Gestione API può rispondere alle richieste HTTPS da:

  • Dominio personalizzato (ad esempio, contoso.com)
  • Dominio predefinito (ad esempio, apim-service-name.azure-api.net).

In base alle informazioni nell'intestazione SNI, Gestione API risponde con il certificato server appropriato.

Client che chiamano senza intestazione SNI

Se si usa un client che non invia l'intestazione SNI, Gestione API crea risposte in base alla logica seguente:

  • Se il servizio dispone di un solo dominio personalizzato configurato per gateway, il certificato predefinito è il certificato rilasciato al dominio personalizzato del gateway.

  • Se il servizio ha configurato più domini personalizzati per gateway (supportato nel livello Developer e Premium), è possibile definire il certificato predefinito impostando la proprietà defaultSslBinding su true ("defaultSslBinding":"true"). Nel portale selezionare la casella di controllo Associazione SSL predefinita .

    Se non si imposta la proprietà, il certificato predefinito è il certificato rilasciato al dominio gateway predefinito ospitato in *.azure-api.net.

Supporto per una richiesta PUT/POST con payload di grandi dimensioni

Gestione API server proxy supporta le richieste con payload di grandi dimensioni (>40 KB) quando si usano certificati lato client in HTTPS. Per impedire il blocco della richiesta del server, è possibile impostare la proprietà negotiateClientCertificate su true ("negotiateClientCertificate": "true") nel nome host del gateway. Nel portale selezionare la casella di controllo Negozia certificato client .

Se la proprietà è impostata su true, il certificato client viene richiesto al momento della connessione SSL/TLS, prima di qualsiasi scambio di richieste HTTP. Poiché l'impostazione si applica a livello di nome host gateway , tutte le richieste di connessione richiedono il certificato client. È possibile risolvere questa limitazione e configurare fino a 20 domini personalizzati per gateway (supportati solo nel livello Premium).

Passaggi successivi

Per altre informazioni sul modulo Azure PowerShell, vedere la documentazione di Azure PowerShell.

Per altri esempi di Azure PowerShell per Gestione API di Azure, vedere gli esempi di PowerShell.