设置自定义域Set up custom domain

此示例脚本在 API 管理服务的代理和门户终结点上设置自定义域。This sample script sets up custom domain on proxy and portal endpoint of the API Management service.

Note

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

如果选择在本地安装并使用 PowerShell,则本教程需要 Azure PowerShell 模块 1.0 或更高版本。If you choose to install and use the PowerShell locally, this tutorial requires the Azure PowerShell module version 1.0 or later. 运行 Get-Module -ListAvailable Az 即可查找版本。Run Get-Module -ListAvailable Az to find the version. 如果需要升级,请参阅安装 Azure PowerShell 模块If you need to upgrade, see Install Azure PowerShell module. 如果在本地运行 PowerShell,则还需运行 Connect-AzAccount 来创建与 Azure 的连接。If you are running PowerShell locally, you also need to run Connect-AzAccount to create a connection with Azure.

示例脚本Sample script

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

清理资源Clean up resources

如果不再需要资源组和所有相关资源,可以使用 Remove-AzResourceGroup 命令将其删除。When no longer needed, you can use the Remove-AzResourceGroup command to remove the resource group and all related resources.

Remove-AzResourceGroup -Name myResourceGroup

APIM 代理服务器在 TLS 握手中如何通过 SSL 证书进行响应How APIM Proxy Server responds with SSL certificates in the TLS handshake

调用时使用 SNI 标头的客户端Clients calling with SNI header

如果客户为代理配置了一个或多个自定义域,则 APIM 可以响应来自自定义域(例如 contoso.com)以及默认域(例如 apim-service-name.azure-api.cn)的 HTTPS 请求。If the customer has one or multiple custom domains configured for Proxy, APIM can respond to HTTPS requests from the custom domain(s) (for example, contoso.com) as well as default domain (for example, apim-service-name.azure-api.cn). APIM 根据服务器名称指示 (SNI) 标头中的信息使用合适的服务器证书进行响应。Based on the information in the Server Name Indication (SNI) header, APIM responds with appropriate server certificate.

调用时不使用 SNI 标头的客户端Clients calling without SNI header

如果客户使用不发送 SNI 标头的客户端,则 APIM 会根据以下逻辑创建响应:If the customer is using a client, which does not send the SNI header, APIM creates responses based on the following logic:

  • 如果服务仅为代理配置了一个自定义域,则默认证书是已颁发给代理自定义域的证书。If the service has just one custom domain configured for Proxy, the Default Certificate is the certificate that was issued to the Proxy custom domain.
  • 如果服务为代理配置了多个域(只有高级层才支持),则客户可以指定哪个证书应当作为默认证书。If the service has configured multiple custom domains for Proxy (only supported in the Premium tier), the customer can designate which certificate should be the default certificate. 若要设置默认证书,defaultSslBinding 属性应当设置为 true ("defaultSslBinding":"true")。To set the default certificate, the defaultSslBinding property should be set to true ("defaultSslBinding":"true"). 如果客户未设置该属性,则默认证书是颁发给 *.azure api.net 上托管的默认代理域的证书。If the customer does not set the property, the default certificate is the certificate issued to default Proxy domain hosted at *.azure-api.net.

对包含大型有效负载的 PUT/POST 请求的支持Support for PUT/POST request with large payload

当在 HTTPS 中使用客户端证书时,APIM 代理服务器支持包含大型有效负载的请求(例如,有效负载 > 40 KB)。APIM Proxy server supports request with large payload when using client-side certificates in HTTPS (for example, payload > 40 KB). 若要防止服务器的请求被冻结,客户可以在代理主机名上设置属性 "negotiateClientCertificate": "true"To prevent the server's request from freezing, customers can set the property "negotiateClientCertificate": "true" on the Proxy hostname. 如果该属性设置为 true,则在进行 SSL/TLS 连接时将在交换任何 HTTP 请求之前请求证书。If the property is set to true, the client certificate is requested at SSL/TLS connection time, before any HTTP request exchange. 由于该设置是在代理主机名级别应用的,因此,所有连接请求都会请求客户端证书。Since the setting applies at the Proxy Hostname level, all connection requests ask for the client certificate. 客户可以为代理配置最多 20 个自定义域(只有高级层才支持)并避开此限制。Customers can configure up to 20 custom domains for Proxy (only supported in the Premium tier) and work around this limitation.

后续步骤Next steps

有关 Azure PowerShell 模块的详细信息,请参阅 Azure PowerShell 文档For more information on the Azure PowerShell module, see Azure PowerShell documentation.

可以在 PowerShell 示例中找到 Azure API 管理的其他 Azure Powershell 示例。Additional Azure Powershell samples for Azure API Management can be found in the PowerShell samples.