请求结构

控制台 OpenAPI 接口的调用，是通过向指定服务地址发送请求，并需满足签名信息和具体接口的业务信息来完成的。OpenAPI 的请求主要包含请求 URL、请求 Header 和请求 Body。

背景信息

请求方法

请求方法详见各个接口具体的需求，选择GET或POST方式发起请求。

通信协议

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

字符编码

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

地域信息

您在调用 API 时，Region信息需要与实例所在地域的 ID 保持一致。其对应关系如下表所示。

请求构成

请求 URL

您可以通过发送 HTTP 或 HTTPS 请求来调用 Web 应用防火墙的 API。发起 API 请求的 URL 由多个参数组成，有固定的请求结构。请求及返回结果均使用 UTF-8 的字符集进行编码。
HTTPS 请求 URL 格式示例如下：

POST https://{Host}?Action={Action name}&Version={Registered version}

• POST表示控制台的 OpenAPI 支持的请求方法。
• Host指定了服务接入地址（Endpoint），当前接入地址为open.volcengineapi.com。
• Action={Action name}指定了要调用的 API。
• Version={Registered version}指定了要调用的 API 的版本。

请求 Header

请求头（Header）中需要指定Content-Type和请求鉴权信息等公共参数，用于标识用户和接口签名。若非必要，每个单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。
其中，Content-Type指定了请求消息体的结构化格式，Web 应用防火墙的Content-Type固定为application/json。若请求时未指定Content-Type的值，默认为application/json格式。详细的参数列表及说明请参见公共参数。
请求 Header 格式示例如下：

X-Date: 20230711T035055Z
Authorization: HMAC-SHA256 Credential=AKLTNGU0OGEyMT***/20230711/cn-beijing/waf/request, SignedHeaders=content-type;x-content-sha256;x-date, Signature=da4fac562d00f41ad8***

• X-Date指签名使用时间，使用 UTC 时间，精确到秒。格式为YYYYMMDD'T'HHMMSS'Z'，例如： 20230711T035055Z。
• Authorization指授权信息。格式为HMAC-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}
  • AccessKeyId (String)：发起请求的账号的 Access Key ID。例如：AKLTNGU0OGEyMT***。
  • ShortDate (String)：请求的短时间，使用 UTC 时间，精确到日。格式为YYYYMMDD，例如：20230711。
  • Region (String)：请求的地域，例如：cn-beijing。

    说明

    Region信息需要与实例所在地域的 ID 保持一致。具体请参见地域信息。

  • Service (String)：请求的服务。Web 应用防火墙的服务名为waf。
  • SignedHeaders (String)：参与签名的 Header，用分号分隔。例如content-type;x-content-sha256;x-date。
  • Signature (String)：计算后的签名。示例中为da4fac562d00f41ad8***。

请求 Body

请求 Body，即请求消息体，主要传递业务相关的请求参数。若请求消息体中参数支持中文，则中文字符必须为 UTF-8 编码。
每个接口的请求消息体内容不同，也并非每个接口都需要有请求消息体（即消息体为空）。调用接口时，请参考具体 API 接口文档构建请求消息体。
例如，获取攻击源信息的请求 Body 格式示例如下：

{
  "Host": "example.volcwaf001.com",
  "StartTime": 1695767322,
  "EndTime": 1697185065,
  "AnalysisKey": "Country",
  "Plugins": [
    "web_policy"
  ]
}

发起请求

您可以使用curl、Postman或直接编写代码等方式发送请求调用 API。
例如，获取防护概览信息的请求示例如下：

POST https://open.volcengineapi.com/?Action=QueryProtectionOverviewLb&Version=2022-12-09
X-Date: 20230711T035055Z
Authorization: HMAC-SHA256 Credential=AKLTNGU0OGEyMT***/20230711/cn-beijing/waf/request, SignedHeaders=content-type;x-content-sha256;x-date, Signature=da4fac562d00f41ad8***

{
  "Host": "example.volcwaf001.com",
  "StartTime": 1695767322,
  "EndTime": 1697185065,
  "AnalysisKey": "Country",
  "Plugins": [
    "web_policy"
  ]
}