您通过发送 API 请求来调用火山引擎域名服务的 API。

在发送 API 请求前，您需要理解以下内容：

请求结构。

公共参数。

请求鉴权。

签名计算方式。

请求结构

API 请求的结构包含以下内容：

API 服务地址。

通讯协议。

请求方法。

请求参数。

API 服务地址

域名服务的 API 服务地址是domain-service.volcengineapi.com。

通讯协议

您可以使用 HTTP 协议或 HTTPS 协议发送请求。推荐您使用 HTTPS 协议，其安全性更高。

请求方法

关于 API 请求所使用的方法，参见每个 API 的说明。对于 POST 请求，您必须指定 Content-Type 的字段值为 application/json。

请求参数

请求参数包括公共参数和每个 API 所特有的参数。

公共参数

公共参数是每个 API 请求必须包含的参数。如果一个 API 请求缺失公共参数，请求会失败。以下表格中的公共参数必须包含在查询字符串（query string）中。

参数名称	数据类型	必选	参数说明	示例
Action	string	是	表示 API 名称。名称格式为 [a-zA-Z]+。	RegisterDomain
Version	string	是	表示 API 版本。该参数的取值是 2022-12-12。	2022-12-12
X-Expires	int	否	表示签名的有效时间，单位是秒。该参数的默认值是 900。	900

请求鉴权

每个请求中必须包含鉴权信息。该鉴权信息用以验证请求者的身份。您可以使用以下任一方法提供鉴权信息。推荐您使用方法一。

（推荐）方法一：在请求头中包含鉴权信息

您需要在请求头中包含以下参数：

参数名称	数据类型	必选	参数说明	示例
X-Date	string	是	表示签名计算的时间，以 UTC 表示。时间精度是秒。关于该参数，您需要留意以下内容：在请求到达时，域名服务会计算请求到达时间与 X-Date 之间的差距。如果差距超过 X-Expires 指定的时间范围，域名服务判定该请求无效。因此，在计算签名前，建议您校准系统时间。	20210913T081805Z
Authorization	string	是	该参数表示鉴权字符串。该参数的伪代码如下： HMAC-SHA256 Credential = {AccessKey}/{ShortDate}/{Region}/{Service}/{Request}, SignedHeaders={SignedHeaders}, Signature={Signature} 该伪代码的说明如下：伪代码中的 Signature 参数表示一个经过计算得到的签名。关于签名的计算方式，参见签名计算方式。关于伪代码中其他参数的说明，参见伪代码中参数的说明。

方法二：在查询字符串中包含鉴权信息

您需要在查询字符串中包含以下查询参数。

参数名称	数据类型	参数说明	示例
X-Date	string	表示签名计算的时间，以 UTC 表示。时间精度是秒。关于该参数，您需要留意以下内容：在请求到达时，域名服务会计算请求到达时间与 X-Date 之间的差距。如果差距超过 X-Expires 指定的时间范围，域名服务判定该请求无效。因此，在计算签名前，建议您校准系统时间。	20210913T081805Z
X-Algorithm	string	表示签名计算所使用的算法。该参数的值是 HMAC-SHA256。	HMAC-SHA256
X-Credential	string	该参数值的伪代码如下： {AccessKey}/{ShortDate}/{Region}/{Service}/{Request} 关于 X-Credential伪代码中参数的说明，参见伪代码中参数的说明。	AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE/20210913/cn-beijing/domain_openapi/request
X-SignedHeaders	string	该参数的说明与伪代码参数说明中的 SignedHeaders 参数是相同的。	host;x-content-sha256;x-date
X-Signature	string	表示一个经过计算得到的签名。关于签名的计算方式，参见签名计算方式。

签名计算方式

本章节主要介绍签名是如何计算的。

本章节的伪代码中的 HMAC 方法使用的是 HMAC-SHA256 算法。

本章节的伪代码中的 HexEncode 方法将字符串转换为十六进制编码格式的字符串。

签名参数 Signature 是基于 kSigning 和 StringToSign 参数计算而来的。Signature 的伪代码如下：

kSigning

kSigning 表示用来计算签名的密钥。要计算 kSigning，您必须先获取您账号的 Access Key Secret，然后使用以下伪代码生成 kSigning。

关于 kSigning 伪代码中参数的说明，参见伪代码中参数的说明。

StringToSign

StringToSign 表示用来计算签名的签名字符串。StringToSign 的伪代码如下：

关于 StringToSign 伪代码中 Algorithm 和 RequestDate 参数的说明，参见伪代码中参数的说明。StringToSign 伪代码中其他参数的说明如下。

CredentialScope

CredentialScope 表示凭证范围。CredentialScope 的伪代码如下：

关于 CredentialScope 伪代码中参数的说明，参见伪代码中参数的说明。

CanonicalRequest

CanonicalRequest 表示规范的请求。CanonicalRequest 的伪代码如下：

CanonicalRequest 伪代码中参数的说明如下：

HTTPRequestMethod：表示请求方法。该参数的取值是 GET 或 POST。

CanonicalURI：表示请求的 URI。

CanonicalQueryString：表示规范的查询字符串。CanonicalQueryString 的值是通过以下规则生成的：

按参数名称对查询参数进行升序排序。

CanonicalHeaders：表示规范的请求头。CanonicalHeaders 是通过以下步骤生成的：

将参与签名计算的请求头参数的名称转化成小写字母。

在字符级别对这些名称进行升序排序。

以 key-value 的格式拼接这些请求头参数。key 是请求头参数的名称，value 是请求头参数的值。

在每个请求头参数后添加换行符（\n）。

SignedHeaders：参见伪代码中参数的说明。

HexEncode(Hash(RequestPayload))：表示一个计算值。该值是通过对请求正文中 payload 的值应用 SHA256 哈希算法计算得到的。

伪代码中参数的说明

以下表格包含了本文中多个伪代码中参数的说明。

参数名称	数据类型	参数说明	示例
AccessKey	string	表示您账号的 Access Key ID。参考获取 Access Key。	AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE
RequestDate	string	该参数与请求鉴权章节中 X-Date 的定义相同。	20210913T081805Z
ShortDate	string	该参数与 RequestDate 的定义相同，只不过时间精度是日。	20210913
Region	string	表示域名服务所在的地域。该参数的取值是 cn-beijing。	cn-beijing
Service	string	表示域名服务的服务名称。该参数的取值是 domain_openapi。	domain_openapi
SignedHeaders	string	表示参与签名计算的请求头参数。多个请求头参数使用分号（;）分隔。这些请求头参数是根据参数名称升序排序的。一般来说，SignedHeaders 的值是 host;x-content-sha256;x-date。您也可以指定任意请求头参数作为 SignedHeaders 的值。	host;x-content-sha256;x-date
Algorithm	string	表示签名计算所使用的算法。该参数的取值为 HMAC-SHA256。	HMAC-SHA256
Request	string	该参数是一个常量，值是 request。	request

请求示例