1. 接口描述
接口请求域名： waf.tencentcloudapi.com 。
添加SaaS型WAF防护域名
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：AddSpartaProtection。 |
| Version | 是 | String | 公共参数，本接口取值：2018-01-25。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表，本接口仅支持其中的: ap-guangzhou, ap-seoul 。 |
| Domain | 是 | String | 需要防护的域名 示例值：randy.qcloudwaf.com |
| CertType | 是 | Integer | 证书类型。 0：仅配置HTTP监听端口，没有证书 1：证书来源为自有证书 2：证书来源为托管证书 示例值：0 |
| IsCdn | 是 | Integer | waf前是否部署有七层代理服务。 0：没有部署代理服务 1：有部署代理服务，waf将使用XFF获取客户端IP 2：有部署代理服务，waf将使用remote_addr获取客户端IP 3：有部署代理服务，waf将使用ip_headers中的自定义header获取客户端IP 示例值：0 |
| UpstreamType | 是 | Integer | 回源类型。 0：通过IP回源 1：通过域名回源 示例值：0 |
| IsWebsocket | 是 | Integer | 是否开启WebSocket支持。 0：关闭 1：开启 示例值：0 |
| LoadBalance | 是 | String | 回源负载均衡策略。 0：轮询 1：IP hash 2：加权轮询 示例值：0 |
| Ports.N | 是 | Array of PortItem | 服务端口列表配置。 NginxServerId：新增域名时填'0' Port：监听端口号 Protocol：端口协议 UpstreamPort：与Port相同 UpstreamProtocol：与Protocol相同 示例值：[{"NginxServerId":"0","Port":"80","Protocol":"http","UpstreamPort":"80","UpstreamProtocol":"http"}] |
| IsKeepAlive | 是 | String | 必填项，是否开启长连接。 0： 短连接 1： 长连接 示例值：1 |
| InstanceID | 是 | String | 必填项，域名所属实例id 示例值：waf_2kl62zgs0108e8j3 |
| Cert | 否 | String | CertType为1时，需要填充此参数，表示自有证书的证书链 示例值：-----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- |
| PrivateKey | 否 | String | CertType为1时，需要填充此参数，表示自有证书的私钥 示例值：-----BEGIN RSA PRIVATE KEY----- xxx -----END RSA PRIVATE KEY----- |
| SSLId | 否 | String | CertType为2时，需要填充此参数，表示腾讯云SSL平台托管的证书id 示例值：cKnKQLJ |
| ResourceId | 否 | String | 待废弃，可不填。Waf的资源ID。 示例值：waf_2kl62zgs0108e8j3 |
| IpHeaders.N | 否 | Array of String | IsCdn为3时，需要填此参数，表示自定义header 示例值：["x-real-ip"] |
| UpstreamScheme | 否 | String | 服务配置有HTTPS端口时，HTTPS的回源协议。 http：使用http协议回源，和HttpsUpstreamPort配合使用 https：使用https协议回源 示例值：https |
| HttpsUpstreamPort | 否 | String | HTTPS回源端口,仅UpstreamScheme为http时需要填当前字段 示例值：80 |
| IsGray | 否 | Integer | 待废弃，可不填。是否开启灰度，0表示不开启灰度。 示例值：0 |
| GrayAreas.N | 否 | Array of String | 待废弃，可不填。灰度的地区 示例值：["gz","bj"] |
| HttpsRewrite | 否 | Integer | 必填项，是否开启HTTP强制跳转到HTTPS。 0：不强制跳转 1：开启强制跳转 示例值：1 |
| UpstreamDomain | 否 | String | 域名回源时的回源域名。UpstreamType为1时，需要填充此字段 示例值：www.qq.com |
| SrcList.N | 否 | Array of String | IP回源时的回源IP列表。UpstreamType为0时，需要填充此字段 示例值：["25.66.42.153","156.32.3.65"] |
| IsHttp2 | 否 | Integer | 必填项，是否开启HTTP2，需要开启HTTPS协议支持。 0：关闭 1：开启 示例值：0 |
| Edition | 否 | String | 待废弃，可不填。WAF实例类型。 sparta-waf：SAAS型WAF clb-waf：负载均衡型WAF cdn-waf：CDN上的Web防护能力 示例值：sparta-waf |
| Anycast | 否 | Integer | 待废弃，目前填0即可。anycast IP类型开关： 0 普通IP 1 Anycast IP 示例值：0 |
| Weights.N | 否 | Array of Integer | 回源IP列表各IP的权重，和SrcList一一对应。当且仅当UpstreamType为0，并且SrcList有多个IP，并且LoadBalance为2时需要填写，否则填 [] 示例值：[10,10,10] |
| ActiveCheck | 否 | Integer | 必填项，是否开启主动健康检测。 0：不开启 1：开启 示例值：1 |
| TLSVersion | 否 | Integer | TLS版本信息 示例值：1 |
| CipherTemplate | 否 | Integer | 必填项，加密套件模板。 0：不支持选择，使用默认模板 1：通用型模板 2：安全型模板 3：自定义模板 示例值：0 |
| Ciphers.N | 否 | Array of Integer | 自定义的加密套件列表。CipherTemplate为3时需要填此字段，表示自定义的加密套件，值通过DescribeCiphersDetail接口获取。 示例值：[1,2,15] |
| ProxyReadTimeout | 否 | Integer | WAF与源站的读超时时间，默认300s。 示例值：300 |
| ProxySendTimeout | 否 | Integer | WAF与源站的写超时时间，默认300s。 示例值：300 |
| SniType | 否 | Integer | WAF回源时的SNI类型。 0：关闭SNI，不配置client_hello中的server_name 1：开启SNI，client_hello中的server_name为防护域名 2：开启SNI，SNI为域名回源时的源站域名 3：开启SNI，SNI为自定义域名 示例值：2 |
| SniHost | 否 | String | SniType为3时，需要填此参数，表示自定义的SNI； 示例值：randy.testwaf.com |
| XFFReset | 否 | Integer | 是否开启XFF重置。0：关闭 1：开启 示例值：0 |
| Note | 否 | String | 域名备注信息 示例值：域名备注 |
| UpstreamHost | 否 | String | 自定义回源Host。默认为空字符串，表示使用防护域名作为回源Host。 示例值：www.qq.com |
| ProxyBuffer | 否 | Integer | 是否开启缓存。 0：关闭 1：开启 示例值：0 |
| ProbeStatus | 否 | Integer | 是否开启拨测。 0: 禁用拨测 1: 启用拨测。默认启用拨测 示例值：1 |
| GmType | 否 | Integer | 国密选项。0：不开启国密 1：在原有TLS选项的基础上追加支持国密 2：开启国密并仅支持国密客户端访问 示例值：0 |
| GmCertType | 否 | Integer | 国密证书类型。0：无国密证书 1：证书来源为自有国密证书 2：证书来源为托管国密证书 示例值：0 |
| GmCert | 否 | String | GmCertType为1时，需要填充此参数，表示自有国密证书的证书链 示例值：-----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- |
| GmPrivateKey | 否 | String | GmCertType为1时，需要填充此参数，表示自有国密证书的私钥 示例值：-----BEGIN PRIVATE KEY----- xxx -----END PRIVATE KEY----- |
| GmEncCert | 否 | String | GmCertType为1时，需要填充此参数，表示自有国密证书的加密证书 示例值：-----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- |
| GmEncPrivateKey | 否 | String | GmCertType为1时，需要填充此参数，表示自有国密证书的加密证书的私钥 示例值：-----BEGIN PRIVATE KEY----- xxx -----END PRIVATE KEY----- |
| GmSSLId | 否 | String | GmCertType为2时，需要填充此参数，表示腾讯云SSL平台托管的证书id 示例值：aKnKQLJ |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 添加SaaS型WAF防护域名
添加SaaS型WAF防护域名
输入示例
POST / HTTP/1.1
Host: waf.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: AddSpartaProtection
<公共请求参数>
{
"Ports": [
{
"NginxServerId": "0",
"Port": "80",
"Protocol": "http",
"UpstreamPort": "80",
"UpstreamProtocol": "http"
}
],
"Domain": "randy.qcloudwaf.com",
"SrcList": [
"125.36.35.4"
],
"Weights": [],
"UpstreamType": 0,
"HttpsRewrite": 0,
"CertType": 0,
"IsCdn": 3,
"IsGray": 0,
"IsHttp2": 0,
"IsWebsocket": 0,
"ProxyBuffer": 1,
"ActiveCheck": 0,
"CipherTemplate": 1,
"TLSVersion": 3,
"Ciphers": [],
"IsKeepAlive": "1",
"LoadBalance": "0",
"InstanceID": "waf_2kw60zgy0908e8j3",
"Anycast": 0,
"ProxyReadTimeout": 300,
"ProxySendTimeout": 300,
"SniHost": "randy.sni.com",
"SniType": 0,
"IpHeaders": [
"x-real-ip"
],
"XFFReset": 0,
"UpstreamHost": "randy.upstream.com",
"Note": "randy test domain",
"ProbeStatus": 1
}输出示例
{
"Response": {
"RequestId": "9ee8be5b-6caa-4c39-ab70-890e0e673515"
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation | 操作失败。 |
| FailedOperation.RedisOperationFailed | 操作Redis数据库失败 |
| InternalError | 内部错误。 |
| InternalError.AsynchronousCallFailed | 异步调用失败 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.CertificationParameterErr | 证书信息参数错误 |
| InvalidParameter.DomainExceedsLimitErr | 域名数量超出限制错误 |
| InvalidParameter.DomainNotRecord | 域名未备案 |
| InvalidParameter.PortParameterErr | 端口信息参数错误 |
| InvalidParameter.ProtectionDomainParameterErr | 防护域名参数错误 |
| InvalidParameter.TLSParameterErr | TLS或加密套件参数错误 |
| InvalidParameter.UnauthorizedOperationParameterErr | 越权参数错误 |
| InvalidParameter.UpstreamParameterErr | 回源信息参数错误 |
| InvalidParameter.XFFResetParameterErr | XFF重置参数错误 |
| InvalidParameterValue | 参数取值错误。 |
| LimitExceeded | 超过配额限制。 |
| MissingParameter | 缺少参数错误。 |
| ResourceInUse | 资源被占用。 |
| ResourceInUse.EmptyErr | EmptyErr |
| ResourceInsufficient | 资源不足。 |
| ResourceNotFound | 资源不存在。 |
| ResourceUnavailable | 资源不可用。 |
| ResourcesSoldOut | 资源售罄。 |
| UnauthorizedOperation | 未授权操作。 |
| UnknownParameter | 未知参数错误。 |
