文档中心

发送 API 请求

最近更新时间：2023.06.25 18:12:15

首次发布时间：2022.12.21 20:29:40

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

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

请求结构。
公共参数。
请求鉴权。
签名计算方式。

请求结构

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

API 服务地址。
通讯协议。
请求方法。
请求参数。

API 服务地址

域名服务的 API 服务地址是 open.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

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-north-1/domain_openapi/request`
X-SignedHeaders	string	该参数的说明与伪代码参数说明中的 `SignedHeaders` 参数是相同的。	`host;x-content-sha256;x-date`
X-Signature	string	表示一个经过计算得到的签名。关于签名的计算方式，参见签名计算方式。

签名计算方式

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

本章节的伪代码中的 HMAC 方法使用的是 HMAC-SHA256 算法。
本章节的伪代码中的 HexEncode 方法将字符串转换为十六进制编码格式的字符串。

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

Signature = HexEncode(HMAC(kSigning, StringToSign))

kSigning

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

kSecret = <Your Access Key Secret>
kDate = HMAC(kSecret, ShortDate)
kRegion = HMAC(kDate, Region)
kService = HMAC(kRegion, Service)
kSigning = HMAC(kService, "request")

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

StringToSign

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

// Hash 函数使用 SHA256 算法
StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

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

CredentialScope

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

{ShortDate}/{Region}/{Service}/{Request}

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

CanonicalRequest

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

HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))

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-north-1`。	`cn-north-1`
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`

请求示例

POST https://open.volcengineapi.com?Version=2022-12-12&Action=RegisterDomain

// Request Headers
X-Date: 20230116T073702Z
Authorization: HMAC-SHA256 Credential=AKLTMjYxYTZmYWU4ZWYzNGI2NDg8NTUxODE1ZGVhNmIxZmQ/20230116/cn-north-1/domain_openapi/request, SignedHeaders=x-content-sha256;x-date, Signature=5a394ce80456c7cdf989c28bd638807c8ead386eb15dd36e39952f405380aef2
Content-Type: application/json

//Request Body
{
    "domain":"test.com",
    "template_tag": "G0zM6RUUWLPysIuVPF7obA=="
}