适用于：所有 API 管理层级
在 Azure 云中创建 Azure API 管理服务实例时，Azure 将为它分配一个 azure-api.cn 子域（例如 apim-service-name.azure-api.cn）。 你还可以使用自己的自定义域名（例如 contoso.com）公开 API 管理终结点。 本文演示了如何将现有的自定义 DNS 名称映射到 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 管理实例所有者才能在内部使用 Management 和 SCM 终结点。 很少会为这些终结点分配自定义域名。
- 开发和高级版层支持为网关终结点设置多个自定义主机名。
- 通配符域名（如
*.contoso.com）在以下层级中受支持：开发、基本、标准、高级。 例如，对于至 api.contoso.com 的请求，特定子域证书（例如，api.contoso.com）优先于通配符证书 (*.contoso.com)。 - 为 开发人员门户配置自定义域时，可以为新域名 启用 CORS 。 这是开发人员门户访问者使能使用 API 参考页中的交互式控制台所必要的。
域证书选项
API 管理支持从 Azure 密钥保管库导入的自定义 TLS 证书或证书。 还可以启用免费的托管证书。
警告
如果需要证书固定，请使用自定义域名和自定义证书或密钥保管库证书，而不是默认证书或免费托管证书。 我们不建议对一个你不管理的证书产生硬性依赖。
如果已有第三方提供商提供的私有证书，则可以上传它到 API 管理实例。 必须满足以下要求。 （如果启用由 API 管理托管的免费证书，则该证书已经满足这些要求。）
- 导出为 PFX 文件，使用三重 DES 加密并且还可以选择用密码进行保护。
- 包含长度至少为 2048 位的私钥
- 包含证书链中的所有中间证书和根证书。
重要
如果证书链使用交叉签名证书，API 管理可能会返回任何有效链，而你无法保证或控制返回哪一条。 确保客户端配置为信任所有可能的有效链，而不是依赖特定链。
配置自定义域名（门户）
根据想要使用的域证书选择步骤。
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 域名 - 实现和规范。
Azure 密钥保管库支持的证书的证书同步和故障排除
API 管理提供控件和诊断来帮助保持证书同步并快速解决访问问题。
例如，由于配置更改或连接问题，API 管理实例在更新或轮换证书后，可能无法从Azure 密钥保管库提取主机名证书。 发生这种情况时，API 管理实例将继续使用缓存的证书，直到它收到更新的证书。 如果缓存的证书过期，通往网关的运行时流量将被阻止。 使用过期的缓存证书时，任何使用主机名证书配置的上游服务（例如应用程序网关）也可以阻止到网关的运行时流量。
使用以下控件和诊断使证书保持同步，并防止或最小化停机时间。
同步证书
在命令栏上选择 “同步证书 ”，以在证书指纹发生更改时手动启动证书同步。 使用此选项可以避免等待自动同步作业，这可能需要几个小时或更长时间。
查看同步日志
选择命令栏上的 “查看同步日志 ”，以在证书同步失败时打开包含详细根本原因信息的面板。 这些日志可帮助你更快地诊断和解决同步问题。
还原对密钥保管库的访问权限
当 API 管理实例和自定义域使用的密钥保管库之间检测到访问问题时，API 管理会显示主动警告。 这些访问问题通常会导致证书同步失败。
如果出现警告，请选择“ 还原 ”以基于密钥保管库授权模型自动修复访问权限。 根据模型，API 管理执行以下操作之一来还原访问权限：
- 为基于 Azure RBAC 的密钥保管库分配 密钥保管库机密用户角色。
- 授予密钥保管库的基于访问策略的 GET 权限。
有关Azure 密钥保管库失败证书轮换的其他故障排除提示
确认用于访问密钥保管库的托管标识存在。
如果 API 管理实例部署在虚拟网络中，请确认与 AzureKeyVault 服务标记的出站连接。
API 管理代理服务器在 TLS 握手中如何通过 SSL 证书进行响应
为网关终结点配置自定义域时，可以设置其他属性，这些属性决定 API 管理如何使用服务器证书做出响应，具体取决于客户端请求。
调用时使用服务器名称指示 (SNI) 标头的客户端
如果为网关终结点配置了一个或多个自定义域，则 API 管理可以响应来自以下两者的 HTTPS 请求：
- 自定义域（例如
contoso.com） - 默认域（例如
apim-service-name.azure-api.cn）。
根据 SNI 标头中的信息，API 管理会使用相应的服务器证书进行响应。
调用时不使用 SNI 标头的客户端
如果使用不发送 SNI 标头的客户端，则 API 管理会根据以下逻辑创建响应：
如果服务仅为网关配置了一个自定义域 - 则默认证书是颁发给网关自定义域的证书。
** 如果服务为网关配置了多个自定义域（支持的层级包括 "开发者" 和 "高级版"），可以通过将 defaultSslBinding 属性设置为 "true" 指定默认证书 ()。 在门户中，选择“默认 SSL 绑定”复选框。
如果未设置该属性，则默认证书是颁发给在
*.azure-api.cn上托管的默认网关域的证书。
对包含大型有效负载的 PUT/POST 请求的支持
当在 HTTPS 中使用客户端证书时，API 管理代理服务器支持包含大型有效负载 (> 40 KB) 的请求。 为了防止服务器的请求被冻结，可以在网关主机名上将 negotiateClientCertificate 属性设置为 true("negotiateClientCertificate": "true")。 在门户中，选中“协商客户端证书”复选框。
如果该属性设置为 true，则将在交换任何 HTTP 请求之前于 SSL/TLS 连接时请求客户端证书。 由于该设置应用于“网关主机名”级别，因此所有连接请求都会要求客户端证书。 可以避开此限制并为网关配置最多 20 个自定义域（仅在高级层才受支持）。