本章介绍
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 查询。示例
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]示例
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示例
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 为校验失败的原因,成功时可能为空字符串。示例
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 |
示例
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 记录。示例
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。示例
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 表示已部署 |
示例
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 服务 |