tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

ModifyHostsCertificate

Last updated: 2024-11-14 16:58:14

    1. API Description

    Domain name for API request: teo.tencentcloudapi.com.

    This API is used to configure the certificate of a site. You can use your own certificate or apply for a free certificate.
    To use an external certificate, upload the certificate to SSL Certificates Console first, and then input the certificate ID in this API. For details, see Deploying Own Certificates to EdgeOne Domains.

    A maximum of 20 requests can be initiated per second for this API.

    We recommend you to use API Explorer
    Try it
    API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

    2. Input Parameters

    The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

    Parameter Name Required Type Description
    Action Yes String Common Params. The value used for this API: ModifyHostsCertificate.
    Version Yes String Common Params. The value used for this API: 2022-09-01.
    Region No String Common Params. This parameter is not required.
    ZoneId Yes String ID of the site.
    Hosts.N Yes Array of String Domain names that you need to modify the certificate configuration
    Mode No String Certificate configuration mode. Values:
  • disable: (Default) Do not configure the certificate
  • eofreecert: Use a free certificate provided by EdgeOne
  • sslcert: Configure an SSL certificate.
    		•
    ServerCertInfo.N No Array of ServerCertInfo SSL certificate configuration. This parameter is effective only when the mode is sslcert. You only need to provide the CertId of the corresponding certificate. You can check the CertId from the SSL Certificate List.
    ClientCertInfo No MutualTLS In the Edge mTLS scenario, this field represents the client's CA certificate, which is deployed at the EO entry side for authenticating the client access to EO nodes. The original configuration applies if this field is not specified.

    3. Output Parameters

    Parameter Name Type Description
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Configuring an SSL certificate

    Add the certificate cert-244ffgv 7m17xw to the domain name abc.test.com under the site zone-2fgd 17m17xw.

    Input Example

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<Common request parameters>

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

    Output Example

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

    Example2 Configuring a free certificate

    Configure a free certificate for the domain name abc.test.com under the site zone-2fgd17m17xw.

    Input Example

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<Common request parameters>

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

    Output Example

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

    Example3 配置边缘双向认证

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

    Input Example

    POST / HTTP/1.1
Host: teo.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ModifyHostsCertificate
<common request parameters>

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

    Output Example

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

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    FailedOperation Operation failed.
    FailedOperation.CertificateHasExpired The edge HTTPS certificate has expired. Issuing expired certificates is currently not supported.
    FailedOperation.CertificateNotFound The edge HTTPS certificate does not exist.
    FailedOperation.EdgeClientCertificateHasExpired
    FailedOperation.InvalidZoneStatus The site status is invalid.
    FailedOperation.ModifyFailed Operation failed.
    FailedOperation.UpstreamClientCertificateHasExpired
    InternalError.ConfigLocked The configuration is locked. Please unlock and try again.
    InternalError.GetRoleError Failed to get the role.
    InternalError.ProxyServer An unknown error occurred in the backend server.
    InternalError.RouteError The backend routing address is incorrect.
    InternalError.SystemError Internal system error.
    InternalError.UnknowError Unknown error.
    InvalidParameter.ActionInProgress Too many attempts. Please try again later.
    InvalidParameter.AliasDomainNotSupportKeyless Alias domain names do not support configuring a keyless certificate.
    InvalidParameter.CertNotMatchDomain Invalid edge HTTPS certificate configuration. The certificate does not match the domain name.
    InvalidParameter.CertToExpire The edge HTTPS certificate is about to expire.
    InvalidParameter.CertTooShortKeySize Invalid edge HTTPS certificate configuration. The key length does not meet the minimum requirement RSA>=2048, DSA>=2048, DH>=2048, and EC>=225.
    InvalidParameter.CertificateConflictWithKeylessServer The domain name to be changed is not bound to a certificate or keyless server. Please bind it first and then proceed.
    InvalidParameter.CnameWildHostNotAllowApplyCertificate Unable to apply for a wildcard certificate under CNAME mode.
    InvalidParameter.EdgeClientCertCheckError
    InvalidParameter.HostStatusNotAllowApplyCertificate CNAME is not switched or the origin is not routed to the EdgeOne server.
    InvalidParameter.InvalidCertInfo Invalid edge HTTPS certificate information.
    InvalidParameter.InvalidHttpsCertInfo Invalid edge HTTPS certificate configuration. The certificate content is invalid.
    InvalidParameter.InvalidHttpsTlsVersion Invalid HTTPS TLS version.
    InvalidParameter.UpstreamClientCertCheckError
    InvalidParameter.ZoneIsGrayPublishing The site is being upgraded. Changing is not supported. Please try again later.
    InvalidParameterValue.AliasDomainNotSupportEdgeMTLS
    InvalidParameterValue.AliasDomainNotSupportUpstreamMTLS
    InvalidParameterValue.CertificateVerifyClientMustCa
    InvalidParameterValue.CertificateVerifyClientNeedCert
    InvalidParameterValue.CertificateVerifyUpstreamClientMustRSAorECC
    InvalidParameterValue.CertificateVerifyUpstreamClientMustSVR
    InvalidParameterValue.CertificateVerifyUpstreamClientNeedCert
    InvalidParameterValue.ClientCertInfoQuotaLimit
    InvalidParameterValue.InvalidKeylessServerId Invalid keyless server ID.
    InvalidParameterValue.ServerCertInfoNeedContainRSAorECC Edge mTLS is enabled. When the client uses an RSA or ECC algorithm certificate, the same algorithm certificate should also be configured in the edge HTTPS certificate.
    InvalidParameterValue.ServerCertInfoNeedContainSM2 Edge mTLS is enabled. When the client uses a national encryption CA certificate, the national encryption certificate should also be configured in the edge HTTPS certificate.
    InvalidParameterValue.UpstreamClientCertInfoQuotaLimit
    LimitExceeded.RateLimitExceeded Reached the API rate limit.
    OperationDenied Operation denied.
    OperationDenied.CertificatePrivateKeyIsEmpty Currently, only the keyless certificate mode allows the private key of the certificate to be empty.
    OperationDenied.ConfigLocked The configuration is locked. Please unlock and try again.
    OperationDenied.DisableZoneNotCompleted The EdgeOne service of the site is being disabled. Please try again later.
    OperationDenied.ErrZoneIsAlreadyPaused The EdgeOne service of the site is disabled. Please enable it and try again.
    OperationDenied.HostsClientCertificateInconsistency
    OperationDenied.HostsKeylessServerInconsistency The keyless server of the domain name to be changed is inconsistent. Please confirm that the keyless server is consistent before retrying.
    OperationDenied.HostsUpstreamCertificateInconsistency
    OperationDenied.KeylessCertSwitchToFreeCertConflict The domain name to be changed has a different certificate or keyless server. Please confirm that the edge HTTPS certificate or keyless server is consistent before retrying.
    OperationDenied.KeylessModeCertificatePrivateKeyNeedEmpty The keyless certificate mode requires the private key of the certificate to be empty.
    OperationDenied.NotInKeylessWhiteList Currently, the keyless certificate feature is available only to users in the allowlist.
    OperationDenied.NotInUpstreamMTLSWhiteList
    OperationDenied.UnSupportToCloseUpstreamMTLS
    OperationDenied.UseUpstreamMTLSNeedOpenHttps
    OperationDenied.VersionControlIsGraying There is a test version in use. Please release the test version to the live environment, or roll back the test version and try again.
    ResourceInUse The resource is occupied.
    ResourceUnavailable.CertNotFound The certificate does not exist or is not authorized.
    ResourceUnavailable.HostNotFound The domain name does not exist or not use a proxy.
    ResourceUnavailable.ZoneNotFound The site does not exist or is not belong to this account.
    UnauthorizedOperation.CamUnauthorized CAM is not authorized.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy