You need to enable JavaScript to run this app.
导航
发送 API 请求
最近更新时间:2024.01.08 20:28:20首次发布时间:2021.07.15 11:09:03

本文档介绍如何调用火山引擎内容分发网络的 API。

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

请求结构

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

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

API 服务地址

内容分发网络的 API 服务地址是 cdn.volcengineapi.com

通讯协议

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

请求方法

如无特殊说明,您使用 POST 方法发送请求。同时,您必须在请求头中指定 Content-Type: application/json

请求参数

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

公共参数

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

参数名称数据类型是否必选参数说明示例
Actionstring表示 API 名称。名称的正则表达式格式为 [a-zA-Z]+。DescribeCdnData
Versionstring表示 API 版本。该参数的取值是 2021-03-012021-03-01
X-Expiresint表示鉴权信息中包含的签名的有效时间,单位是秒。该参数的默认值是 900900

请求鉴权

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

(推荐)方法一:在请求头中包含鉴权信息

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

参数名称数据类型是否必选参数说明示例

X-Date

string

表示签名计算的时间,以 UTC 表示。时间精度是秒。

关于该参数,您需要留意以下内容:在请求到达时,内容分发网络会计算请求到达时间与 X-Date 之间的差距。如果差距超过 X-Expires 指定的时间范围,内容分发网络判定该请求无效。因此,在计算签名前,建议您校准系统时间。

20210913T081805Z

Authorization

string

该参数表示鉴权字符串。该参数的伪代码如下:
HMAC-SHA256 Credential = {AccessKey}/{ShortDate}/{Region}/{Service}/{Request}, SignedHeaders={SignedHeaders}, Signature={Signature}

该伪代码的说明如下:

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

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

参数名称数据类型参数说明示例

X-Date

string

表示签名计算的时间,以 UTC 表示。时间精度是秒。 关于该参数,您需要留意以下内容:

  • 在请求到达时,内容分发网络会计算请求到达时间与 X-Date 之间的差距。如果差距超过 X-Expires 指定的时间范围,内容分发网络判定该请求无效。因此,在计算签名前,建议您校准系统时间。

20210913T081805Z

X-Algorithmstring表示签名计算所使用的算法。该参数的值是 HMAC-SHA256HMAC-SHA256

X-Credential

string

该参数值的伪代码如下:
{AccessKey}/{ShortDate}/{Region}/{Service}/{Request}

关于 X-Credential伪代码中参数的说明,参见伪代码中参数的说明

AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE/20210913/cn-north-1/CDN/request

X-SignedHeaders

string

该参数的说明与伪代码参数说明中的 SignedHeaders 参数是相同的。

host;x-content-sha256;x-date

X-Signaturestring表示一个经过计算得到的签名。关于签名的计算方式,参见签名计算方式

签名计算方式

本章节主要介绍签名是如何计算的。文档最后提供了签名计算的示例代码

  • 签名计算是一个复杂的过程。推荐您使用火山引擎 SDK 与内容分发网络进行交互,无需计算签名。
  • 本章节的伪代码中的 HMAC 方法使用的是 HMAC-SHA256 算法。
  • 本章节的伪代码中的 HexEncode 方法将字符串转换为十六进制编码格式的字符串。

签名参数 Signature 是基于 kSigningStringToSign 参数计算而来的。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 伪代码中 AlgorithmRequestDate 参数的说明,参见伪代码中参数的说明。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:表示请求方法。对于内容分发网络,该参数的取值是 POST
  • CanonicalURI:表示请求的 URL。
  • CanonicalQueryString:表示规范的查询字符串。CanonicalQueryString 的值是通过以下规则生成的:
    • 按参数名称对查询参数进行升序排序。
  • CanonicalHeaders:表示规范的请求头。CanonicalHeaders 是通过以下步骤生成的:
    • 将参与签名计算的请求头参数的名称转化成小写字母。
    • 在字符级别对这些名称进行升序排序。
    • 以 key-value 的格式拼接这些请求头参数。key 是请求头参数的名称,value 是请求头参数的值。
    • 在每个请求头参数后添加换行符(\n)。
  • SignedHeaders:参见伪代码中参数的说明
  • HexEncode(Hash(RequestPayload)):表示一个计算值。该值是通过对请求正文中 payload 的值应用 SHA256 哈希算法计算得到的。

伪代码中参数的说明

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

参数名称数据类型参数说明示例
AccessKeystring表示您账号的 Access Key ID。参考获取 Access KeyAKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE
RequestDatestring该参数与请求鉴权章节中 X-Date 的定义相同。20210913T081805Z
ShortDatestring该参数与 RequestDate 的定义相同,只不过时间精度是日。20210913
Regionstring该参数用于签名计算。参数值建议是 cn-north-1,也可以是非空的任意字符串。cn-north-1
Servicestring表示内容分发网络的服务名称。该参数的取值是 CDNCDN

SignedHeaders

string

表示参与签名计算的请求头参数。多个请求头参数使用分号(;)分隔。这些请求头参数是根据参数名称升序排序的。

一般来说,SignedHeaders 的值是 host;x-content-sha256;x-date。您也可以指定任意请求头参数作为 SignedHeaders 的值。

host;x-content-sha256;x-date

Algorithmstring表示签名计算所使用的算法。该参数的取值为 HMAC-SHA256HMAC-SHA256
Requeststring该参数是一个常量,值是 requestrequest

请求示例

POST https://cdn.volcengineapi.com/?Action=DescribeCdnConfig&Version=2021-03-01

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

//Request Body
{
    "Domain": "www.example.com"
}

签名计算的示例代码

我们以调用 DescribeCdnData API 为例,获取 example.com 域名最近 5 分钟的带宽数据。