文档中心

使用 HTTP 请求调用

最近更新时间：2022.11.02 20:46:32

首次发布时间：2022.07.28 22:07:06

您可以使用 HTTP 请求来调用火山引擎云服务的 API 接口。在请求中添加请求参数，向 API 接口的服务地址发送 HTTP 请求。系统根据请求的内容，返回结果数据。

在使用 HTTP 请求前，需要了解以下内容：

请求结构。
公共参数。
签名机制。

请求结构

API 请求的结构涵盖以下内容：

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

服务地址

多云CDN服务的服务地址是open.volcengineapi.com。

通信协议

使用HTTP或HTTPS协议发送请求。推荐使用安全性更高的HTTPS协议发送请求。

请求方法

如无特殊说明，默认使用 POST 方法。POST 请求中，必须指定 Content-Type 字段值为 application/json。

说明

GET 请求和 POST 请求都可以在 request header 和 query string 中包含公共 URI 参数。
POST 请求可以额外在请求正文中包含 API 特定参数。

请求参数

关于请求参数的信息，参见公共参数。

公共参数

公共参数是每个 API 请求必须包含的参数。如果 API 请求中缺少公共参数。请求会失败。公共参数分为 URI 参数和签名参数。

URI 参数

URI 参数必须包含在 query string 中。

名称	类型	是否必选	说明	示例
Action	string	是	表示 API 名称。格式为 `[a-zA-Z]+`。	`DescribeContentQuota`
Version	string	是	表示 API 版本。格式为 `YYYY-MM-DD`。	`2022-03-01`

签名参数

每个 API 请求必须包含签名参数。签名参数可以包含在 query string 中作为 URI 参数，也可以包含在 request headers 中。

在 request headers 中包含签名参数

如果在 request headers 中包含签名参数，必须包含以下参数。

名称	类型	是否必填	描述	示例
X-Date	string	是	表示签名的 UTC 时间，精确到秒。	`20201103T104027Z`
Authorization	string	是	表示签名值。	参见 Authorization。

Authorization

Authorization 的伪代码结构如下：

HMAC-SHA256 Credential = {AccessKey}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}

{}内字段的信息如下。

名称	类型	描述	示例
AccessKey	string	火山引擎账号的 AccessKey ID，可以从秘钥管理页面获取。	`AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE`
ShortDate	string	请求的时间，使用 UTC 时间，精确到日。	`20210913`
Region	string	请求的 Region。	`cn-north-1`
Service	string	请求的服务名称。	`MCDN`
SignedHeaders	string	参与签名的 request headers。Request headers 之间以分号分隔。	`host;x-content-sha256;x-date`
Signature	string	计算后的签名。	关于更多签名的信息，参见签名机制。

在 query string 中包含签名参数

如果在 query string 中包含签名参数，必须包含以下参数。

名称	类型	是否必填	描述	示例
X-Date	string	是	签名的 UTC 时间，精确到秒。	`20210913T081805Z`
X-Algorithm	string	是	签名算法。该参数是一个固定值。	`HMAC-SHA256`
X-Credential	string	是	参见下面的说明。	参见下面的说明。
X-SignedHeaders	string	是	参与签名的 request headers。Request headers 之间以分号分隔。	`host;x-content-sha256;x-date`
X-Signature	string	是	计算后的签名。	关于更多签名的信息，参见签名机制。

X-Credential 的伪代码结构

{AccessKey}/{ShortDate}/{Region}/{Service}/request

签名机制

如果您使用火山引擎 API 来调用云服务的功能，必须在 API 请求头中包含签名参数。签名参数中需要包含 Signature 签名。文档最后提供了示例代码。

Signature 签名是基于秘钥（kSigning）和签名字符串（StringToSign）计算出来的。计算逻辑的伪代码如下：

// kSigning：秘钥
// StringToSign：签名字符串
// HMAC：指代 HMAC-SHA256
Signature = HexEncode(HMAC(kSigning, StringToSign))

kSigning

kSigning 表示用来计算签名的秘钥。要获取 kSigning，必须先从秘钥管理页面获取 AccessKey Secret。然后使用以下代码生成 kSigning。

kSecret = *Your Access Key Secret*
kDate = HMAC(kSecret, Date)
kRegion = HMAC(kDate, Region)
kService = HMAC(kRegion, Service)
kSigning = HMAC(kService, "request")

StringToSign

StringToSign 表示用来计算签名的签名字符串，包含规范请求的元数据信息。StringToSign 是通过连接以下值生成的：

签名算法。
请求日期。
凭证范围。
规范请求的哈希值。

StringToSign 的伪代码如下：

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

StringToSign 伪代码中的参数含义如下：

Algorithm
Algorithm 表示签名算法，是一个固定值的字符串。取值为 HMAC-SHA256。

RequestDate
RequestDate 表示请求日期，与公共参数 x-date 相同。示例值是20210913T081805Z。

CredentialScope
CredentialScope 表示凭证范围。格式如下：

YYYYMMDD/region/service/request

CanonicalRequest

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

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

CanonicalRequest 伪代码中参数的含义如下：

HTTPRequestMethod 表示请求方法。该参数的取值是 GET 或 POST。
CanonicalURI 表示请求路径。
CanonicalQueryString 表示规范的 query string。CanonicalQueryString 的值是通过以下规则生成的：
- 对所有参数名，在字符级别按升序排序。
CanonicalHeaders 表示规范的 headers。CanonicalHeaders 是通过以下步骤生成的：
1. 将参与签名计算的 headers 的 keys 转化成小写字母。
2. 在字符级别对 keys 进行升序排序。
3. 以 key-value 的格式拼接所有的 headers。
4. 对每个 header 添加换行符（\n）。
SignedHeaders 表示 headers 中 key 的列表。这些 keys 是在字符级别升序排序的。
HexEncode(Hash(RequestPayload)) 表示一个计算值。该计算值是通过对请求体中 payload 的内容应用 SHA256 哈希算法计算得到的。

签名机制的示例代码

在示例代码中，我们调用 requestMCDN 函数进行加密和发起请求，并输出请求的结果。这里我们以调用 DescribeContentQuota API 为例，获取在多云CDN服务中某个账号 ID 的刷新与预热任务的配额。