本文档介绍调用火山引擎 DDoS 服务 OpenAPI 的通用方法。在您开始调用具体的业务 API 之前，请仔细阅读本篇指南，以了解构建和发送 API 请求所需的所有要素。

调用流程概览

一次完整的 API 调用遵循标准的请求认证流程。为了帮助您清晰地理解，我们将其分解为以下四个核心步骤：

准备基础信息：确定服务地址（Endpoint），并准备好调用 API 所需要的业务参数和公共参数。

计算请求签名：遵循火山引擎的签名规则，使用您的访问密钥（Access Key）为本次请求计算出最终的签名（Signature）。

组装并发送请求：将基础信息、签名及其他认证信息共同组装成一个完整的 HTTP 请求，然后发送至服务端。

处理服务响应：接收并解析服务端返回的 JSON 格式数据，根据业务需求进行后续处理。

步骤一准备基础信息

在开始构建请求前，您需要明确以下信息。

服务地址

API 请求必须发送到指定的服务地址。详细的服务地址对应列表请参考服务地址。

DDoS 高防属于 Global 服务，其服务地址不受地域影响。例如，IPv4 协议客户端支持的地址固定为advdefence.volcengineapi.com。

DDoS 基础防护和 DDoS 原生服务的 Endpoint 由服务名（service）和地域（region）共同确定。例如，IPv4 协议的客户端支持的服务地址格式如下：

{service}.{region}.volcengineapi.com

参数	说明	示例
service	DDoS 服务对应的子服务名称标识。 DDoS 基础防护：ddos DDoS 原生防护：origin-defence	origin-defence
region	资源所在的地域 ID，参考服务地址。	cn-beijing

例如，若某 IPv4 协议客户端要调用位于华北 2（北京）地域的 DDoS 原生防护 API，对应的服务地址为：

https://origin-defence.cn-beijing.volcengineapi.com

公共参数

无论使用何种请求方法，每个 API 请求都必须包含以下参数，其他公共参数请参考公共参数。

参数名	位置	类型	是否必选	描述
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 的签名工具模块查看每个 API 的签名生成过程，也可以参考签名机制自行计算签名。主要流程说明如下：

构造规范请求：将 HTTP 请求方法、URI、查询参数、请求头（Headers）和请求体（Body）等信息，按照固定格式拼接成一个标准化的字符串。

构造待签字符串：将签名算法（HMAC-SHA256）、请求时间（来自 X-Date Header）、凭证范围（Credential Scope）和上一步规范请求的哈希值拼接起来。

计算签名密钥：使用您的 SecretAccessKey 和凭证范围信息（日期、地域、服务），通过一系列 HMAC-SHA256 计算得出用于签名的最终密钥。

计算最终签名：使用上一步得到的签名密钥，对“待签字符串”进行 HMAC-SHA256 计算，生成最终的签名值。

步骤三组装并发送请求

完成签名后，您需要将所有信息组装成一个完整的 HTTP 请求并发送。

请求 URL

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

POST表示控制台的 OpenAPI 支持的请求方法。

Host指定了服务接入地址（Endpoint），详情请参考服务地址。

Action={Action name}指定了要调用的 API。

Version={Registered version}指定了要调用的 API 的版本。

请求 Header

请求头（Header）中需要指定 Content-Type 和请求鉴权信息等公共参数，用于标识用户和接口签名。若非必要，每个单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。请求 Header 格式示例如下：

详细的参数列表及说明请参见公共参数。

请求 Body

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

例如，查询攻击事件列表的请求 Body 格式示例如下：

发送请求

将包含 Authorization 和X-Date头的完整请求发送至第一步确定的服务地址。

步骤四处理服务响应

API 的返回结果为 application/json 格式。

成功结果

请求成功时，返回的 JSON 数据包含 Result 和 ResponseMetadata 两部分。

Result: 包含具体的业务数据，其结构因 Action 的不同而异。

ResponseMetadata: 包含本次请求的元数据。当您需要技术支持时，请务必提供 RequestId。

失败结果

请求失败时，返回的 JSON 数据包含 Error 和 ResponseMetadata。

Error中包含错误码 Code 和详细错误信息 Message，可用于定位问题。

DDoS防护