Custom Domain

Manage the custom domain binding and HTTP access routing rules for TCB environments. Access via app.env.

version tip

Since v5.0.0, this capability has been added. Before v5.0.0, please use HTTP Access Service (Legacy).

Conceptual Overview

Concept	Description
Custom Domain	Custom domain bound to TCB HTTP access service, supports HTTPS certificate configuration
Access Routing	Configure path-to-upstream service (SCF/Cloud Run/Static Hosting) mapping rules under a domain
AccessType	Domain access method: DIRECT (Direct) / CDN (TCB CDN) / CUSTOM (Custom CDN/WAF)
Protocol	HTTPS protocol policy: HTTP_AND_HTTPS / HTTP_TO_HTTPS (force redirect) / HTTPS_TO_HTTP
UpstreamResourceType	Routing upstream type: SCF (Cloud Function) / CBR (Cloud Run) / STATIC_STORE (Static Hosting) / WEB_SCF (Web Cloud Function)

---

describeHttpServiceRoute

1. API Description

API feature: queries the list of domains and access routes in the environment, supports multi-dimensional filtering

API declaration: app.env.describeHttpServiceRoute(params): Promise<DescribeHttpServiceRouteRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Filters	Optional	HTTPServiceRouteFilter[]	Filter conditions, supporting Domain, Path, DomainType, UpstreamResourceType
Offset	No	Number	Pagination offset, default 0
Limit	No	Number	Page size, default 20, maximum 1000

3. Return Results

Field	Type	Description
Domains	HTTPServiceDomain[]	List of domain routing information
OriginDomain	String	HTTP service origin domain (for custom CDN/WAF origin)
TotalCount	Number	Total number of domains
RequestId	String	Unique identifier of the request

HTTPServiceDomain

Field	Type	Description
Domain	String	Domain
DomainType	String	Domain type
AccessType	String	Access method: DIRECT / CDN / CUSTOM
CertId	String	SSL Certificate ID
Protocol	String	Protocol type
Cname	String	Target value of the CNAME to be configured
IsDefault	Boolean	Whether it is the default domain
Enable	Boolean	Whether it has been enabled
Status	String	Status: PROCESSING / FAIL / SUCCESS
DNSStatus	String	DNS resolution status: OK / INVALID
Routes	HTTPServiceRoute[]	List of routes under the domain
CreateTime	String	Creation time
UpdateTime	String	Update time

4. Sample Code

const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({ secretId: 'Your SecretId', secretKey: 'Your SecretKey', envId: 'your-env-id' })

async function test() {
  const { Domains, TotalCount } = await app.env.describeHttpServiceRoute({
    EnvId: 'your-env-id',
    Limit: 20
  })
  console.log(`Total ${TotalCount} domains`)
  Domains.forEach(d => console.log(d.Domain, d.Status, d.DNSStatus))
}

test()

---

bindCustomDomain

1. API Description

API feature: Bind custom domains to HTTP access service, supports configuring HTTPS certificates and access methods.

API declaration: app.env.bindCustomDomain(params): Promise<BindCustomDomainRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	BindCustomDomainDomainParam	Domain configuration, see description below

BindCustomDomainDomainParam

Field	Required	Type	Description
Domain	Required	String	Domain, globally unique
CertId	Yes	String	SSL Certificate ID (Tencent Cloud SSL Platform)
AccessType	No	String	Access method: DIRECT (default) / CDN / CUSTOM
Protocol	No	String	Protocol policy: default HTTP_AND_HTTPS
Enable	No	Boolean	Whether to enable immediately, default true
CustomCname	No	String	Custom CDN/WAF origin CNAME (required when AccessType=CUSTOM)

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request

4. Sample Code

async function test() {
  await app.env.bindCustomDomain({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      CertId: 'your-cert-id',
      AccessType: 'DIRECT',
      Protocol: 'HTTP_TO_HTTPS'
    }
  })
  console.log('Domain name binding succeeded. Please configure the CNAME record with your DNS provider.')
}

test()

---

deleteCustomDomain

1. API Description

API feature: Delete custom domains. An error will be thrown if routes are bound to the domain. Delete the routes first.

API declaration: app.env.deleteCustomDomain(params): Promise<DeleteCustomDomainRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Required	String	Domain name to be deleted

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request

---

createHttpServiceRoute

1. API Description

API feature: Create access routing under a specified domain, mapping paths to upstream services such as SCF, Cloud Run, or Static Hosting.

API declaration: app.env.createHttpServiceRoute(params): Promise<CreateHttpServiceRouteRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	HTTPServiceDomainParam	Domain and routing configuration, see description below

HTTPServiceDomainParam

Field	Required	Type	Description
Domain	Yes	String	Domain (already bound)
Routes	No	HTTPServiceRouteParam[]	List of routes, up to 20 items
AccessType	No	String	Access method
CertId	No	String	SSL Certificate ID
Protocol	No	String	Protocol policy
Enable	No	Boolean	Domain enabled status

HTTPServiceRouteParam (single route)

Field	Required	Type	Description
Path	Yes	String	Route path, e.g. /api
UpstreamResourceType	No	String	Upstream type: SCF / CBR / STATIC_STORE / WEB_SCF / LH
UpstreamResourceName	No	String	Upstream service name (e.g. SCF function name / Cloud Run service name)
PathRewrite	No	HTTPServicePathRewrite	Path rewrite configuration
EnableSafeDomain	No	Boolean	Whether to enable the safe domain, default true
EnableAuth	No	Boolean	Whether to enable Identity Authentication, default false
EnablePathTransmission	No	Boolean	Whether to enable path transmission, default false
QPSPolicy	No	HTTPServiceRouteQPSPolicy	QPS rate limiting policy
Enable	No	Boolean	Whether to enable route, default true

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request

4. Sample Code

async function test() {
  // Create a route under the bound domain: map /api to the SCF my-function
  await app.env.createHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      Routes: [
        {
          Path: '/api',
          UpstreamResourceType: 'SCF',
          UpstreamResourceName: 'my-function',
          EnableAuth: false,
          Enable: true
        }
      ]
    }
  })
  console.log('Route created successfully')
}

test()

---

modifyHttpServiceRoute

1. API Description

API feature: Modify the access routing configuration under the specified domain.

API declaration: app.env.modifyHttpServiceRoute(params): Promise<ModifyHttpServiceRouteRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Same as createHttpServiceRoute, see the description above.

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request

---

deleteHttpServiceRoute

1. API Description

API feature: Delete access routes under the specified domain. If Paths is not provided, delete all routes under the domain.

API declaration: app.env.deleteHttpServiceRoute(params): Promise<DeleteHttpServiceRouteRes>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	String	Domain
Paths	No	String[]	List of route paths to delete; if not passed, delete all routes under the domain

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request

4. Sample Code

async function test() {
  // Delete the /api route
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    Paths: ['/api']
  })

  // Delete all routes under the domain
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com'
  })
}

test()