You need to enable JavaScript to run this app.
导航
使用 HTTP 请求调用
最近更新时间:2022.11.02 20:46:32首次发布时间:2022.07.28 22:07:06

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

在使用 HTTP 请求前,需要了解以下内容:

请求结构

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

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

服务地址

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

通信协议

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

请求方法

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

说明

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

请求参数

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

公共参数

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

URI 参数

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

名称类型是否必选说明示例
Actionstring表示 API 名称。格式为 [a-zA-Z]+DescribeContentQuota
Versionstring表示 API 版本。格式为 YYYY-MM-DD2022-03-01

签名参数

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

在 request headers 中包含签名参数

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

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

Authorization

Authorization 的伪代码结构如下:

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

{}内字段的信息如下。

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

在 query string 中包含签名参数

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

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

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 的刷新与预热任务的配额。