本文档介绍如何调用火山引擎内容分发网络（CDN）的 API。
调用 CDN API 有两种方式：
火山引擎 SDK 使您以编程方式与 CDN 进行交互。在交互过程中您无需处理复杂的签名计算。火山引擎 SDK 为常见的编程语言提供了相应的库，并提供了示例代码方便您上手。
关于各版本 SDK 的说明，参见 SDK 更新说明。各版本 SDK 的下载链接如下。
另一种调用 CDN API 的方式是发送 API 请求。API 请求中需要包含计算的签名以验证您的身份。
在发送 API 请求前，您需要理解以下内容：
API 请求的结构包含以下内容：
CDN API 服务地址是 cdn.volcengineapi.com。
您可以使用 HTTP 协议或 HTTPS 协议发送请求。推荐您使用 HTTPS 协议，其安全性更高。
如无特殊说明，您使用 POST 方法发送请求。同时，您必须在请求头中指定 Content-Type: application/json。
请求参数包括公共参数和每个 API 所特有的参数。
公共参数是每个 API 请求必须包含的参数。如果一个 API 请求缺失公共参数，请求会失败。以下表格中的公共参数必须包含在查询字符串（query string）中。
| 参数名称 | 数据类型 | 是否必选 | 参数说明 | 示例 |
|---|---|---|---|---|
| Action | string | 是 | 表示 API 名称。名称的正则表达式格式为 [a-zA-Z]+。 | DescribeCdnData |
| Version | string | 是 | 表示 API 版本。该参数的取值是 2021-03-01。 | 2021-03-01 |
| X-Expires | int | 否 | 表示鉴权信息中包含的签名的有效时间，单位是秒。该参数的默认值是 900。 | 900 |
每个请求中必须包含鉴权信息。该鉴权信息用以验证请求者的身份。您可以使用以下任一方法提供鉴权信息。推荐您使用方法一。
您需要在请求头中包含以下参数：
| 参数名称 | 数据类型 | 是否必选 | 参数说明 | 示例 |
|---|---|---|---|---|
X-Date | string | 是 | 表示签名计算的时间，以 UTC 表示。时间精度是秒。 |
|
Authorization | string | 是 | 该参数表示鉴权字符串。该参数的伪代码如下： |
您需要在查询字符串中包含以下查询参数。
| 参数名称 | 数据类型 | 参数说明 | 示例 |
|---|---|---|---|
X-Date | string | 表示签名计算的时间，以 UTC 表示。时间精度是秒。 关于该参数，您需要留意以下内容：
|
|
| X-Algorithm | string | 表示签名计算所使用的算法。该参数的值是 HMAC-SHA256。 | HMAC-SHA256 |
X-Credential | string | 该参数值的伪代码如下： 关于 |
|
X-SignedHeaders | string | 该参数的说明与 伪代码参数说明中的 |
|
| X-Signature | string | 表示一个经过计算得到的签名。关于签名的计算方式，参见 签名计算方式。 |
本章节主要介绍签名是如何计算的。文档最后提供了 签名计算的示例代码。
HMAC 方法使用的是 HMAC-SHA256 算法。HexEncode 方法将字符串转换为十六进制编码格式的字符串。签名参数 Signature 是基于 kSigning 和 StringToSign 参数计算而来的。Signature 的伪代码如下：
Signature = HexEncode(HMAC(kSigning, StringToSign))
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 的伪代码如下：
// 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：表示请求方法。对于 CDN，该参数的取值是 POST。CanonicalURI：表示请求的 URL。CanonicalQueryString：表示规范的查询字符串。CanonicalQueryString 的值是通过以下规则生成的：
CanonicalHeaders：表示规范的请求头。CanonicalHeaders 是通过以下步骤生成的：
\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 | 表示 CDN 的服务名称。该参数的取值是 CDN。 | CDN |
SignedHeaders | string | 表示参与签名计算的请求头参数。多个请求头参数使用分号（;）分隔。这些请求头参数是根据参数名称升序排序的。 |
|
| Algorithm | string | 表示签名计算所使用的算法。该参数的取值为 HMAC-SHA256。 | HMAC-SHA256 |
| Request | string | 该参数是一个常量，值是 request。 | request |
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 分钟的带宽数据。