服务地址
火山引擎 OpenAPI 的通用服务接入地址如下:
地域 | 服务地址 |
---|---|
不限 | open.volcengineapi.com |
通信协议
所有接口均使用安全性更高的 HTTPS 方式发送请求,提供高安全性的通信通道。
请求方法
OpenAPI 仅允许使用 POST 请求。
注意
使用 POST 方式时,公共参数中的Action
和Version
必须放在Query String
当中。
请求参数
火山引擎 OpenAPI 请求包含两类参数:
• 公共请求参数:每一个接口需要包含的请求参数。详细信息,请参见 公共参数。
• 接口请求参数:各个接口特有的请求参数。详细信息,请参见各个接口文档。
字符编码
请求及返回结果使用 UTF-8 的字符集进行编码。
公共请求参数是每个接口都需要使用的请求参数,开发者每次使用火山引擎 OpenAPI 发送请求时都需要携带这些公共请求参数,否则会导致请求失败。公共请求参数首字母均为大写,以此区分其他请求参数。
Action 和 Version
注意
Action
和 Version
必须放在Query
当中。
名称 | 类型 | 是否必填 | 参数格式 | 描述 |
---|---|---|---|---|
Action | String | 是 | [a-zA-Z]+ | 接口的名字,与具体的接口相关。 |
Version | String | 是 | YYYY-MM-DD | 接口的版本信息,与具体的接口相关。 |
X-Expires | Int | 否 | 300 | 签名的有效时间,单位为秒,默认不填是 900 秒。 |
签名参数
说明
签名参数是请求必不可少的部分,可以放在 Header 或 Query 中。
在Header中的场景
名称 | 类型 | 是否必填 | 描述 |
---|---|---|---|
X-Date | String | 是 | 使用 UTC 时间,精确到秒。请使用格式:YYYYMMDD'T'HHMMSS'Z',例如:20201103T104027Z。 |
Authorization | String | 是 | 用于验证请求合法性的认证信息。格式为:HMAC-SHA256 Credential={AccessKey}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}。 注意 Service 为固定值: |
Authorization 中的信息含义:
名称 | 类型 | 备注 |
---|---|---|
AccessKey | String | 请求的 Access Key ID。 |
ShortDate | String | 请求的短时间,精确到日。使用 UTC 时间,例如: |
Region | String | 请求的地域(Region),例如: |
Service | String | 请求的服务,调用多云安全 API 时为: |
SignedHeaders | String | 参与签名的 Header,用分号(;)分隔。 |
Signature | String | 计算完毕的签名。签名计算方式,请参见 签名机制。 |
火山引擎对于每一次的 HTTPS 协议访问请求,会通过访问签名信息中的访问密钥(包括 Access Key ID 和 Secret Access Key),验证访问请求者身份。
获取访问密钥
账户和有权限的用户可以新建访问密钥,操作如下:
使用主账号或拥有密钥管理权限的 IAM 用户登录 [访问控制控制台](https://console.volcengine.com/iam)。
在左侧导航栏选择 **资源管理 > 密钥管理**。
查看您账号的访问密钥列表。
○ 每个账号最多同时拥有 2 个访问密钥。
○ 如果当前账号的访问密钥数量未达到上限,则可单击 新建密钥,创建新的访问密钥。创建完成后单击 查看AccessKey详情,查看新的访问密钥信息。
创建一个正规化请求
说明
• Hash 代指 SHA256 算法。
• HexEncode 代指转 16 进制编码。
CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))
在签名之前,要将请求正规化,使得签名计算过程无异议,其主要过程及伪代码如下:
字段 | 说明 |
---|---|
HTTPRequestMethod | HTTP 请求方法,例如 POST。 |
CanonicalURI | 正规化后的 URI。如果 URI 为空,那么使用 |
CanonicalQueryString | 正规化后的 Query String。Query String 正规化流程如下:
|
CanonicalHeaders | 正规化后的Header。其中伪代码如下:
其中, 注意 • 结尾需要添加换行符: |
SignedHeaders | 参与签名的 Header 名称。
|
RequestPayload | 完整的请求的 Body。 |
创建签名字符串
签名字符串主要包含请求以及正规化请求的元数据信息,由签名算法、请求日期、信任状和正规化请求哈希值连接组成,伪代码如下:
StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))
字段说明如下。
字段 | 说明 |
---|---|
Algorithm | 签名的算法。目前火山引擎仅支持 HMAC-SHA256 签名算法。 |
RequestDate | 请求 UTC 时间。请使用YYYYMMDD'T'HHMMSS'Z'格式。 |
CredentialScope | 凭证范围。格式为YYYYMMDD/region/service/request。 |
CanonicalRequest | 前序正规化请求的结果。 |
计算签名秘钥
1.计算签名前,首先从 Secret Access Key 派生出签名密钥(Signing Key),而不是直接使用 Secret Access Key。具体计算过程如下:
kSecret = *Your Secret Access Key* kDate = HMAC(kSecret, Date) kRegion = HMAC(kDate, Region) kService = HMAC(kRegion, Service) kSigning = HMAC(kService, "request")
2.计算签名。
Signature = HexEncode(HMAC(kSigning, StringToSign))
3.构建 Header。
说明
表达式中用{}
内的内容,代表上文计算出的中间过程。
Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}
返回结果
调用火山引擎 OpenAPI 后,所有返回结果都会带上 RequestId、Action、Version、Service、Region 等字段。
正常返回示例
接口调用成功后,会返回请求 ID 和接口返回参数。HTTP 状态码为 2xx。
{ "ResponseMetadata": { "RequestId": "2020102017223001022507", "Action": "{Action}", "Version": "{Version}", "Service": "{Service}", "Region": "{Region}" }, "Result":"..." }
异常返回示例
接口调用出错后,会返回请求 ID 和错误信息。HTTP 状态码为 4xx 或者 5xx。
您可以根据接口错误代码 Code 和错误信息 Message,参考 公共错误码 和具体接口错误码排查错误。
{ "ResponseMetadata": { "RequestId": "202010201722300102****", "Action": "{Action}", "Version": "{Version}", "Service": "{Service}", "Region": "{Region}", "Error": { "Code": "InvalidActionOrVersion", "Message": "Could not find operation GetUserById for version 2018-01-01" } } }