You need to enable JavaScript to run this app.
导航
请求结构
最近更新时间:2023.11.10 17:41:28首次发布时间:2023.11.10 17:41:28

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

背景信息

请求方法

请求方法详见各个接口具体的需求,选择GETPOST方式发起请求。

通信协议

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

字符编码

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

地域信息

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

地域

ID

华北2(北京)

cn-beijing

华北2(北京高防)

cn-gaofang-bj

华东2(上海)

cn-shanghai

华东2(南通高防3)

cn-gaofang-nt3

华南1(广州)

cn-guangzhou

请求构成

请求 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"
  ]
}

发起请求

您可以使用curlPostman或直接编写代码等方式发送请求调用 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"
  ]
}