最近更新时间:2024.04.19 19:22:24
首次发布时间:2023.02.02 19:06:53
您通过 HTTP 请求来调用火山引擎证书中心的 API。
在发送 HTTP 请求前,您需要理解以下内容:
API 请求的结构包含以下内容:
证书中心的 API 服务地址是 open.volcengineapi.com
。
您可以使用 HTTP
协议或 HTTPS
协议发送请求。推荐您使用 HTTPS
协议,其安全性更高。
请求方法详见各个接口的具体说明。火山引擎中的 OpenAPI 大多数支持 GET 或 POST 方法。
使用 POST
方法发送请求时,您必须在请求头中指定 Content-Type: application/json
。
请求参数包括公共参数和每个 API 所特有的参数。
公共参数是每个 API 请求必须包含的参数。如果一个 API 请求缺失公共参数,请求会失败。
以下表格中的公共参数必须包含在请求头(header)中。
参数名称 | 数据类型 | 是否必选 | 参数说明 |
---|---|---|---|
Region | String | 是 | 服务地区。该参数的取值是 cn-north-1 。 |
ServiceName | String | 是 | 服务名称。该参数的取值是 certificate_service 。 |
X-Upstream | String | 是 | 请求对应的云平台。该参数的取值是 volcano 。 |
以下表格中的公共参数必须包含在查询字符串(query string)中。
参数名称 | 数据类型 | 是否必选 | 参数说明 |
---|---|---|---|
Action | String | 是 | 表示 API 名称。名称格式为 [a-zA-Z]+。 |
Version | String | 是 | 表示 API 版本。该参数的取值是 2021-06-01 。 |
X-Expires | int | 否 | 表示签名的有效时间,单位是秒。该参数的默认值是 900 。 |
公共参数还包含签名参数 Signature
。该签名参数可以包含在请求头中,也可以包含在查询字符串中。推荐您将签名参数包含在请求头中。
您可以在请求头中包含该签名参数。参见请求示例。当包含在请求头中,签名参数 Signature
是 Authorization
参数所表示的结构体的一部分。请求头必须包含以下参数。
参数名称 | 数据类型 | 是否必选 | 参数说明 | 示例 |
---|---|---|---|---|
X-Date | String | 是 | 表示签名计算的时间,以 UTC 表示。时间精度是秒。
|
|
Authorization | String | 是 | 该参数表示一个结构体。结构体中包含了签名参数 Signature 。参见 Authorization。 |
Authorization
Authorization
的伪代码结构如下:
HMAC-SHA256 Credential = {AccessKey}/{ShortDate}/{Region}/{Service}/{Request}, SignedHeaders={SignedHeaders}, Signature={Signature}
Authorization
伪代码中的 Signature
参数表示签名。关于 Signature
参数的计算步骤,参见签名计算机制。关于 Authorization
伪代码中其他参数的说明,参见伪代码中参数的说明。
您可以在查询字符串中包含该签名参数。当包含在查询字符串中,签名参数的名称是 X-Signature
。查询字符串需要包含以下参数。
参数名称 | 数据类型 | 是否必选 | 参数说明 | 示例 |
---|---|---|---|---|
X-Date | String | 是 | 表示签名计算的时间,以 UTC 表示。时间精度是秒。
|
|
X-Algorithm | String | 是 | 表示签名计算所使用的算法。该参数的值是 HMAC-SHA256 。 | HMAC-SHA256 |
X-Credential | String | 是 | 参见 X-Credential。 | AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE/20210913/cn-north-1/CDN/request |
X-SignedHeaders | String | 是 | 表示参与签名计算的请求头参数。多个请求头参数使用分号(;)分隔。这些请求头参数是根据参数名称升序排序的。 |
|
X-Signature | String | 是 | 表示签名。关于签名的计算步骤,参见签名计算机制。 |
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
,您必须先获取您账号的 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
:表示请求方法。对于证书中心,该参数的取值是 GET
或 POST
。CanonicalURI
:表示请求的 URI。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 | 表示证书中心的服务名称。该参数的取值是 certificate_service 。 | certificate_service |
SignedHeaders | String | 表示参与签名计算的请求头参数。多个请求头参数使用分号(;)分隔。这些请求头参数是根据参数名称升序排序的。 |
|
Algorithm | String | 表示签名计算所使用的算法。该参数的取值为 HMAC-SHA256 。 | HMAC-SHA256 |
Request | String | 该参数是一个常量,值是 request 。 | request |
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