帮你快速理解、总结文档立即下载

域名

最近更新时间:2026-11-13 16:16:03
我的收藏
本章介绍 makers.domains 上的自定义域名方法:项目绑定、查询和解绑自定义域名,校验域名归属,检查 CNAME 指向以及配置 HTTPS 证书。域名归属校验、CNAME 检查与 HTTPS 证书方法只能通过腾讯云 API 密钥调用。
方法
用途
API Token
腾讯云 API 密钥
domains.create
为项目绑定自定义域名
✓
✓
domains.list
查询项目的域名列表
✓
✓
domains.delete
解绑自定义域名
✓
✓
domains.verifyOwnership / domains.verify_ownership
校验域名归属
✕
✓
domains.checkCname / domains.check_cname
检查域名的 CNAME 指向
✕
✓
domains.applyFreeCertificate / domains.apply_free_certificate
申请免费证书
✕
✓
domains.checkFreeCertificate / domains.check_free_certificate
查询免费证书申请结果
✕
✓
domains.listHostCertificates / domains.list_host_certificates
查询域名的证书配置
✕
✓
domains.modifyCertificate / domains.modify_certificate
配置域名证书
✕
✓
如果是子账号,使用云 API 调用后六个方法还需要对应 Action 的 CAM 权限:teo:VerifyOwnership、teo:CheckCnameStatus、teo:ApplyFreeCertificate、teo:CheckFreeCertificateVerification、teo:DescribeHostCertificates 与 teo:ModifyHostsCertificate。

数据模型

domains.list 返回域名对象的数组,包含默认域名与自定义域名。后端未返回的字段值为空(TypeScript 为 null,Python 为 None)。
字段
类型
说明
type
string | null/str | None
Preset 为平台默认域名,Custom 为自定义域名
domain
string | null/str | None
域名
status
string | null/str | None
域名状态,按后端原值返回。刚绑定时为 init,生效后为 online
cname
string | null/str | None
EdgeOne 分配的目标 CNAME。配置 DNS 时将域名的 CNAME 记录指向该值。归属校验通过后由异步任务写入,写入前为空
currentCname/current_cname
string | null/str | None
域名当前的公网 CNAME 解析结果,不能作为 DNS 配置目标
mainDomain/main_domain
string | null/str | None
主域名
area
string | null/str | None
加速区域:mainland、overseas 或 global
zoneId/zone_id
string | null/str | None
域名所属项目的 Makers 站点 ID,可传给 CNAME 与证书方法
forceRedirectHttps/force_redirect_https
string | null/str | None
是否强制跳转 HTTPS:on 或 off
redirectStatusCode/redirect_status_code
number | null/int | None
强制跳转的状态码:301 或 302
ownershipVerification/ownership_verification
对象或空,见下表
归属校验信息。不需要归属校验时为空
ownershipVerification / ownership_verification 的字段:
字段
说明
dnsVerification/dns_verification
DNS 校验,含 recordType/record_type、subdomain 与 recordValue/record_value。按这三个字段添加 TXT 记录
fileVerification/file_verification
文件校验,含 path 与 content。在域名下的 path 提供内容为 content 的文件
nsVerification/ns_verification
始终为空

domains.create

为项目绑定自定义域名。绑定后域名状态为 init,cname 为空。
前置条件:
项目的生产环境已有成功的部署。
项目加速区域为 mainland 或 global 时,域名已完成 ICP 备案。
域名解绑后约 5 分钟内处于释放期,期间无法重新绑定。
不满足时抛出 MakersError,code 为 FailedOperation,原因见错误信息。
参数
参数
类型
必填
说明
projectId/project_id
string/str
是
项目 ID
domain
string/str
是
自定义域名
返回值
Promise<CreatedCustomDomain>/dict —— 只包含 domain 与 id。域名状态、cname 与归属校验信息需通过 domains.list 查询。
示例
Typescript
Python
const { domain, id } = await makers.domains.create({
projectId: "your-project-id",
domain: "www.example.com",
});
created = makers.domains.create(
project_id="your-project-id",
domain="www.example.com",
)
print(created["domain"], created["id"])

domains.list

查询项目的域名列表,包含平台默认域名。传入 domain 时只返回该域名。
参数
参数
类型
必填
说明
projectId/project_id
string/str
是
项目 ID
domain
string/str
否
只返回该域名
返回值
Promise<CustomDomain[]>/list[dict]
示例
Typescript
Python
const [row] = await makers.domains.list({
projectId: "your-project-id",
domain: "www.example.com",
});
console.log(row?.status, row?.cname);
console.log(row?.ownershipVerification?.dnsVerification);
rows = makers.domains.list(
project_id="your-project-id",
domain="www.example.com",
)
if rows:
print(rows[0]["status"], rows[0]["cname"])
print((rows[0]["ownership_verification"] or {}).get("dns_verification"))

domains.delete

解绑一个或多个自定义域名。域名未绑定到该项目时抛出 MakersError。解绑后约 5 分钟内无法重新绑定同一域名。
参数
参数
类型
必填
说明
projectId/project_id
string/str
是
项目 ID
domains
string[]/list[str]
是
待解绑的域名,至少一个
返回值
Promise<void>/None
示例
Typescript
Python
await makers.domains.delete({
projectId: "your-project-id",
domains: ["www.example.com"],
});
makers.domains.delete(
project_id="your-project-id",
domains=["www.example.com"],
)

domains.verifyOwnership / domains.verify_ownership

校验域名归属。归属校验通过后,EdgeOne 才会开始为域名分配 cname。
校验未通过时返回 status 为 fail,不抛出异常。域名从未申请过归属校验时,抛出 MakersError,code 为 OperationDenied.DomainOwnershipHasNotApplied。
参数
参数
类型
必填
说明
domain
string/str
是
待校验的域名
返回值
Promise<DomainOwnership>/dict —— 包含 status 与 message。status 为 success 或 fail。message 为校验失败的原因,成功时可能为空字符串。
示例
Typescript
Python
const { status, message } = await makers.domains.verifyOwnership({
domain: "www.example.com",
});
if (status === "fail") {
console.error(message);
}
result = makers.domains.verify_ownership(domain="www.example.com")
if result["status"] == "fail":
print(result["message"])

domains.checkCname / domains.check_cname

检查域名的 CNAME 是否已指向 EdgeOne 分配的 cname。
参数
参数
类型
必填
说明
zoneId/zone_id
string/str
否
Makers 站点 ID,默认为初始化时的 zoneId / zone_id
recordNames/record_names
string[]/list[str]
是
待检查的域名,至少一个
返回值
Promise<CnameCheck>/dict —— 只包含 cnameStatus/cname_status。每一项包含 recordName/record_name、cname 与 status。status 按后端原值返回:
status
含义
active
已指向 EdgeOne 分配的 CNAME
moved
未指向 EdgeOne 分配的 CNAME
invalid
指向了其他域名的 CNAME,需改为 domains.list 返回的 cname
示例
Typescript
Python
const { cnameStatus } = await makers.domains.checkCname({
recordNames: ["www.example.com"],
});
for (const { recordName, status } of cnameStatus) {
console.log(recordName, status);
}
result = makers.domains.check_cname(record_names=["www.example.com"])
for item in result["cname_status"]:
print(item["record_name"], item["status"])

domains.applyFreeCertificate / domains.apply_free_certificate

为域名申请免费证书,返回需要发布的 DNS 记录或验证文件。同一域名只能申请一本免费证书,换一种 verificationMethod 再次调用即可切换验证方式。
注意:
cname 写入前调用本方法或 modifyCertificate,会导致 cname 丢失且无法补写:域名状态仍可能变为 online,但 cname 始终为空。

参数
参数
类型
必填
说明
zoneId/zone_id
string/str
否
Makers 工作空间 ID,默认为初始化时的 zoneId / zone_id
domain
string/str
是
域名
verificationMethod/verification_method
"dns_challenge" | "http_challenge"
是
验证方式。dns_challenge 为 DNS 委派验证,http_challenge 为文件验证。其他取值在发请求前抛出 ValidationError
返回值
Promise<FreeCertificateApplication>/dict —— 包含 dnsVerification 与 fileVerification,未返回的一项为空。dnsVerification 含 recordType、subdomain 与 recordValue,DNS 委派验证通常返回一条 CNAME 记录。
示例
Typescript
Python
const { dnsVerification } = await makers.domains.applyFreeCertificate({
domain: "www.example.com",
verificationMethod: "dns_challenge",
});
if (dnsVerification) {
const { recordType, subdomain, recordValue } = dnsVerification;
console.log(`add ${recordType} ${subdomain} -> ${recordValue}`);
}
result = makers.domains.apply_free_certificate(
domain="www.example.com",
verification_method="dns_challenge",
)
dns = result["dns_verification"]
if dns:
print(f"add {dns['record_type']} {dns['subdomain']} -> {dns['record_value']}")

domains.checkFreeCertificate / domains.check_free_certificate

查询免费证书的申请结果。
参数
参数
类型
必填
说明
zoneId/zone_id
string/str
否
Makers 工作空间 ID,默认为初始化时的 zoneId / zone_id
domain
string/str
是
域名
返回值
Promise<FreeCertificate>/dict —— 包含 commonName、signatureAlgorithm与 expireTime。
示例
Typescript
Python
import { MakersError } from "@edgeone/makers-sdk";

try {
const { commonName, expireTime } = await makers.domains.checkFreeCertificate({
domain: "www.example.com",
});
console.log(commonName, expireTime);
} catch (error) {
if (!(error instanceof MakersError)) throw error;
console.log("not issued yet:", error.code);
}
result = makers.domains.apply_free_certificate(
domain="www.example.com",
verification_method="dns_challenge",
)
dns = result["dns_verification"]
if dns:
print(f"add {dns['record_type']} {dns['subdomain']} -> {dns['record_value']}")

domains.listHostCertificates / domains.list_host_certificates

查询域名的证书配置。SDK 自动翻页并返回全部结果,不接受分页参数。参数对象可以省略。
参数
参数
类型
必填
说明
zoneId/zone_id
string/str
否
Makers 工作空间 ID,默认为初始化时的 zoneId / zone_id
filters
{ name, values, fuzzy? }[]/list[dict]
否
过滤条件。按域名过滤时 name 为 host。fuzzy 为 true 时模糊匹配,默认精确匹配
返回值
Promise<HostCertificateList>/dict —— 包含 certificates 与 totalCount。每个证书包含:
字段
说明
host
域名
mode
证书模式,按后端原值返回,例如 eofreecert(免费证书)、disable(未配置证书)
hostCertInfo/host_cert_info
已配置的证书列表,每项包含 certId/cert_id、alias、type、status、signAlgo/sign_algo、deployTime/deploy_time 与 expireTime/expire_time。status 为 deployed 表示已部署
示例
Typescript
Python
const { certificates } = await makers.domains.listHostCertificates({
filters: [{ name: "host", values: ["www.example.com"] }],
});
for (const { host, mode, hostCertInfo } of certificates) {
console.log(host, mode, hostCertInfo.map((cert) => cert.status));
}
result = makers.domains.list_host_certificates(
filters=[{"name": "host", "values": ["www.example.com"]}],
)
for cert in result["certificates"]:
print(cert["host"], cert["mode"], [info["status"] for info in cert["host_cert_info"]])

domains.modifyCertificate / domains.modify_certificate

为一个或多个域名配置证书。前置条件与注意事项同 applyFreeCertificate:domains.list 返回的 cname 不为空后才能调用。不支持上传自有证书。
参数
参数
类型
必填
说明
zoneId/zone_id
string/str
否
Makers 工作空间 ID,默认为初始化时的 zoneId / zone_id
hosts
string[]/list[str]
是
域名,至少一个
mode
"eofreecert" | "eofreecert_manual" | "disable"
是
证书模式,见下表。其他取值在发请求前抛出 ValidationError
mode
说明
eofreecert
申请免费证书并部署。域名 CNAME 已指向 EdgeOne 时自动完成验证
eofreecert_manual
部署通过 applyFreeCertificate 申请并已签发的免费证书。尚未签发时抛出 ValidationError,code 为 InvalidParameter.CertificateNotApplied
disable
关闭证书,域名立即停止 HTTPS 服务