设置自定义域

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

备注

本文已经过更新,以便使用 Azure Az PowerShell 模块。 若要与 Azure 交互,建议使用的 PowerShell 模块是 Az PowerShell 模块。 若要开始使用 Az PowerShell 模块,请参阅安装 Azure PowerShell。 若要了解如何迁移到 Az PowerShell 模块,请参阅 将 Azure PowerShell 从 AzureRM 迁移到 Az

如果选择在本地安装并使用 PowerShell,则本教程需要安装 Azure PowerShell 模块 1.0 或更高版本。 运行 Get-Module -ListAvailable Az 即可查找版本。 如果需要进行升级,请参阅 Install Azure PowerShell module(安装 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 = "China 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

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 示例。