自定义域名

管理云开发环境的自定义域名绑定及 HTTP 访问路由规则。通过 app.env 访问。

版本提示

自 v5.0.0 起新增此能力。v5.0.0 之前请使用 HTTP 访问服务（旧）。

概念说明

概念	说明
自定义域名	绑定到云开发 HTTP 访问服务的自定义域名，支持 HTTPS 证书配置
访问路由	在某个域名下配置路径到上游服务（云函数/云托管/静态托管）的映射规则
AccessType	域名接入方式：`DIRECT`（直连）/ `CDN`（云开发 CDN）/ `CUSTOM`（自定义 CDN/WAF）
Protocol	HTTPS 协议策略：`HTTP_AND_HTTPS` / `HTTP_TO_HTTPS`（强制跳转）/ `HTTPS_TO_HTTP`
UpstreamResourceType	路由上游类型：`SCF`（云函数）/ `CBR`（云托管）/ `STATIC_STORE`（静态托管）/ `WEB_SCF`（Web 云函数）

describeHttpServiceRoute

1. 接口描述

接口功能：查询环境下的域名与访问路由列表，支持多维度过滤

接口声明：app.env.describeHttpServiceRoute(params): Promise<DescribeHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Filters	否	HTTPServiceRouteFilter[]	过滤条件，支持 `Domain`、`Path`、`DomainType`、`UpstreamResourceType`
Offset	否	Number	分页偏移量，默认 0
Limit	否	Number	分页大小，默认 20，最大 1000

3. 返回结果

字段	类型	说明
Domains	HTTPServiceDomain[]	域名路由信息列表
OriginDomain	String	HTTP 访问服务源站域名（用于自定义 CDN/WAF 回源）
TotalCount	Number	域名总数
RequestId	String	请求唯一标识

HTTPServiceDomain

字段	类型	说明
Domain	String	域名
DomainType	String	域名类型
AccessType	String	接入方式：`DIRECT` / `CDN` / `CUSTOM`
CertId	String	SSL 证书 ID
Protocol	String	协议类型
Cname	String	需配置的 CNAME 目标值
IsDefault	Boolean	是否是默认域名
Enable	Boolean	是否已开启
Status	String	状态：`PROCESSING` / `FAIL` / `SUCCESS`
DNSStatus	String	DNS 解析状态：`OK` / `INVALID`
Routes	HTTPServiceRoute[]	该域名下的路由列表
CreateTime	String	创建时间
UpdateTime	String	更新时间

4. 示例代码

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(`共 ${TotalCount} 个域名`)
  Domains.forEach(d => console.log(d.Domain, d.Status, d.DNSStatus))
}

test()

bindCustomDomain

1. 接口描述

接口功能：绑定自定义域名到 HTTP 访问服务，支持配置 HTTPS 证书和接入方式

接口声明：app.env.bindCustomDomain(params): Promise<BindCustomDomainRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	BindCustomDomainDomainParam	域名配置，见下方说明

BindCustomDomainDomainParam

字段	必填	类型	说明
Domain	是	String	域名，全局唯一
CertId	是	String	SSL 证书 ID（腾讯云 SSL 平台）
AccessType	否	String	接入方式：`DIRECT`（默认）/ `CDN` / `CUSTOM`
Protocol	否	String	协议策略：默认 `HTTP_AND_HTTPS`
Enable	否	Boolean	是否立即开启，默认 `true`
CustomCname	否	String	自定义 CDN/WAF 的回源 CNAME（`AccessType=CUSTOM` 时填写）

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

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('域名绑定成功，请前往 DNS 服务商配置 CNAME 解析')
}

test()

deleteCustomDomain

1. 接口描述

接口功能：删除自定义域名。域名下存在路由绑定时会抛出错误，需先删除路由

接口声明：app.env.deleteCustomDomain(params): Promise<DeleteCustomDomainRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	要删除的域名

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

createHttpServiceRoute

1. 接口描述

接口功能：在指定域名下创建访问路由，将路径映射到云函数、云托管或静态托管等上游服务

接口声明：app.env.createHttpServiceRoute(params): Promise<CreateHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	HTTPServiceDomainParam	域名及路由配置，见下方说明

HTTPServiceDomainParam

字段	必填	类型	说明
Domain	是	String	域名（已绑定的域名）
Routes	否	HTTPServiceRouteParam[]	路由列表，最多 20 条
AccessType	否	String	接入方式
CertId	否	String	SSL 证书 ID
Protocol	否	String	协议策略
Enable	否	Boolean	域名开启状态

HTTPServiceRouteParam（单条路由）

字段	必填	类型	说明
Path	是	String	路由路径，如 `/api`
UpstreamResourceType	否	String	上游类型：`SCF` / `CBR` / `STATIC_STORE` / `WEB_SCF` / `LH`
UpstreamResourceName	否	String	上游服务名称（云函数名/云托管服务名等）
PathRewrite	否	HTTPServicePathRewrite	路径重写配置
EnableSafeDomain	否	Boolean	是否启用安全域名，默认 `true`
EnableAuth	否	Boolean	是否启用身份认证，默认 `false`
EnablePathTransmission	否	Boolean	是否路径透传，默认 `false`
QPSPolicy	否	HTTPServiceRouteQPSPolicy	QPS 限频策略
Enable	否	Boolean	是否开启路由，默认 `true`

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  // 在已绑定的域名下创建路由：将 /api 映射到云函数 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('路由创建成功')
}

test()

modifyHttpServiceRoute

1. 接口描述

接口功能：修改指定域名下的访问路由配置

接口声明：app.env.modifyHttpServiceRoute(params): Promise<ModifyHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

与 createHttpServiceRoute 相同，参见上方说明。

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

deleteHttpServiceRoute

1. 接口描述

接口功能：删除指定域名下的访问路由。不传 Paths 时删除该域名下的全部路由

接口声明：app.env.deleteHttpServiceRoute(params): Promise<DeleteHttpServiceRouteRes>

版本提示

自 v5.0.0 起支持此接口

2. 输入参数

字段	必填	类型	说明
EnvId	是	String	环境 ID
Domain	是	String	域名
Paths	否	String[]	要删除的路由路径列表；不传则删除该域名下全部路由

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识

4. 示例代码

async function test() {
  // 删除 /api 路由
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com',
    Paths: ['/api']
  })

  // 删除域名下全部路由
  await app.env.deleteHttpServiceRoute({
    EnvId: 'your-env-id',
    Domain: 'api.example.com'
  })
}

test()

自定义域名

概念说明​

describeHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

bindCustomDomain​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

deleteCustomDomain​

1. 接口描述​

2. 输入参数​

3. 返回结果​

createHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

modifyHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

deleteHttpServiceRoute​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

概念说明

describeHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

bindCustomDomain

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

deleteCustomDomain

1. 接口描述

2. 输入参数

3. 返回结果

createHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

modifyHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

deleteHttpServiceRoute

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码