你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
为 Azure API 管理实例配置自定义域名
适用于：所有 API 管理层级
在 Azure 云中创建 Azure API 管理服务实例时，Azure 将为它分配一个 azure-api.net 子域（例如 apim-service-name.azure-api.net）。 你还可以使用自己的自定义域名（例如 contoso.com）公开 API 管理终结点。 本文演示了如何将现有的自定义 DNS 名称映射到 API 管理实例公开的终结点。
注意
目前，工作区网关不支持自定义域名。
先决条件
API 管理实例。 有关详细信息，请参阅创建 Azure API 管理实例。
由你或你的组织拥有的自定义域名。 本文不提供有关如何购买自定义域名的说明。
可选的，一个包含公钥和私钥的有效证书 (.PFX)。 使用者或使用者可选名称 (SAN) 必须与域名匹配（这使得 API 管理实例可以通过 TLS 安全地公开 URL）。
查看域证书选项。
托管在 DNS 服务器上的 DNS 记录，该记录将自定义域名映射到 API 管理实例的默认域名。 本主题不提供有关如何托管 DNS 记录的说明。
有关所需记录的详细信息，请参阅本文后面的 DNS 配置。
自定义域的终结点
可以向多个 API 管理终结点分配自定义域名。 当前有以下终结点可用：
| 端点 | 默认 |
|---|---|
| 网关 | 默认值为：<apim-service-name>.azure-api.net。 网关是唯一可用于“消耗”层中的配置的终结点。添加自定义网关域后，默认网关终结点配置仍可用。 |
| 开发人员门户 | 默认值为：<apim-service-name>.developer.azure-api.net |
| Management | 默认值为：<apim-service-name>.management.azure-api.net |
| 配置 API (v2) | 默认值为：<apim-service-name>.configuration.azure-api.net |
| SCM | 默认值为：<apim-service-name>.scm.azure-api.net |
注意事项
- 可以更新服务层中支持的任何终结点。 通常，客户会更新“网关”（此 URL 用于调用通过 API 管理公开的 API）和“开发人员门户”（开发人员门户 URL）。
- 配置自定义网关域名后，仍然可使用默认网关终结点，并且无法删除它。 对于使用自定义域名配置的其他 API 管理终结点（如开发者门户），默认终结点不再可用。
- 只有 API 管理实例所有者能够在内部使用“管理”和“SCM”终结点 。 很少会为这些终结点分配自定义域名。
- “高级”和“开发人员”层支持为“网关”终结点设置多个主机名。
- 除“消耗”层之外的所有层都支持类似于
*.contoso.com的通配符域名。 例如，对于至 api.contoso.com 的请求，特定子域证书（例如，api.contoso.com）优先于通配符证书 (*.contoso.com)。
域证书选项
API 管理支持从 Azure 密钥保管库导入的自定义 TLS 证书或证书。 还可以启用免费的托管证书。
警告
如果需要证书固定，请使用自定义域名和自定义或密钥保管库证书，而不是默认证书或免费托管证书。 建议不要硬依赖于一个你不管理的证书。
如果已有第三方提供商提供的私有证书，则可以上传它到 API 管理实例。 必须满足以下要求。 （如果启用由 API 管理托管的免费证书，则该证书已经满足这些要求。）
- 导出为 PFX 文件，使用三重 DES 加密并且还可以选择用密码进行保护。
- 包含长度至少为 2048 位的私钥
- 包含证书链中的所有中间证书和根证书。
配置自定义域名（门户）
根据想要使用的域证书选择步骤。
DNS 配置
- 为自定义域配置 CNAME 记录。
- 使用 API 管理的免费托管证书时，还会配置 TXT 记录以建立域的所有权。
注意
免费证书是由 DigiCert 颁发的。 对于某些域，必须通过创建值为 0 issue digicert.com 的 CAA 域记录显式允许 DigiCert 作为证书颁发者。
CNAME 记录
配置从自定义域名（例如，api.contoso.com）指向 API 管理服务主机名（例如 <apim-service-name>.azure-api.net）的 CNAME 记录。 如果 IP 地址发生更改，CNAME 记录比 A 记录更稳定。 有关详细信息，请参阅 Azure API 管理的 IP 地址和 API 管理常见问题解答。
注意
某些域注册机构只允许在使用 CNAME 记录（例如 www.contoso.com），而非根名称（例如 contoso.com）时映射子域。 有关 CNAME 记录的详细信息，请参阅注册机构提供的文档或 IETF 域名 - 实现和规范。
注意
使用免费的托管证书并使用 DNS 提供商配置 CNAME 记录时，请确保将 CNAME 记录解析为默认的 API 管理服务主机名 (<apim-service-name>.azure-api.net)。 目前，如果 CNAME 记录未解析为默认的 API 管理主机名，API 管理将不会自动续订证书。 例如，如果使用免费的托管证书，并且使用 Cloudflare 作为 DNS 提供商，请确保未在 CNAME 记录上启用 DNS 代理。
TXT 记录
为 API 管理启用免费的托管证书时，还会在 DNS 区域中配置 TXT 记录以建立域名的所有权。
- 记录的名称是前缀为
apimuid的自定义域名。 示例：apimuid.api.contoso.com。 - 该值是 API 管理实例提供的域所有权标识符。
使用门户配置自定义域的免费托管证书时，会自动显示必需 TXT 记录的名称和值。
还可以通过调用获取域所有权标识符 REST API 来获取域所有权标识符。
API 管理代理服务器如何在 TLS 握手中使用 SSL 证书做出响应
为网关终结点配置自定义域时，可以设置其他属性，这些属性决定 API 管理如何服务器证书做出响应，具体取决于客户端请求。
调用时使用服务器名称指示 (SNI) 标头的客户端
如果为网关终结点配置了一个或多个自定义域，则 API 管理可以响应来自以下两者的 HTTPS 请求：
- 自定义域（例如
contoso.com） - 默认域（例如
apim-service-name.azure-api.net）。
根据 SNI 标头中的信息，API 管理会使用相应的服务器证书进行响应。
调用时不使用 SNI 标头的客户端
如果使用不发送 SNI 标头的客户端，则 API 管理会根据以下逻辑创建响应：
如果服务仅为网关配置了一个自定义域 - 则默认证书是颁发给网关自定义域的证书。
如果服务为网关配置了多个自定义域（在“开发人员层”和“高级层”中受支持）- 则可以通过将 defaultSslBinding 属性设置 true (
"defaultSslBinding":"true") 来指定默认证书。 在门户中，选择“默认 SSL 绑定”复选框。如果未设置该属性，则默认证书是颁发给在
*.azure-api.net上托管的默认网关域的证书。
对包含大型有效负载的 PUT/POST 请求的支持
当在 HTTPS 中使用客户端证书时，API 管理代理服务器支持包含大型有效负载 (> 40 KB) 的请求。 为了防止服务器的请求被冻结，可以在网关主机名上将 negotiateClientCertificate 属性设置为 true("negotiateClientCertificate": "true")。 在门户中，选择“协商客户端证书”复选框。
如果该属性设置为 true，则在进行 SSL/TLS 连接时将在交换任何 HTTP 请求之前请求证书。 由于该设置应用于“网关主机名”级别，因此所有连接请求都会要求客户端证书。 可以避开此限制并为网关配置最多 20 个自定义域（仅在高级层才受支持）。