文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>API 中心>边缘安全加速平台 EO>证书相关接口>配置域名证书

配置域名证书

最近更新时间：2025-10-22 02:53:00

我的收藏

本页目录：

1. 接口描述

接口请求域名： teo.tencentcloudapi.com 。

完成域名创建之后，您可以为域名配置自有证书，也可以使用 EdgeOne 为您提供的 免费证书。
如果您需要配置自有证书，请先将证书上传至 SSL证书控制台，然后在本接口中传入对应的证书 ID。详情参考 部署自有证书至 EdgeOne 域名 。

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称 必选 类型 描述
Action 是 String 公共参数，本接口取值：ModifyHostsCertificate。
Version 是 String 公共参数，本接口取值：2022-09-01。
Region 否 String 公共参数，此参数为可选参数。
ZoneId 是 String 站点 ID。
Hosts.N 是 Array of String 需要修改证书配置的加速域名。
Mode 否 String 配置服务端证书的模式，取值有：
  • disable：不配置服务端证书；
  • eofreecert：通过自动验证申请免费证书并部署。验证方式详见：申请免费证书支持的验证方式

    - 在 NS 或者 DNSPod 托管接入模式下，仅支持自动验证的方式申请免费证书。
    - 当免费证书申请失败时会导致证书部署失败，您可以通过检查免费证书申请结果接口获取申请失败原因。

  • eofreecert_manual：部署 DNS 委派验证或者文件验证申请的免费证书。在部署免费证书前，您需要触发申请免费证书接口申请免费证书。在免费证书申请成功后，你可以通过该枚举值对免费证书进行部署；

    • 注意：在对免费证书部署时，需要保证当前已存在申请成功的免费证书。您可以通过检查免费证书申请结果接口检查当前是否已存在申请成功的免费证书。

  • sslcert：配置 SSL 托管服务端证书。
    		•
    ServerCertInfo.N 否 Array of ServerCertInfo SSL 证书配置，本参数仅在 mode 为 sslcert 时生效，传入对应证书的 CertId 即可。您可以前往 SSL 证书列表 查看 CertId。
    ClientCertInfo 否 MutualTLS 在边缘双向认证场景下，该字段为客户端的 CA 证书，部署在 EO 节点内，用于客户端对 EO 节点进行认证。默认关闭，不填写表示保持原有配置。
    UpstreamCertInfo 否 UpstreamCertInfo 用于配置 EO 节点回源时携带的证书，用于回源双向认证握手，默认关闭，不填写表示保持原有配置。该配置当前为白名单内测中，如需使用，请联系我们。

    3. 输出参数

    参数名称 类型 描述
    RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

    4. 示例

    示例1 配置 SSL 证书

    针对站点（ZoneId 为 zone-2fgd17m17xw）下的域名（abc.test.com）配置 SSL 证书（CertId 为 J2JqATrt）。

    输入示例

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<公共请求参数>

{
    "ZoneId": "zone-2fgd17m17xw",
    "Hosts": [
        "abc.test.com"
    ],
    "Mode": "sslcert",
    "ServerCertInfo": [
        {
            "CertId": "J2JqATrt"
        }
    ]
}

    输出示例

    {
    "Response": {
        "RequestId": "5e5a0d0f-52f3-4bad-9bd3-dcf1d5c954e7"
    }
}

    示例2 配置免费证书

    针对站点（ZoneId 为 zone-2fgd17m17xw）下的域名（abc.test.com）配置免费证书。

    输入示例

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<公共请求参数>

{
    "ZoneId": "zone-2fgd17m17xw",
    "Hosts": [
        "abc.test.com"
    ],
    "Mode": "eofreecert"
}

    输出示例

    {
    "Response": {
        "RequestId": "084d5612-67a7-4aca-aac9-827aa3662b2d"
    }
}

    示例3 配置边缘双向认证

    针对站点（ZoneId 为 zone-2fgd17m17xw）下的域名（abc.test.com）配置 边缘双向认证（CertId 为 J2JqATrt）。

    输入示例

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<公共请求参数>

{
    "ZoneId": "zone-2fgd17m17xw",
    "Hosts": [
        "abc.test.com"
    ],
    "ClientCertInfo": {
        "Switch": "on",
        "CertInfos": [
            {
                "CertId": "J2JqATrt"
            }
        ]
    }
}

    输出示例

    {
    "Response": {
        "RequestId": "5e5a0d0f-52f3-4bad-9bd3-dcf1d5c954e7"
    }
}

    5. 开发者资源

    腾讯云 API 平台

    腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

    API Inspector

    用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

    SDK

    云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

    命令行工具

    6. 错误码

    以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。

    错误码 描述
    FailedOperation 操作失败。
    FailedOperation.CertificateHasExpired 边缘HTTPS证书已过期，暂不支持下发过期证书。
    FailedOperation.CertificateNotFound 边缘HTTPS证书不存在。
    FailedOperation.EdgeClientCertificateHasExpired 边缘客户端证书已过期，暂不支持下发过期证书。
    FailedOperation.InvalidZoneStatus 站点状态不正确。
    FailedOperation.ModifyFailed 操作失败。
    FailedOperation.UpstreamClientCertificateHasExpired 回源客户端证书已过期，暂不支持下发过期证书。
    InternalError.ConfigLocked 配置已被锁定，请解除配置锁定之后在重试。
    InternalError.GetRoleError 获取角色失败。
    InternalError.ProxyServer 后端服务器发生未知错误。
    InternalError.RouteError 后端服务路由地址错误。
    InternalError.SystemError 内部错误-系统错误。
    InternalError.UnknowError 未知错误。
    InvalidParameter.ActionInProgress 操作频繁，请稍后重试。
    InvalidParameter.AliasDomainNotSupportKeyless 别称域名不支持配无私钥证书。
    InvalidParameter.CertNotMatchDomain 无效的边缘HTTPS证书配置，证书与域名不匹配。
    InvalidParameter.CertToExpire 边缘HTTPS证书即将过期。
    InvalidParameter.CertTooShortKeySize 无效的边缘HTTPS证书配置，密钥长度不符合最短要求RSA>=2048,DSA>=2048,DH>=2048,EC>=225。
    InvalidParameter.CertificateConflictWithKeylessServer 待变更域名未绑定证书或 keyless 服务端，请先绑定后再操作。
    InvalidParameter.CnameWildHostNotAllowApplyCertificate CNAME模式下无法申请泛域名证书。
    InvalidParameter.EdgeClientCertCheckError 无效的边缘客户端证书配置。
    InvalidParameter.HostStatusNotAllowApplyCertificate CNAME 未切换或者源站未路由到EO服务器。
    InvalidParameter.InvalidCertInfo 无效的边缘HTTPS证书信息。
    InvalidParameter.InvalidHttpsCertInfo 无效的边缘HTTPS证书配置，证书内容无效。
    InvalidParameter.InvalidHttpsTlsVersion 无效的HTTPS TLS版本。
    InvalidParameter.UpstreamClientCertCheckError 无效的回源客户端证书配置。
    InvalidParameter.ZoneIsGrayPublishing 站点升级中，暂不支持进行变更操作，请稍后再试。
    InvalidParameterValue.AliasDomainNotSupportEdgeMTLS 别称域名暂不支持配置边缘双向认证。
    InvalidParameterValue.AliasDomainNotSupportUpstreamMTLS 别称域名暂不支持配置回源双向认证。
    InvalidParameterValue.CertificateVerifyClientMustCa 边缘双向认证配置中的客户端证书必须是CA证书。
    InvalidParameterValue.CertificateVerifyClientNeedCert 边缘双向认证配置至少需要配置一本证书。
    InvalidParameterValue.CertificateVerifyUpstreamClientMustRSAorECC 当前回源双向认证的证书仅支持 RSA或 ECC 算法证书，暂不支持国密 SM2 算法证书。
    InvalidParameterValue.CertificateVerifyUpstreamClientMustSVR 回源双向认证的证书类型不正确，不支持配置为 CA 证书。
    InvalidParameterValue.CertificateVerifyUpstreamClientNeedCert 回源双向认证配置至少需要配置一本证书。
    InvalidParameterValue.ClientCertInfoQuotaLimit 边缘双向认证配置中的客户端 CA 证书最多允许配置20本。
    InvalidParameterValue.InvalidKeylessServerId 无效的 keyless 服务端 Id。
    InvalidParameterValue.ServerCertInfoNeedContainRSAorECC 已开启边缘双向认证，客户端使用 RSA 或者 ECC 算法证书时，边缘 HTTPS 证书必须也配置有相同算法证书。
    InvalidParameterValue.ServerCertInfoNeedContainSM2 已开启边缘双向认证，客户端使用国密算法 CA 证书时，边缘 HTTPS 证书必须也配置有国密证书。
    InvalidParameterValue.UpstreamClientCertInfoQuotaLimit 回源双向认证配置中的客户端证书最多允许配置1本。
    LimitExceeded.RateLimitExceeded 单位时间内接口请求频率达到限制。
    OperationDenied 操作被拒绝。
    OperationDenied.CertificatePrivateKeyIsEmpty 当前仅无私钥证书模式允许证书私钥为空。
    OperationDenied.ConfigLocked 配置已被锁定，请解除配置锁定之后在重试。
    OperationDenied.DisableZoneNotCompleted 站点停用未完毕，请稍后再试。
    OperationDenied.ErrZoneIsAlreadyPaused 站点处于停用状态，请开启后重试。
    OperationDenied.HostsClientCertificateInconsistency 待变更域名边缘双向认证证书不一致，请确认变更域名证书一致后重试。
    OperationDenied.HostsKeylessServerInconsistency 待变更域名 keyless 服务端不一致，请确认变更域名 keyless 服务端一致后重试。
    OperationDenied.HostsUpstreamCertificateInconsistency 待变更域名回源双向认证证书不一致，请确认变更域名证书一致后重试。
    OperationDenied.KeylessCertSwitchToFreeCertConflict 待变更域名存在不同的证书或 keyless 服务端，请确认边缘 HTTPS 证书或 keyless 服务端一致后重试。
    OperationDenied.KeylessModeCertificatePrivateKeyNeedEmpty 当前无私钥证书模式要求证书私钥为空。
    OperationDenied.NotInKeylessWhiteList 当前无私钥证书功能仅针对白名单用户开放。
    OperationDenied.NotInUpstreamMTLSWhiteList 当前回源双向认证功能仅针对白名单用户开放。
    OperationDenied.UnSupportToCloseUpstreamMTLS 当前并不支持关闭回源双向认证，如需关闭，请通过将边缘 HTTPS 证书更改为不配置来关闭。
    OperationDenied.UseUpstreamMTLSNeedOpenHttps 如需启用回源双向认证，请先配置边缘 HTTPS 证书。
    OperationDenied.VersionControlIsGraying 存在使用中的测试版本，请将测试版本发布现网或者回滚测试版本再重试。
    ResourceInUse 资源被占用。
    ResourceUnavailable.CertNotFound 证书不存在或未授权。
    ResourceUnavailable.HostNotFound 域名不存在或未开启代理。
    ResourceUnavailable.ZoneNotFound 站点不存在或不属于该账号。
    UnauthorizedOperation.CamUnauthorized Cam 未授权。
    中国站
    目录