发送 HTTP 请求

您通过 HTTP 请求来调用火山引擎证书中心的 API。

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

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

请求结构

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

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

API 服务地址

证书中心的 API 服务地址是 open.volcengineapi.com。

通讯协议

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

请求方法

请求方法详见各个接口的具体说明。火山引擎中的 OpenAPI 大多数支持 GET 或 POST 方法。
使用 POST 方法发送请求时，您必须在请求头中指定 Content-Type: application/json。

请求参数

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

公共参数

公共参数是每个 API 请求必须包含的参数。如果一个 API 请求缺失公共参数，请求会失败。

以下表格中的公共参数必须包含在请求头（header）中。

以下表格中的公共参数必须包含在查询字符串（query string）中。

签名参数

公共参数还包含签名参数 Signature。该签名参数可以包含在请求头中，也可以包含在查询字符串中。推荐您将签名参数包含在请求头中。

（推荐）在请求头中包含该签名参数

您可以在请求头中包含该签名参数。参见请求示例。当包含在请求头中，签名参数 Signature 是 Authorization 参数所表示的结构体的一部分。请求头必须包含以下参数。

Authorization

Authorization 的伪代码结构如下：

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

Authorization 伪代码中的 Signature 参数表示签名。关于 Signature 参数的计算步骤，参见签名计算机制。关于 Authorization 伪代码中其他参数的说明，参见伪代码中参数的说明。

在查询字符串中包含该签名参数

您可以在查询字符串中包含该签名参数。当包含在查询字符串中，签名参数的名称是 X-Signature。查询字符串需要包含以下参数。

X-Credential

X-Credential 的伪代码结构如下：

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

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

签名计算机制

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

• 本章节的伪代码中的 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 是通过以下步骤生成的：
  1. 将参与签名计算的请求头参数的名称转化成小写字母。
  2. 在字符级别对这些名称进行升序排序。
  3. 以 key-value 的格式拼接这些请求头参数。key 是请求头参数的名称，value 是请求头参数的值。
  4. 在每个请求头参数后添加换行符（\n）。
• SignedHeaders：参见伪代码中参数的说明。
• HexEncode(Hash(RequestPayload))：表示一个计算值。该值是通过对请求正文中 payload 的值应用 SHA256 哈希算法计算得到的。

伪代码中参数的说明

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

请求示例

GET https://open.volcengineapi.com/?Action=CertificateGetInstance&Version=2021-06-01

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