请求结构

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

• 服务地址。
• 通讯协议。
• 请求方法。
• 请求参数。
• 字符编码。

服务地址

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

通信协议

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

请求方法

请求方法详见各个接口。

注意事项

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

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

请求参数

全球加速的 OpenAPI 请求包含两类参数：公共请求参数和接口请求参数。

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

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

字符编码

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

公共参数

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

URI 参数

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

签名参数

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

在 request headers 中的场景

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

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

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

在 query string 中包含签名参数

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

签名机制

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

返回结构

API 请求成功时，HTTP 响应状态码是 200。 API 请求失败时，会出现以下任意一个情况：

• HTTP 响应状态码是 4xx 或 5xx。

• 响应正文的 ResponseMetadata 结构体包含 Error 字段。

API请求成功的响应示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "DescribeAccelerator",
        "Version": "2022-03-01",
        "Service": "ga",
        "Region": "cn-north-1"
    },
    "Result": {
        "AcceleratorId": "accinstance-xxxxxxxx",
        "CreateTime": 1717127658,
        "CrossDomainBandwidthIds": [
            "crb-xxx"
        ],
        "BillingType": "PayByTrafficMonthly",
        "BillingSpec": "small",
        "ExpiredTime": 1719719658,
        "FullPortSwitch": false,
        "BillingSpecEffectiveTime": 1717127658,
        "ChargeType": "POSTPAY",
        "BandwidthPackageIds": [
            "gbwp-xx"
        ],
        "Name": "test",
        "RenewType": 0,
        "RegionCount": 1,
        "State": "active",
        "CNAME": "xxxx",
        "ListenerCount": 10,
        "AccountID": "2100xxx"
    }
}

API 请求失败的响应示例

{
    "ResponseMetadata": {
        "RequestId": "20230604110420****100232280022D31",
        "Action": "CreateAccelerator",
        "Version": "2022-03-01",
        "Service": "ga",
        "Region": "cn-north-1",
        "Error": {
            "Code": "MethodNotSupport",
            "Message": "请使用POST方法传递参数"
        }
    }
}

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