设置自定义域

此示例脚本在 API 管理服务的代理和门户终结点上设置自定义域。

Note

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介。 有关安装说明,请参阅安装 Azure PowerShell

如果选择在本地安装并使用 PowerShell,则本教程需要 Azure PowerShell 模块 1.0 或更高版本。 运行 Get-Module -ListAvailable Az 即可查找版本。 如果需要升级,请参阅安装 Azure PowerShell 模块。 如果在本地运行 PowerShell,则还需运行 Connect-AzAccount -Environment AzureChinaCloud 来创建与 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 = "China East"
$organisation = "Contoso"
$adminEmail = "admin@contoso.com"

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

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

# Create the Api Management service. Since the SKU is not specified, it creates a service with Developer SKU. 
New-AzureRmApiManagement -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-AzureRmApiManagementHostnameCertificate -Name $apimServiceName -ResourceGroupName $resourceGroupName `
                        -HostnameType "Proxy" -PfxPath $proxyCertificatePath -PfxPassword $proxyCertificatePassword

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

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

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

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

清理资源

如果不再需要资源组和所有相关资源,可以使用 Remove-AzResourceGroup 命令将其删除。

Remove-AzResourceGroup -Name myResourceGroup

APIM 代理服务器在 TLS 握手中如何通过 SSL 证书进行响应

调用时使用 SNI 标头的客户端

如果客户为代理配置了一个或多个自定义域,则 APIM 可以响应来自自定义域(例如 contoso.com)以及默认域(例如 apim-service-name.azure-api.cn)的 HTTPS 请求。 APIM 根据服务器名称指示 (SNI) 标头中的信息使用合适的服务器证书进行响应。

调用时不使用 SNI 标头的客户端

如果客户使用不发送 SNI 标头的客户端,则 APIM 会根据以下逻辑创建响应:

  • 如果服务仅为代理配置了一个自定义域,则默认证书是已颁发给代理自定义域的证书。
  • 如果服务为代理配置了多个域(只有高级层才支持),则客户可以指定哪个证书应当作为默认证书。 若要设置默认证书,defaultSslBinding 属性应当设置为 true ("defaultSslBinding":"true")。 如果客户未设置该属性,则默认证书是颁发给 *.azure api.net 上托管的默认代理域的证书。

对包含大型有效负载的 PUT/POST 请求的支持

当在 HTTPS 中使用客户端证书时,APIM 代理服务器支持包含大型有效负载的请求(例如,有效负载 > 40 KB)。 若要防止服务器的请求被冻结,客户可以在代理主机名上设置属性 "negotiateClientCertificate": "true"。 如果该属性设置为 true,则在进行 SSL/TLS 连接时将在交换任何 HTTP 请求之前请求证书。 由于该设置是在代理主机名级别应用的,因此,所有连接请求都会请求客户端证书。 客户可以为代理配置最多 20 个自定义域(只有高级层才支持)并避开此限制。

后续步骤

有关 Azure PowerShell 模块的详细信息,请参阅 Azure PowerShell 文档

可以在 PowerShell 示例中找到 Azure API 管理的其他 Azure Powershell 示例。