You need to enable JavaScript to run this app.
导航
调用方式
最近更新时间:2024.06.28 16:50:41首次发布时间:2022.12.08 18:36:34

请求结构

若您调用火山引擎全站加速的 OpenAPI ,是通过向指定服务地址发送请求,并满足火山引擎签名信息和具体接口的业务信息来完成的。火山引擎全站加速的API请求的结构涵盖以下内容:

  • 服务地址。

  • 通讯协议。

  • 请求方法。

  • 请求参数。

  • 字符编码。

服务地址

火山引擎的 OpenAPI 的通用服务接入地址为:open.volcengineapi.com

通信协议

支持通过HTTPHTTPS两种方式进行请求通信,推荐使用安全性更高的HTTPS方式发送请求。

请求方法

请求方法详见各个接口具体的需求。火山引擎全站加速中的 OpenAPI 支持 POST 请求。

注意

  • 使用POST方式时,公共请求参数中的ActionVersion必须放在Query 中,签名参数可放在 Header 或 Query 中。

  • POST 请求中的非公共请求参数放在 Body 中。

请求参数

全站加速的 OpenAPI 请求包含两类参数:公共请求参数接口请求参数

  • 公共请求参数是每一个接口需要包含的,具体可参见公共参数

  • 接口请求参数是各个接口特有的,详见各个接口描述。

字符编码

请求及返回结果使用UTF-8的字符集进行编码。

公共参数

公共请求参数是每个 API 请求必须包含的参数。如果 API 请求中缺少公共请求参数,请求会失败。
公共请求参数首字母均为大写,以此区分其他请求参数。公共请求参数分为 URI 参数和签名参数。

URI 参数

URI 参数必须包含在 query string 中。

名称类型是否必选格式说明示例
Action
string
[a-zA-Z]+
API 名称,与具体的接口相关,表示要执行的操作。
CreateAccelerator
VersionstringYYYY-MM-DDAPI 版本信息。2022-03-01

签名参数

每个 API 请求必须包含签名参数。签名参数可以包含在 query string 中作为 URI 参数,也可以包含在 request headers 中。

在 request headers 中的场景

如果在 request headers 中包含签名参数,必须包含以下参数。

名称类型是否必选描述
X-Date
string
表示签名的 UTC 时间,精确到秒。如20201103T104027Z

Authorization

string

表示签名值。

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

Authorization 示例中的信息含义如下:

名称类型描述示例
AccessKey
string
火山引擎账号的 AccessKey ID,可以从 秘钥管理 页面获取。
AKLTMjI2ODVlYzI3ZGY1NGU4ZjhjYWRjMTlmNTM5OTZkYzE
ShortDatestring请求的时间,使用 UTC 时间,精确到日。20210913
Regionstring请求的地域。cn-beijing
Servicestring请求的服务名称。dcdn
SignedHeadersstring参与签名的 request headers。Request headers 之间以分号分隔。host;x-content-sha256;x-date
Signaturestring计算后的签名。关于更多签名的信息,参见签名机制

在 query string 中包含签名参数

如果在 query string 中包含签名参数,必须包含以下参数。

名称类型是否必选描述示例
X-Date
string
表示签名的 UTC 时间,精确到秒。
20210913T081805Z
X-Algorithmstring表示签名算法,该参数是一个固定值。HMAC-SHA256
X-Credentialstring{AccessKey}/{ShortDate}/{Region}/{Service}/request 组成。-
X-SignedHeadersstring参与签名的 request headers。Request headers 之间以分号分隔。host;x-content-sha256;x-date
X-Signaturestring计算后的签名。关于更多签名的信息,参见签名机制

签名机制

为了保证请求者身份的合法性以及请求在传输过程中不被恶意篡改,火山引擎签名机制要求请求者对请求参数进行哈希值计算,经过加密后同API请求一起发送到服务器中,服务器将以同样的机制对收到的请求进行签名计算,并以此与请求者传来的签名进行比对,若签名未通过验证,请求将被拒绝。
请参考签名方法文档。

返回结构

所有的返回都会带上RequestId、Action、Version、Service、Region等字段。
API 请求成功时,HTTP 响应状态码是 200。
API 请求失败时,会出现以下任意一个情况:

  • HTTP 响应状态码是 4xx 或 5xx。
  • 响应正文的 ResponseMetadata 结构体包含 Error 字段。

API 请求成功的响应示例

{
    "ResponseMetadata": {
        "RequestId": "2020102017223001022507", 
        "Action": "{Action}",
        "Version": "{Version}",
        "Service": "{Service}",
        "Region": "{Region}" 
    },
    "Result":"..."
}

API 请求失败的响应示例

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

相较于请求成功的响应结果,请求失败的响应结果不再有Result部分,而ResponseMetadata中将额外出现 Error 字段,字段解释如下:

字段说明
ErrorError 出现表明本次请求失败。
CodeCode 内容为具体的错误码,您可根据错误码查询文档自助解决问题。
CodeNCodeN 为标识错误码的数字 ID ,方便查找问题,仅部分接口会提供 CodeN 。
MessageMessage描述了错误发生的具体原因,供您排查问题参考。
RequestIDRequestID 是每次 API 请求的唯一标识,当出现了无法自助解决的问题时,您可通过工单系统联系我们,提供请求的 RequestID ,我们将协助进行故障排查。