You need to enable JavaScript to run this app.
导航
API 说明
最近更新时间:2025.02.11 16:34:58首次发布时间:2024.12.20 16:16:51

1. 请求结构

服务地址
火山引擎 OpenAPI 的通用服务接入地址如下:

地域

服务地址

不限

open.volcengineapi.com

通信协议
所有接口均使用安全性更高的 HTTPS 方式发送请求,提供高安全性的通信通道。
请求方法
OpenAPI 仅允许使用 POST 请求。

注意

使用 POST 方式时,公共参数中的ActionVersion必须放在Query String当中。

请求参数
火山引擎 OpenAPI 请求包含两类参数:
• 公共请求参数:每一个接口需要包含的请求参数。详细信息,请参见 公共参数
• 接口请求参数:各个接口特有的请求参数。详细信息,请参见各个接口文档。
字符编码
请求及返回结果使用 UTF-8 的字符集进行编码。

2. 公共参数

公共请求参数是每个接口都需要使用的请求参数,开发者每次使用火山引擎 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 为固定值:mcs

Authorization 中的信息含义:

名称

类型

备注

AccessKey

String

请求的 Access Key ID。

ShortDate

String

请求的短时间,精确到日。使用 UTC 时间,例如:20180201

Region

String

请求的地域(Region),例如:cn-beijing,表示华北2(北京)地域。
更多 Region 信息,请参见 地域和可用区

Service

String

请求的服务,调用多云安全 API 时为:mcs

SignedHeaders

String

参与签名的 Header,用分号(;)分隔。

Signature

String

计算完毕的签名。签名计算方式,请参见 签名机制

3. 签名机制

火山引擎对于每一次的 HTTPS 协议访问请求,会通过访问签名信息中的访问密钥(包括 Access Key ID 和 Secret Access Key),验证访问请求者身份。
获取访问密钥
账户和有权限的用户可以新建访问密钥,操作如下:

  1. 使用主账号或拥有密钥管理权限的 IAM 用户登录 [访问控制控制台](https://console.volcengine.com/iam)。
    
  2. 在左侧导航栏选择 **资源管理 > 密钥管理**。
    
  3. 查看您账号的访问密钥列表。
    

    ○ 每个账号最多同时拥有 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 正规化流程如下:

  1. URL 编码(UrlEncode)每个 Query String 参数名称和参数值。
    
  2. 按照 ASCII 字节顺序对参数名称严格排序。
    
  3. 将排序好的参数名称和参数值用`=`连接;按照排序结果将参数对用`&`连接。
    
CanonicalQueryString = "Action=ListUsers&Version=2018-01-01"

CanonicalHeaders

正规化后的Header。其中伪代码如下:

CanonicalHeaders = CanonicalHeadersEntry0 + CanonicalHeadersEntry1 + ... + CanonicalHeadersEntryN
CanonicalHeadersEntry = Lowercase(HeaderName) + ':' + Trimall(HeaderValue) + '\n'

其中,Lowercase表示将 Header 的名称全部转化成小写,Trimall表示去掉 Header 的值的前后多余空格。

注意

• 结尾需要添加换行符:\n
• Header 的顺序由headerName的小写后 ASCII 排序。

SignedHeaders

参与签名的 Header 名称。
签名 Header 需包含在正规化 Headers 名称列表中,用于指明哪些 Header 参与签名计算,从而忽略请求被 Proxy 添加的额外 Header。如果存在hostx-date两个 Header,则必须添加到正规化 Headers 名称列表中。
伪代码如下:

SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... + Lowercase(HeaderNameN)

RequestPayload

完整的请求的 Body。
• URL 编码(同 RFC3986 方法) 每个 Query String 参数名称和参数值。
其中 GET 方法需要包含哈希算法、信任状、签名日期和签名 Header 等全部参数。
• 按照 ASCII 字节顺序对参数名称严格排序。
• 将排序好的参数名称和参数值用=连接;按照排序结果将参数对用&连接。

创建签名字符串
签名字符串主要包含请求以及正规化请求的元数据信息,由签名算法、请求日期、信任状和正规化请求哈希值连接组成,伪代码如下:

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"
         }
     }
 }