本文档介绍调用火山引擎 DDoS 服务 OpenAPI 的通用方法。在您开始调用具体的业务 API 之前，请仔细阅读本篇指南，以了解构建和发送 API 请求所需的所有要素。 ## 调用流程概览一次完整的 API 调用遵循标准的请求认证流程。为了帮助您清晰地理解，我们将其分解为以下四个核心步骤： 1. **准备基础信息**：确定服务地址（Endpoint），并准备好调用 API 所需要的业务参数和公共参数。 2. **计算请求签名**：遵循火山引擎的签名规则，使用您的访问密钥（Access Key）为本次请求计算出最终的签名（Signature）。 3. **组装并发送请求**：将基础信息、签名及其他认证信息共同组装成一个完整的 HTTP 请求，然后发送至服务端。 4. **处理服务响应**：接收并解析服务端返回的 JSON 格式数据，根据业务需求进行后续处理。 ## 步骤一准备基础信息在开始构建请求前，您需要明确以下信息。 ### 服务地址 API 请求必须发送到指定的服务地址。详细的服务地址对应列表请参考[服务地址](/docs/6352/2227859)。 * DDoS 高防属于 Global 服务，其服务地址不受地域影响。例如，IPv4 协议客户端支持的地址固定为`advdefence.volcengineapi.com`。 * DDoS 基础防护和 DDoS 原生服务的 Endpoint 由服务名（service）和地域（region）共同确定。例如，IPv4 协议的客户端支持的服务地址格式如下： ```Plain Text {service}.{region}.volcengineapi.com ``` |参数 |说明 |示例 | |---|---|---| |`service` |DDoS 服务对应的子服务名称标识。|`origin-defence` |\ | || |\ | |* DDoS 基础防护：ddos| |\ | |* DDoS 原生防护：origin\-defence | | |`region` |资源所在的地域 ID，参考[服务地址](/docs/6352/2227859)。 |`cn-beijing` | 例如，若某 IPv4 协议客户端要调用位于华北 2（北京）地域的 DDoS 原生防护 API，对应的服务地址为： ```Plain Text https://origin-defence.cn-beijing.volcengineapi.com ``` ### 公共参数无论使用何种请求方法，每个 API 请求都必须包含以下参数，其他公共参数请参考[公共参数](https://www.volcengine.com/docs/6369/67268?lang=zh)。 :::warning * `Action` 和 `Version` **必须**放在 URL 的 QueryString 中。 * 其他公共参数的位置取决于请求方法（GET 在 Query 中，POST 在 Body 或 Header 中）。 ::: |参数名 |位置 |类型 |是否必选 |描述 | |---|---|---|---|---| |`Action` |Query |String |是 |要执行的操作，例如 `DescribeInstances`。 | |`Version` |Query |String |是 |API 的版本号，格式为 `YYYY-MM-DD`。例如 `2022-11-01`。 | |`Region` |Header/Query |String |是 |地域名称，必须与 Endpoint 中的 `region` 保持一致。参与签名计算。 | |`Service` |Header/Query |String |是 |服务名称，必须与 Endpoint 中的 `service` 保持一致。参与签名计算。 | ### 请求方法与业务参数根据您要调用的接口，确定使用 `GET` 还是 `POST` 方法，并准备好相应的业务参数。 * **GET 方法**: 所有业务参数和公共参数（`Action` 和 `Version` 除外）均在 URL 的 QueryString 中传递。适用于查询类操作。 * **POST 方法**: 所有业务参数和公共参数（`Action` 和 `Version` 除外）均在请求体 (Request Body) 中以 `application/json` 格式传递。适用于创建、更新、删除等操作。 ## 步骤二计算请求签名签名需要遵循一套严格的加密和规范化流程，您可以通过 [API Explorer](https://api.volcengine.com/api-explorer) 的签名工具模块查看每个 API 的签名生成过程，也可以参考[签名机制](https://www.volcengine.com/docs/6369/67269?lang=zh#%E7%AD%BE%E5%90%8D%E6%9C%BA%E5%88%B6)自行计算签名。主要流程说明如下： 1. **构造规范请求**：将 HTTP 请求方法、URI、查询参数、请求头（Headers）和请求体（Body）等信息，按照固定格式拼接成一个标准化的字符串。 2. **构造待签字符串**：将签名算法（HMAC\-SHA256）、请求时间（来自 `X-Date` Header）、凭证范围（Credential Scope）和上一步规范请求的哈希值拼接起来。 3. **计算签名密钥**：使用您的 `SecretAccessKey` 和凭证范围信息（日期、地域、服务），通过一系列 HMAC\-SHA256 计算得出用于签名的最终密钥。 4. **计算最终签名**：使用上一步得到的签名密钥，对“待签字符串”进行 HMAC\-SHA256 计算，生成最终的签名值。

## 步骤三组装并发送请求完成签名后，您需要将所有信息组装成一个完整的 HTTP 请求并发送。 ### 请求 URL 您可以通过发送 HTTP 或 HTTPS 请求来调用 API。发起 API 请求的 URL 由多个参数组成，有固定的请求结构。请求及返回结果均使用 UTF\-8 的字符集进行编码。HTTPS 请求 URL 格式示例如下： ```Plain Text POST https://{Host}?Action={Action name}&Version={Registered version} ``` * `POST`表示控制台的 OpenAPI 支持的请求方法。 * `Host`指定了服务接入地址（Endpoint），详情请参考[服务地址](/docs/6352/2227859)。 * `Action={Action name}`指定了要调用的 API。 * `Version={Registered version}`指定了要调用的 API 的版本。 ### 请求 Header 请求头（Header）中需要指定 Content\-Type 和请求鉴权信息等公共参数，用于标识用户和接口签名。若非必要，每个单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。请求 Header 格式示例如下： ```Plain Text X-Date: 20230711T035055Z Authorization: HMAC-SHA256 Credential=AKLTNGU0OGEyMT***/20230711/cn-beijing/origin-defence/request, SignedHeaders=content-type;x-content-sha256;x-date, Signature=da4fac562d00f41ad8*** ``` 详细的参数列表及说明请参见[公共参数](https://www.volcengine.com/docs/6369/67268?lang=zh)。 ### 请求 Body 请求 Body，即请求消息体，主要传递业务相关的请求参数。若请求消息体中参数支持中文，则中文字符必须为 UTF\-8 编码。每个接口的请求消息体内容不同，也并非每个接口都需要有请求消息体（即消息体为空）。调用接口时，请参考具体 API 接口文档构建请求消息体。例如，查询攻击事件列表的请求 Body 格式示例如下： ```JSON { "CurrPage": 1, "PageSize": 10, "InsId": 44, "BeginTime": 1693560540, "EndTime": 1698744600, "IpList": [ "180.184.**.**" ] } ``` ### 发送请求将包含 `Authorization` 和`X-Date`头的完整请求发送至第一步确定的服务地址。 ```JSON POST https://ddos.cn-beijing.volcengineapi.com/?Action=GetAlarm&Version=2020-12-08 HTTP/1.1 X-Date: 20250329T180937Z Authorization: HMAC-SHA256 Credential=AKLTYWViMTVmZGYzM2E0NDI5Mzk2MDZjNjFmMjc********/20250329/cn-beijing/ddos/request, SignedHeaders=host;x-date, Signature=1eda9e7e6b1728151a8e8791fdaf67cfbd28bd5c80d0fce2eb208746******** { "ip": "192.1.**.**", "beginDate": "2025-10-01 00:00:00", "endDate": "2025-12-31 11:59:59", "blockStatus": 1, "page": 1, "pageSize": 10 } ``` ## 步骤四处理服务响应 API 的返回结果为 `application/json` 格式。 ### **成功结果** 请求成功时，返回的 JSON 数据包含 `Result` 和 `ResponseMetadata` 两部分。 * `Result`: 包含具体的业务数据，其结构因 `Action` 的不同而异。 * `ResponseMetadata`: 包含本次请求的元数据。当您需要技术支持时，请务必提供 `RequestId`。 ```JSON { "ResponseMetadata": { "RequestId": "202407291830000102270830571C3A****", "Action": "GetAlarm", "Version": "2020-12-08", "Service": "ddos", "Region": "cn-beijing" }, "Result": { "Id": 7566, "Ip": "192.1.**.**", "AttackType": "UDP Flood", "PpsPeak": 4532, "BpsPeak": 52099000, "StartTime": "2024-12-28 06:17:10", "EndTime": "2024-12-28 06:18:40", "PeakTime": "2024-12-28 06:17:13", "Product": "EcsInstance", "BlockStatus": 0, "BlockStartTime": "", "BlockEndTime": "" } } ``` ### **失败结果** 请求失败时，返回的 JSON 数据包含 `Error` 和 `ResponseMetadata`。 `Error`中包含错误码 `Code` 和详细错误信息 `Message`，可用于定位问题。 ```JSON { "ResponseMetadata": { "RequestId": "202407291835000102270830571C3B****", "Action": "GetAlarm", "Version": "2020-12-08", "Service": "ddos", "Region": "cn-beijing", "Error": { "Code": "InvalidParameter", "Message": "The specified ip is not valid." } } } ```

DDoS防护