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 Gateway (Legacy).

Conceptual Overview

Concept	Description
Custom Domain	Custom domain bound to TCB HTTP Gateway, 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) / `EO` (TCB EdgeOne)
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` / `EO`
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 Gateway, supports configuring HTTPS certificates and access methods.

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

Call recommendation

It is recommended to call verifyHttpServiceRoute first to run ownership/conflict prechecks, and bind the domain only after precheck passes.

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` / `EO`
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

verifyHttpServiceRoute

1. API Description

API feature: performs read-only prechecks for domain/route configurations before create/modify. It does not create or modify any resources.

API declaration: app.env.verifyHttpServiceRoute(params): Promise<VerifyHttpServiceRouteRes>

version tip

This API has been supported since v5.8.0.

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	HTTPServiceDomainParam	Domain and route configuration. See details below.

HTTPServiceDomainParam

Field	Required	Type	Description
Domain	Yes	String	Domain (globally unique)
AccessType	No	String	Binding type: `DIRECT` / `CDN` / `CUSTOM` / `EO`
CertId	No	String	SSL platform certificate ID under the current account
Protocol	No	String	Protocol policy: `HTTP` / `HTTPS` / `HTTP_AND_HTTPS` / `HTTP_TO_HTTPS` / `HTTPS_TO_HTTP`
CustomCname	No	String	Custom CNAME, used only when `AccessType=CUSTOM`
Enable	No	Boolean	Domain enabled status; enabled by default when omitted
Routes	No	HTTPServiceRouteParam[]	Route list, up to 20 items
Extension	No	HTTPServiceExtension	Domain extension configuration

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` / `STORAGE` (required for create, optional for modify)
UpstreamResourceName	No	String	Upstream service name (required for create, optional for modify; can be omitted for `STATIC_STORE` / `STORAGE`)
PathRewrite	No	HTTPServicePathRewrite	Path rewrite configuration
EnableSafeDomain	No	Boolean	Whether to enable 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
Extension	No	HTTPServiceExtension	Route extension configuration (including headers handling)
Enable	No	Boolean	Whether to enable route

HTTPServicePathRewrite

Field	Required	Type	Description
Prefix	No	String	Path prefix rewrite. Mutually exclusive with `StaticStorePrefix`.
StaticStorePrefix	No	String	Static hosting path prefix rewrite. Mutually exclusive with `Prefix`.

HTTPServiceRouteQPSPolicy

Field	Required	Type	Description
QPSTotal	No	Number	Global QPS value (requests per second).
QPSPerClient	No	HTTPServiceQPSPerClient	Per-client rate limiting configuration.

HTTPServiceQPSPerClient

Field	Required	Type	Description
LimitBy	No	String	Client dimension: `UserID` / `ClientIP`.
LimitValue	No	Number	Per-client QPS limit value (requests per second).

HTTPServiceExtension

Field	Required	Type	Description
HeadersHandler	No	HTTPServiceHeadersHandler	Headers handling configuration.

HTTPServiceHeadersHandler

Field	Required	Type	Description
RequestHeadersToAdd	No	HTTPServiceHeaderToAdd[]	List of request headers to add.
RequestHeadersToRemove	No	String[]	List of request header keys to remove.
ResponseHeadersToAdd	No	HTTPServiceHeaderToAdd[]	List of response headers to add.
ResponseHeadersToRemove	No	String[]	List of response header keys to remove.

HTTPServiceHeaderToAdd

Field	Required	Type	Description
Key	No	String	Header key to add.
Value	No	String	Header value to add.
Action	No	String	Add behavior: `APPEND_IF_EXISTS_OR_ADD` / `ADD_IF_ABSENT` / `OVERWRITE_IF_EXISTS_OR_ADD` / `OVERWRITE_IF_EXISTS`.

3. Return Results

Field	Type	Description
Passed	Boolean	`true` when all enabled checks pass
Ownership	VerifyHttpServiceRouteCheckItem	Domain ownership check result
Cert	VerifyHttpServiceRouteCheckItem	Certificate check result
Quota	VerifyHttpServiceRouteCheckItem	Domain/path quota check result
RouteConflict	VerifyHttpServiceRouteCheckItem	Route conflict check result under the same domain
DomainConflict	VerifyHttpServiceRouteCheckItem	Domain occupancy conflict check result
InternalAccount	VerifyHttpServiceRouteCheckItem	Internal-domain/account check result
Blacklist	VerifyHttpServiceRouteCheckItem	Domain blacklist check result
CDNResource	VerifyHttpServiceRouteCheckItem	CDN resource check result
EO	VerifyHttpServiceRouteCheckItem	EdgeOne precheck result
RequestId	String	Unique identifier of the request

VerifyHttpServiceRouteCheckItem structure:

Field	Type	Description
Status	String	Check status: `PASS` / `SKIPPED` / `FAIL`
Code	String	Failure code, returned only when `FAIL`
Message	String	Detail message or skip reason
OwnershipVerification	Object	Ownership verification guidance (e.g. DNS record/file verification info)

4. Sample Code

It is recommended to call verifyHttpServiceRoute before creating or updating routes. If Passed=true, proceed with domain binding and route creation.

async function test() {
  const verifyRes = await app.env.verifyHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: {
      Domain: 'api.example.com',
      CertId: 'your-cert-id'
    }
  })

  if (!verifyRes.Passed) {
    console.log('Precheck failed. Complete ownership verification or resolve conflicts, then retry.')
    console.log(verifyRes.Ownership, verifyRes.RouteConflict, verifyRes.DomainConflict)
    return
  }

  console.log('Precheck passed. You can continue with bindCustomDomain / createHttpServiceRoute.')
}

test()

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>

Call recommendation

It is recommended to call verifyHttpServiceRoute first and create routes only after Passed=true.

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 (globally unique)
AccessType	No	String	Binding type: `DIRECT` / `CDN` / `CUSTOM` / `EO`
CertId	No	String	SSL platform certificate ID under the current account
Protocol	No	String	Protocol policy: `HTTP` / `HTTPS` / `HTTP_AND_HTTPS` / `HTTP_TO_HTTPS` / `HTTPS_TO_HTTP`
CustomCname	No	String	Custom CNAME, used only when `AccessType=CUSTOM`
Enable	No	Boolean	Domain enabled status; enabled by default when omitted
Routes	No	HTTPServiceRouteParam[]	Route list, up to 20 items
Extension	No	HTTPServiceExtension	Domain extension configuration

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` / `STORAGE` (required for create, optional for modify)
UpstreamResourceName	No	String	Upstream service name (required for create, optional for modify; can be omitted for `STATIC_STORE` / `STORAGE`)
PathRewrite	No	HTTPServicePathRewrite	Path rewrite configuration
EnableSafeDomain	No	Boolean	Whether to enable 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
Extension	No	HTTPServiceExtension	Route extension configuration (including headers handling)
Enable	No	Boolean	Whether to enable route

The semantics of PathRewrite / EnableAuth / EnablePathTransmission / QPSPolicy align with the CLI gateway configuration. See Configuration File - Gateway for the authoritative definitions. The Manager SDK uses PascalCase (e.g. EnableAuth), corresponding one-to-one with the camelCase (enableAuth) in cloudbaserc.json.

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()

purgeHttpServiceCache

1. API Description

API feature: Purge the cache of an HTTP service domain, supporting both CDN and EdgeOne (EO) cache types. After purging, a task ID is generated and can be used to query the task progress and details via describeHttpServiceCachePurgeTask.

API declaration: app.env.purgeHttpServiceCache(params): Promise<PurgeHttpServiceCacheRes>

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	String	HTTP service domain
CacheType	Yes	String	Cache type: `CDN` (TCB CDN) / `EO` (EdgeOne)
PurgeType	Yes	String	Purge granularity: `PURGE_URL` (URL, with protocol) / `PURGE_PREFIX` (directory, EO only) / `PURGE_HOST` (domain, EO only). CDN only supports `PURGE_URL`
Targets	Yes	String[]	List of purge targets, semantics vary with `PurgeType`

3. Return Results

Field	Type	Description
CacheType	String	Cache type: `CDN` / `EO`
TaskId	String	Purge task ID, can be used to query progress via `describeHttpServiceCachePurgeTask`
RequestId	String	Unique identifier of the request

4. Sample Code

async function test() {
  // Purge the URL cache of a CDN domain
  const { TaskId } = await app.env.purgeHttpServiceCache({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    CacheType: 'CDN',
    PurgeType: 'PURGE_URL',
    Targets: ['https://api.example.com/index.html']
  })
  console.log(`Purge task submitted: ${TaskId}`)

  // Purge the directory cache of an EO domain (PURGE_PREFIX is EO-only)
  await app.env.purgeHttpServiceCache({
    EnvId: 'your-env-id',
    Domain: 'static.example.com',
    CacheType: 'EO',
    PurgeType: 'PURGE_PREFIX',
    Targets: ['https://static.example.com/assets/']
  })
}

test()

describeHttpServiceCachePurgeTask

1. API Description

API feature: Query the details of HTTP service domain cache purge tasks. Pass a task ID to query the status, time, cache type, and other details of a single task, or omit it to query historical task records.

API declaration: app.env.describeHttpServiceCachePurgeTask(params): Promise<DescribeHttpServiceCachePurgeTaskRes>

2. Input Parameters

Field	Required	Type	Description
EnvId	Yes	String	Environment ID
Domain	Yes	String	HTTP service domain
CacheType	Yes	String	Cache type: `CDN` / `EO`
TaskId	No	String	Task ID returned by `purgeHttpServiceCache`; when omitted, query historical task records
PurgeType	No	String	Filter by purge granularity: `PURGE_URL` / `PURGE_PREFIX` / `PURGE_HOST`
StartTime	No	String	Query start time, ISO8601 format. Defaults to 7 days ago when `TaskId` is empty
EndTime	No	String	Query end time, ISO8601 format. Defaults to now when `TaskId` is empty
Offset	No	Number	Pagination offset, default 0
Limit	No	Number	Page size, default 20, maximum 1000

3. Return Results

Field	Type	Description
Tasks	HTTPServiceCachePurgeTask[]	Task list
TotalCount	Number	Total number of tasks, used to determine whether all data has been fetched
RequestId	String	Unique identifier of the request

HTTPServiceCachePurgeTask

Field	Type	Description
TaskId	String	Task ID
CacheType	String	Cache type: `CDN` / `EO`
Status	String	Task status: `PROCESSING` / `SUCCESS` / `FAILED` / `TIMEOUT` / `CANCELED`
PurgeType	String	Purge type: `PURGE_URL` / `PURGE_PREFIX` / `PURGE_HOST`
Method	String	Purge method: `INVALIDATE` (only refresh updated resources) / `DELETE` (refresh all node resources)
Targets	String[]	List of purge targets
FailReason	String	Failure reason, returned when the task fails
CreateTime	String	Task creation time, ISO8601 format (UTC+0)
UpdateTime	String	Task update time, ISO8601 format (UTC+0)

4. Sample Code

async function test() {
  // Query the progress of a single task
  const { Tasks } = await app.env.describeHttpServiceCachePurgeTask({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    CacheType: 'CDN',
    TaskId: 'your-task-id'
  })
  const task = Tasks[0]
  console.log(`Task status: ${task.Status}, fail reason: ${task.FailReason || '-'}`)

  // Query the directory purge history of an EO domain
  const history = await app.env.describeHttpServiceCachePurgeTask({
    EnvId: 'your-env-id',
    Domain: 'static.example.com',
    CacheType: 'EO',
    PurgeType: 'PURGE_PREFIX',
    Limit: 20
  })
  console.log(`Total ${history.TotalCount} history records`)
}

test()

Conceptual Overview​

describeHttpServiceRoute​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

bindCustomDomain​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

deleteCustomDomain​

1. API Description​

2. Input Parameters​

3. Return Results​

verifyHttpServiceRoute​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

createHttpServiceRoute​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

modifyHttpServiceRoute​

1. API Description​

2. Input Parameters​

3. Return Results​

deleteHttpServiceRoute​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

purgeHttpServiceCache​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

describeHttpServiceCachePurgeTask​

1. API Description​

2. Input Parameters​

3. Return Results​

4. Sample Code​

Conceptual Overview

describeHttpServiceRoute

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

bindCustomDomain

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

deleteCustomDomain

1. API Description

2. Input Parameters

3. Return Results

verifyHttpServiceRoute

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

createHttpServiceRoute

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

modifyHttpServiceRoute

1. API Description

2. Input Parameters

3. Return Results

deleteHttpServiceRoute

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

purgeHttpServiceCache

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code

describeHttpServiceCachePurgeTask

1. API Description

2. Input Parameters

3. Return Results

4. Sample Code