配置自定义域名Configure a custom domain name

创建 Azure API 管理服务实例时,Azure 会为其分配 azure-api.cn 的子域(例如,apim-service-name.azure-api.cn)。When you create an Azure API Management service instance, Azure assigns it a subdomain of azure-api.cn (for example, apim-service-name.azure-api.cn). 不过,你可以使用自己的自定义域名(例如 contoso.com)公开 API 管理终结点。However, you can expose your API Management endpoints using your own custom domain name, such as contoso.com. 本教程演示了如何将现有的自定义 DNS 名称映射到 API 管理实例公开的终结点。This tutorial shows you how to map an existing custom DNS name to endpoints exposed by an API Management instance.


API 管理仅接受主机头值与默认域名或任何已配置的自定义域名匹配的请求。API Management accepts only requests with host header values matching the default domain name or any of the configured custom domain names.


想要使用证书固定改进其应用程序安全性的客户必须使用自定义域名和他们管理的证书,而不是使用默认证书。Customers who wish to use certificate pinning to improve the security of their applications must use a custom domain name and certificate which they manage, not the default certificate. 改为固定默认证书的客户将硬依赖于他们不控制的证书属性,建议不要这样做。Customers that pin the default certificate instead will be taking a hard dependency on the properties of the certificate they don't control, which is not a recommended practice.


若要执行本文中所述的步骤,必须具有:To perform the steps described in this article, you must have:

  • 一个有效的 Azure 订阅。An active Azure subscription.

    如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

  • API 管理实例。An API Management instance. 有关详细信息,请参阅创建 Azure API 管理实例For more information, see Create an Azure API Management instance.

  • 由你或你的组织拥有的自定义域名。A custom domain name that is owned by you or your organization. 本主题不会提供有关如何购买自定义域名的说明。This topic does not provide instructions on how to procure a custom domain name.

  • 托管在 DNS 服务器上的 CNAME 记录,该记录将自定义域名映射到 API 管理实例的默认域名。A CNAME record hosted on a DNS server that maps the custom domain name to the default domain name of your API Management instance. 本主题不会提供有关如何托管 CNAME 记录的说明。This topic does not provide instructions on how to host a CNAME record.

  • 必须具有有效的带有公钥和私钥 (.PFX) 的证书。You must have a valid certificate with a public and private key (.PFX). 使用者或使用者可选名称 (SAN) 必须与域名匹配(这使得 API 管理实例可以通过 TLS 安全地公开 URL)。Subject or subject alternative name (SAN) has to match the domain name (this enables API Management instance to securely expose URLs over TLS).

使用 Azure 门户设置自定义域名Use the Azure portal to set a custom domain name

  1. Azure 门户中导航到自己的 API 管理实例。Navigate to your API Management instance in the Azure portal.

  2. 选择“自定义域”。Select Custom domains.

    可以为许多终结点分配自定义域名。There are a number of endpoints to which you can assign a custom domain name. 当前有以下终结点可用:Currently, the following endpoints are available:

    • 网关(默认值为:<apim-service-name>.azure-api.cn),Gateway (default is: <apim-service-name>.azure-api.cn),
    • 门户(默认值为:<apim-service-name>.portal.azure-api.cn),Portal (default is: <apim-service-name>.portal.azure-api.cn),
    • 管理(默认值为:<apim-service-name>.management.azure-api.cn),Management (default is: <apim-service-name>.management.azure-api.cn),
    • SCM(默认值为:<apim-service-name>.scm.azure-api.cn),SCM (default is: <apim-service-name>.scm.azure-api.cn),
    • NewPortal(默认值为:<apim-service-name>.developer.azure-api.cn)。NewPortal (default is: <apim-service-name>.developer.azure-api.cn).


    只有“网关”终结点可用于“消耗”层中的配置。Only the Gateway endpoint is available for configuration in the Consumption tier. 可以更新所有终结点或者更新其中的一部分。You can update all of the endpoints or some of them. 通常,客户会更新“网关”(此 URL 用来调用通过 API 管理公开的 API)和“门户”(开发人员门户 URL) 。Commonly, customers update Gateway (this URL is used to call the API exposed through API Management) and Portal (the developer portal URL). “管理”和“SCM”终结点由 API 管理实例所有者在内部使用,因此很少会为其分配自定义域名 。Management and SCM endpoints are used internally by the API Management instance owners only and thus are less frequently assigned a custom domain name. “高级”层级支持为“网关”终结点设置多个主机名。 The Premium tier supports setting multiple host names for the Gateway endpoint.

  3. 选择要更新的终结点。Select the endpoint that you want to update.

  4. 在右侧窗口中,单击“自定义”。In the window on the right, click Custom.

    • 在“自定义域名”中,指定要使用的名称。In the Custom domain name, specify the name you want to use. 例如,api.contoso.comFor example, api.contoso.com.
    • 证书中,从密钥保管库中选择证书。In the Certificate, select a certificate from Key Vault. 如果证书受密码保护,你还可以上传有效的 .PFX 文件并提供其密码You can also upload a valid .PFX file and provide its Password, if the certificate is protected with a password.


    通配符域名(例如 *.contoso.com)在除消耗层以外的所有层中都受支持。Wildcard domain names, e.g. *.contoso.com are supported in all tiers except the Consumption tier.


    我们建议使用 Azure Key Vault 管理证书并将其设置为“自动续订”。We recommend using Azure Key Vault for managing certificates and setting them to autorenew. 如果使用 Azure Key Vault 来管理自定义域 TLS/SSL 证书,请确保该证书作为证书而不是机密插入到 Key Vault 中 。If you use Azure Key Vault to manage the custom domain TLS/SSL certificate, make sure the certificate is inserted into Key Vault as a certificate, not a secret.

    若要提取 TLS/SSL 证书,API 管理必须对包含该证书的 Azure Key Vault 具有“列表”和“获取机密”权限。To fetch a TLS/SSL certificate, API Management must have the list and get secrets permissions on the Azure Key Vault containing the certificate. 使用 Azure 门户时,所有必要的配置步骤都将自动完成。When using Azure portal all the necessary configuration steps will be completed automatically. 使用命令行工具或管理 API 时,必须手动授予这些权限。When using command line tools or management API, these permissions must be granted manually. 此过程分为两个步骤。This is done in two steps. 首先,使用 API 管理实例上的“托管标识”页确保已启用“托管标识”并记下该页上显示的主体 ID。First, use Managed identities page on your API Management instance to make sure that Managed Identity is enabled and make a note of the principal id shown on that page. 其次,在包含证书的 Azure Key Vault 上为此主体 ID 提供权限列表并获取机密权限。Second, give permission list and get secrets permissions to this principal id on the Azure Key Vault containing the certificate.

    如果证书设置为“自动续订”,API 管理将自动选取最新版本,而不会对服务造成任何停机(如果你的 API 管理层具有 SLA - 即在除了开发人员层之外的所有层中)。If the certificate is set to autorenew, API Management will pick up the latest version automatically without any downtime to the service (if your API Management tier has SLA - i. e. in all tiers except the Developer tier).

  5. 单击“应用”。Click Apply.


    分配证书的过程可能需要 15 分钟或更久,这取决于部署规模。The process of assigning the certificate may take 15 minutes or more depending on size of deployment. 开发人员 SKU 有停机时间,基本 SKU 和更高 SKU 没有停机时间。Developer SKU has downtime, Basic and higher SKUs do not have downtime.

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.

DNS 配置DNS configuration

可使用两个选项来为自定义域名配置 DNS:When configuring DNS for your custom domain name, you have two options:

  • 配置一条指向已配置的自定义域名终结点的 CNAME 记录。Configure a CNAME-record that points to the endpoint of your configured custom domain name.
  • 配置一条指向 API 管理网关 IP 地址的 A 记录。Configure an A-record that points to your API Management gateway IP address.


尽管 API 管理实例 IP 地址是静态的,但在少数情况下它可能会更改。Although the API Managment instance IP address is static, it may change in a few scenarios. 因此,建议在配置自定义域时使用 CNAME。Because of this it's recommended to use CNAME when configuring custom domain. 选择 DNS 配置方法时,请考虑到这一点。Take that into consideration when choosing DNS configuration method. 有关详细信息,请参阅 IP 文档文章API 管理常见问题解答Read more in the the IP documentation article and the API Management FAQ.

后续步骤Next steps

升级和缩放你的服务Upgrade and scale your service