适用于：所有 API 管理层级
在 Azure 云中创建 Azure API 管理服务实例时，Azure 将为它分配一个 azure-api.cn 子域（例如 apim-service-name.azure-api.cn）。 你还可以使用自己的自定义域名（例如 contoso.com）公开 API 管理终结点。 本文演示了如何将现有的自定义 DNS 名称映射到 API 管理实例公开的终结点。
重要
API 管理仅接受主机头值与以下项匹配的请求：
重要
更改 API 管理服务的基础结构（例如配置自定义域、添加 CA 证书、缩放、虚拟网络配置、可用性区域更改和区域添加）可能需要 15 分钟或更长时间才能完成，具体取决于服务层和部署大小。 对于具有更大规模单位或多区域配置的实例，预期时间更长。 仔细执行对 API 管理的滚动更改，以保留容量和可用性。
当服务正在更新时，无法进行其他服务基础结构更改。 但是，可以配置 API、产品、策略和用户设置。 该服务 不会 经历网关停机，API 管理 将继续 服务 API 请求，而不会中断（开发人员层除外）。
先决条件
API 管理实例。 有关详细信息，请参阅创建 Azure API 管理实例。
由你或你的组织拥有的自定义域名。 本文不提供有关如何购买自定义域名的说明。
可选的，一个包含公钥和私钥的有效证书 (.PFX)。 主题或主题备用名称 (SAN) 必须与域名匹配，从而使 API 管理实例能够通过 TLS 安全地公开 URL。
查看域证书选项。
托管在 DNS 服务器上的 DNS 记录，该记录将自定义域名映射到 API 管理实例的默认域名。 本主题不提供有关如何托管 DNS 记录的说明。
有关所需记录的详细信息，请参阅本文后面的 DNS 配置。
自定义域的端点
可以向多个 API 管理终结点分配自定义域名。 当前有以下终结点可用：
| 端点 |
违约 |
|
网关 |
默认值为：<apim-service-name>.azure-api.cn。 网关是“消费层”中唯一可配置的终结点。
添加自定义网关域后，默认网关终结点配置仍可用。 |
|
开发人员门户（除“消耗”之外的所有层） |
默认值为：<apim-service-name>.developer.azure-api.cn |
|
管理 （仅限经典层） |
默认值为：<apim-service-name>.management.azure-api.cn |
|
自承载网关配置 API （v2） |
默认值为：<apim-service-name>.configuration.azure-api.cn |
|
SCM （仅限经典层） |
默认值为：<apim-service-name>.scm.azure-api.cn |
注意事项
- 您可以更新服务层级中支持的任何终结点。 通常，客户会更新“网关”（此 URL 用于调用通过 API 管理公开的 API）和“开发人员门户”（开发人员门户 URL）。
- 配置自定义网关域名后，默认网关终结点仍然可用，并且无法删除。 对于使用自定义域名配置的其他 API 管理终结点（如开发者门户），默认终结点不再可用。
- 只有 API 管理实例的所有者可以在内部使用管理和SCM终结点。 很少会为这些终结点分配自定义域名。
- “高级”和“开发人员”层支持为“网关”终结点设置多个主机名。
- 除“使用层”之外的所有层都支持像
*.contoso.com这样的通配符域名。 例如，对于至 api.contoso.com 的请求，特定子域证书（例如，api.contoso.com）优先于通配符证书 (*.contoso.com)。
- 为 开发人员门户配置自定义域时，可以为新域名 启用 CORS 。 这是开发人员门户访问者使能使用 API 参考页中的交互式控制台所必要的。
域证书选项
API 管理支持从 Azure 密钥保管库导入的自定义 TLS 证书或证书。 还可以启用免费的托管证书。
警告
如果需要证书固定，请使用自定义域名和自定义证书或密钥保管库证书，而不是默认证书或免费托管证书。 我们不建议对一个你不管理的证书产生硬性依赖。
如果已有第三方提供商提供的私有证书，则可以上传它到 API 管理实例。 必须满足以下要求。 （如果启用由 API 管理托管的免费证书，则该证书已经满足这些要求。）
- 导出为 PFX 文件，使用三重 DES 加密并且还可以选择用密码进行保护。
- 包含长度至少为 2048 位的私钥
- 包含证书链中的所有中间证书和根证书。
建议使用 Azure 密钥保管库管理证书，并将这些证书设置为 autorenew。
如果使用 Azure 密钥保管库来管理自定义域 TLS 证书，请确保该证书“作为证书”而不是“机密”插入密钥保管库。
谨慎
在 API 管理中使用密钥保管库证书时，请注意不要删除证书、密钥保管库或用于访问密钥保管库的托管标识。
若要提取 TLS/SSL 证书，API 管理必须对包含该证书的 Azure Key Vault 具有“列表”和“获取机密”权限。
如果证书设置为 autorenew 并且 API 管理层（除“开发人员”层以外的所有层）附带 SLA，API 管理将自动选取最新版本，而不会给服务造成任何中断。
有关详细信息，请参阅在 Azure API 管理中使用托管标识。
配置自定义域名（门户）
根据想要使用的域证书选择步骤。
- 在 Azure 门户中导航到自己的 API 管理实例。
- 在左侧导航栏中选择“自定义域”。
- 选择+添加，或选择要更新的现有终结点。
- 在右侧窗口中，选择自定义域终结点的类型。
- 在“主机名”字段中，指定要使用的名称。 例如，
api.contoso.com。
- 在“证书”下，选择“自定义”
- 选择“证书文件”以选择并上传证书。
- 上传有效的 .PFX 文件并提供其密码（如果该证书受密码保护）。
- 配置网关终结点时，请根据需要选择或取消选择其他选项，包括“协商客户端证书”或“默认 SSL 绑定”。
- 选择“添加”或为现有终结点选择“更新”。
- 选择“保存”。
- 在 Azure 门户中导航到自己的 API 管理实例。
- 在左侧导航栏中选择“自定义域”。
- 选择+添加，或选择要更新的现有终结点。
- 在右侧窗口中，选择自定义域终结点的类型。
- 在“主机名”字段中，指定要使用的名称。 例如，
api.contoso.com。
- 在“证书”下，选择“密钥保管库”然后“选择”。
- 从下拉列表中选择“订阅”。
- 从下拉列表中选择“密钥保管库”。
- 加载证书后，从下拉列表中选择“证书”。 单击“选择”。
- 在“客户端标识”中，选择在实例中启用的系统分配的标识或用户分配的托管标识以访问密钥保管库。
- 配置网关终结点时，请根据需要选择或取消选择其他选项，包括“协商客户端证书”或“默认 SSL 绑定”。
- 选择“添加”或为现有终结点选择“更新”。
- 选择“保存”。
DNS 配置
将 DNS 提供程序配置为将自定义域名映射到 API 管理实例的默认域名。
CNAME 记录
配置从自定义域名（例如，api.contoso.com）指向 API 管理服务主机名（例如 yourapim-service-name.azure-api.net）的 CNAME 记录。 如果 IP 地址发生更改，CNAME 记录比 A 记录更稳定。 有关详细信息，请参阅 Azure API 管理的 IP 地址和 API 管理常见问题解答。
注释
某些域注册机构只允许在使用 CNAME 记录（例如 www.contoso.com），而非根名称（例如 contoso.com）时映射子域。 有关 CNAME 记录的详细信息，请参阅注册机构提供的文档或 IETF 域名 - 实现和规范。
CNAME 记录
配置从自定义域名（例如，api.contoso.com）指向 API 管理服务主机名（例如 yourapim-service-name.azure-api.net）的 CNAME 记录。 如果 IP 地址发生更改，CNAME 记录比 A 记录更稳定。 有关详细信息，请参阅 Azure API 管理的 IP 地址和 API 管理常见问题解答。
注释
某些域注册机构只允许在使用 CNAME 记录（例如 www.contoso.com），而非根名称（例如 contoso.com）时映射子域。 有关 CNAME 记录的详细信息，请参阅注册机构提供的文档或 IETF 域名 - 实现和规范。
TXT 记录
为 API 管理启用免费的托管证书时，还会在 DNS 区域中配置 TXT 记录以建立域名的所有权。
- 记录的名称是前缀为
apimuid 的自定义域名。 示例：apimuid.api.contoso.com。
- 该值是 API 管理实例提供的域所有权标识符。
使用门户配置自定义域的免费托管证书时，会自动显示必需 TXT 记录的名称和值。
还可以通过调用获取域所有权标识符 REST API 来获取域所有权标识符。
API 管理代理服务器在 TLS 握手中如何通过 SSL 证书进行响应
为网关终结点配置自定义域时，可以设置其他属性，这些属性决定 API 管理如何使用服务器证书做出响应，具体取决于客户端请求。
如果为网关终结点配置了一个或多个自定义域，则 API 管理可以响应来自以下两者的 HTTPS 请求：
- 自定义域（例如
contoso.com）
- 默认域（例如
apim-service-name.azure-api.cn）。
根据 SNI 标头中的信息，API 管理会使用相应的服务器证书进行响应。
如果使用不发送 SNI 标头的客户端，则 API 管理会根据以下逻辑创建响应：
如果服务仅为网关配置了一个自定义域 - 则默认证书是颁发给网关自定义域的证书。
**
如果服务为网关配置了多个自定义域（支持的层级包括 "开发者" 和 "高级版"），可以通过将 defaultSslBinding 属性设置为 "true" 指定默认证书 ()。 在门户中，选择“默认 SSL 绑定”复选框。
如果未设置该属性，则默认证书是颁发给在 *.azure-api.cn 上托管的默认网关域的证书。
对包含大型有效负载的 PUT/POST 请求的支持
当在 HTTPS 中使用客户端证书时，API 管理代理服务器支持包含大型有效负载 (> 40 KB) 的请求。 为了防止服务器的请求被冻结，可以在网关主机名上将 negotiateClientCertificate 属性设置为 true("negotiateClientCertificate": "true")。 在门户中，选中“协商客户端证书”复选框。
如果该属性设置为 true，则将在交换任何 HTTP 请求之前于 SSL/TLS 连接时请求客户端证书。 由于该设置应用于“网关主机名”级别，因此所有连接请求都会要求客户端证书。 可以避开此限制并为网关配置最多 20 个自定义域（仅在高级层才受支持）。
故障排除：从 Azure Key Vault 轮换主机名证书失败
由于配置更改或连接问题，API 管理实例在更新或轮换证书后可能无法从 Azure Key Vault 提取主机名证书。 发生这种情况时，API 管理实例将继续使用缓存的证书，直到它收到更新的证书。 如果缓存的证书过期，通往网关的运行时流量将被阻止。 使用过期的缓存证书时，任何使用主机名证书配置的上游服务（例如应用程序网关）也可以阻止到网关的运行时流量。
要缓解此问题，请确认密钥库是否存在，并且证书是否存储在密钥库中。 如果 API 管理实例部署在虚拟网络中，请确认与 AzureKeyVault 服务标记的出站连接。 检查用于访问密钥保管库的托管标识是否存在。 确认托管身份对密钥库的访问权限。 有关详细配置步骤，请查看本文前面的 设置自定义域名 - Key Vault。 还原配置后，主机名证书将在 4 小时内在 API 管理中刷新。
相关内容
升级和扩展你的服务