文档中心

云拨测

拨测任务（V2）

CreateTask - 创建周期拨测任务

调用 CreateTask 接口创建一个定时执行的拨测任务，以监控和分析网络性能和稳定性。

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：CreateTask

要执行的操作，取值：CreateTask。

Version string 必选示例值：2025-10-31

API的版本，取值：2025-10-31。

ProjectName string 可选示例值：default

资源所属项目名称，如果不传，默认归属于default项目。

Tags object[] 可选示例值：--

资源绑定的标签。

Key string 必选示例值：k1

标签键，长度限制在1~128个字符之间。

Value string 必选示例值：v1

标签值。

长度限制在0~256个字符之间。

允许任何语言的文字、数字、空格和符号“:.:/=+-@”。

Type integer 必选示例值：1

任务类型。其中：

1：HTTP(S)

2：DNS

3：PING

5：UDP

6：TCP

8: 上传

9: 下载

11: 页面元素

Name string 必选示例值：cloud-detect-test

任务名称。

Address string 必选示例值：www.example.com

目标地址。

NodeCount integer 必选示例值：10

每条线路的样本数量。

IntervalSeconds long 必选示例值：60

拨测频率（单位：秒）。可选值：60、120、180、300、600、900、1200、1800、3600、7200、10800、21600、43200、86400。

FinishTime long 必选示例值：0

结束时间（秒级时间戳），0代表不限结束时间。

PeriodConfig object 可选示例值：--

自定义执行周期。

Period integer 必选示例值：1

执行周期。可选值：

1：每天

2：每周

3：每月

Days long[] 可选示例值：[1, 2, 3, 4, 5]

执行日，当执行周期为周或月时必填。

TimeRangeConfig object[] 可选示例值：--

自定义时间段配置，存储了多段时间范围以及对应的拨测频率。

StartTime object 必选示例值：--

每日执行开始时间。

Hour integer 必选示例值：09

开始小时，00~23。

Minute integer 必选示例值：00

开始分钟，00~59。

EndTime object 必选示例值：--

每日执行结束时间。

Hour integer 必选示例值：09

开始小时，00~23。

Minute integer 必选示例值：00

开始分钟，00~59。

Interval long 必选示例值：60

拨测频率，0为不执行。可选值：0、60、120、180、300、600、900、1200、1800、3600、7200、10800、21600、43200、86400。

ResultAssert object 可选示例值：--

任务断言配置。

Relation string 必选示例值：and

断言条件关系：

Conditions object[] 必选示例值：--

断言条件列表。

Field string 必选示例值：action.http.status_code

断言字段，取值请参见断言参数配置。

Value string 可选示例值：200

断言匹配值。

Operator string 必选示例值：include

比较方式，取值请参见断言参数配置。

Property string 可选示例值：key

断言属性，例如：HTTP中的响应头，Jsonpath、xpath的值等。

ProcessType string 可选示例值：md5

解析/加工方式，取值请参见断言参数配置。

DiagnoseConfig object 可选示例值：--

诊断配置。

PingConfig object 可选示例值：--

PING配置。

ProtocolType integer 可选示例值：1

协议类型。可选值：

1（默认）：ICMP

2：TCP

3：UDP

Timeout integer 可选示例值：20

超时时间。取值范围：[1,60]。默认值：20。

ExecuteInterval double 可选示例值：0.5

执行间隔，单位：秒（s）。

可选值：0.2、0.5、1、2、3、4、5、10。

默认值：0.2。

PackagesNum integer 可选示例值：4

包数量。取值范围：(0,100]。默认值：4。

PackagesSize integer 可选示例值：32

包大小。

可选值：32、64、128、256、512、1024、1080、1450。

默认值：32。

EnableDividePackage boolean 可选示例值：true

是否切分包。可选值：

false：不切分。

true（默认）：切分。

ConnectTimeout double 可选示例值：0.5

单次监测超时、TCPing的单次建联超时时间。单位为秒（s）。取值范围：[0.01,10]。默认值：0.5。

MtrConfig object 可选示例值：--

MTR配置。

PackageType integer 可选示例值：1

包数据类型。探测包类型，可选值：

1（默认）：ICMP

2：TCP

3：UDP

Interval double 可选示例值：0.2

探测间隔。单位：秒（s）。取值范围：[0,1]。默认值：0.2。

PackageNum integer 可选示例值：4

发包数。单位：个。取值范围：[1,16]。默认值：4。

PackageSize integer 可选示例值：32

包大小。单位：bytes。取值范围：[1,128]。默认值：32。

MaxHops integer 可选示例值：30

最大跳数。单位：个。取值范围：[1,60]。默认值：30。

MaxUnknownHost integer 可选示例值：10

最大未知主机数。单位：个。取值范围：[1,60]。默认值：5。

Timeout integer 可选示例值：10

超时时间。单位：秒（s）。默认值：10。

DnsReverseResolution boolean 可选示例值：true

是否开启DNS逆向解析。默认值为false。

PcapStatus integer 可选示例值：1

表示抓包配置。可选值：

0：不抓包

1：总是抓包

2：失败时抓包

MethodList integer[] 可选示例值：2

诊断方法列表。可选值：

1：PING

2：DNS

3：MTR

DnsConfig object 可选示例值：--

DNS配置。

Timeout integer 可选示例值：5

超时时间。单位：秒（s）。取值范围：(0,45)。默认值：5。

SearchType integer 可选示例值：1

查询方式。可选值：

1（默认）：递归

2：迭代

Server string 可选示例值：dns.example.com

DNS服务器地址。

ServerType integer 可选示例值：3

DNS服务器类型。可选值：

1：IPv4

2：IPv6

3：自动

默认值：3。

EnableDig boolean 可选示例值：true

是否使用dig命令格式检测结果。默认值：true。

RecordType integer 可选示例值：1

指定查询的记录类型。可选值：

1：A

2：AAAA

3：CNAME

4：MX

5：TXT

6：PTR

不设置时会自动根据TargetServerType（目标服务器类型）来指定A或者AAAA。

LineIdList long[] 必选示例值：274

节点ID列表。

PingConfig object 可选示例值：--

PING任务配置。如果创建PING类型的任务，必填该配置项。

ProtocolType integer 可选示例值：1

协议类型。可选值：

1（默认）：ICMP

2：TCP

3：UDP

Timeout integer 可选示例值：20

超时时间。取值范围：[1,60]。默认值：20。

ExecuteInterval double 可选示例值：0.5

执行间隔，单位：秒（s）。

可选值：0.2、0.5、1、2、3、4、5、10。

默认值：0.2。

PackagesNum integer 可选示例值：4

包数量。取值范围：(0,100]。默认值：4。

PackagesSize integer 可选示例值：32

包大小。

可选值：32、64、128、256、512、1024、1080、1450。

默认值：32。

EnableDividePackage boolean 可选示例值：true

是否切分包。可选值：

false：不切分。

true（默认）：切分。

ConnectTimeout double 可选示例值：0.5

单次监测超时、TCPing的单次建联超时时间。单位为秒（s）。取值范围：[0.01,10]。默认值：0.5。

PageConfig object 可选示例值：--

页面元素任务配置。如果创建页面元素类型的任务，必填该配置项。

Cookies object[] 可选示例值：--

设置请求的cookie。

Name string 必选示例值：digest

cookie名称。

Value string 必选示例值：value

cookie值。

Domain string 可选示例值：www.example.com

cookie域名。

Timeout long 可选示例值：40

超时时间。取值范围：[5,300]，默认值：40。

AutoScroll boolean 可选示例值：true

是否自动滚屏，默认关闭。

QuicConfig object 可选示例值：--

QUIC配置。

QuicVersion integer 可选示例值：0

QUIC版本，可选值：

0（默认）： Default，浏览器默认版本，不会强制QUIC版本

9000：H3

29：H3Draft29

43：Q043

46：Q046

50：Q050

ForceQuicHost string[] 可选示例值：["abc.com"]

强制使用QUIC的主机列表。若不传入，所有域名都会统一按照配置的QuicVersion执行QUIC协议；若传入，列表中指定的域名会优先按照配置的QuicVersion执行。

EnableCache boolean 可选示例值：true

是否开启缓存，默认开启。

CustomHeader object 可选示例值：--

自定义请求头。

Type integer 可选示例值：1

自定义请求头修改类型，可选值：

1（默认）：关闭

3：修改全部包

Values object 可选示例值：{"key":"value"}

自定义请求value。

SaveElements boolean 可选示例值：true

是否返回全部元素，默认开启。

EnableRedirect boolean 可选示例值：true

是否开启重定向，默认开启。

DisableCompress boolean 可选示例值：true

是否禁止压缩，需拨测目标的服务端支持。默认值：false。

CustomHostConfig object 可选示例值：--

自定义解析/主机名配置。

Strategy integer 必选示例值：1

下发策略。可选值：

1：随机

2：轮询

CustomHosts object[] 必选示例值：--

自定义的主机列表，每个对象包含原始主机名和解析列表。

RawHostPort string 必选示例值：example.com:80

域名。格式为host:port, port可省略。长度大于0。

ResolveList string[] 必选示例值：127.0.0.1:8080、[0:0:0:0:0:0:0:1]:8080

指定解析ip,caname list，格式为host:port，port可省略。列表长度大于0。

说明

当IP为IPv6时，Host需用英文中括号包裹。

IgnoreCertificate boolean 可选示例值：true

是否忽略证书校验，默认值：false。

SaveFinalSnapshot integer 可选示例值：1

是否保存最终截图快照。

1（默认）：不保存

2：保存

ScreenshotKeypoint boolean 可选示例值：true

关键点截图，默认值：false。

SaveBaseDocumentBody boolean 可选示例值：true

是否保存基础文档响应体，当前仅支持text/html和application/json。默认值：false。

UploadConfig object 可选示例值：--

文件上传任务配置。如果创建文件上传类型的任务，必填该配置项。

Method integer 必选示例值：1

HTTP方法，可选值：

拨测方式为下载时，取值为1：GET。

拨测方式为上传时，取值：

2：POST

3：PUT

DnsType string 可选示例值：system

指定DNS服务器，可选值：

system（默认）：系统默认

custom：自定义DNS

doh: DoH URL

isp：运营商DNS

Headers object[] 可选示例值：--

HTTP header，最大设置100个。

Key string 必选示例值：X-Volcengine-Platform

HTTP头部的名称。

Value string 必选示例值：cloud-detect

HTTP头部的值，对应于Key的值。

Queries object[] 可选示例值：--

HTTP query参数，最大设置100个。

Key string 必选示例值：X-Volcengine-Platform

HTTP头部的名称。

Value string 必选示例值：cloud-detect

HTTP头部的值，对应于Key的值。

Timeout integer 必选示例值：30

超时时间，取值范围：1~120秒。

Redirect boolean 可选示例值：true

是否开启重定向，默认值：false。

DnsServer string 可选示例值：114.114.114.114

指定DNS服务器地址：

当DNSType为system或isp时，忽略当前值。

当DNSType为custom时，必须是合法的IP地址。

当DNSType为doh时，填写DoH地址，即：以https://开头的URL。

HttpVersion string 可选示例值：auto

HTTP版本，可选值：

auto（默认）：自动协商

http/1.1：HTTP/1.1

h2：HTTP2

h3：HTTP/3(RFC9000)

UploadFileUrl string 可选示例值：https://example.com/file

待上传文件的下载地址，长度小于1KB，若未填写，则随机生成文件内容。

MaxTransferSize long 可选示例值：1024

最大请求/响应体，单位Byte，最大为20MB。

CustomHostConfig object 可选示例值：--

自定义Host。

Strategy integer 必选示例值：1

下发策略。可选值：

1：随机

2：轮询

CustomHosts object[] 必选示例值：--

自定义的主机列表，每个对象包含原始主机名和解析列表。

RawHostPort string 必选示例值：example.com:80

域名。格式为host:port, port可省略。长度大于0。

ResolveList string[] 必选示例值：127.0.0.1:8080、[0:0:0:0:0:0:0:1]:8080

指定解析ip,caname list，格式为host:port，port可省略。列表长度大于0。

说明

当IP为IPv6时，Host需用英文中括号包裹。

IgnoreCertificate boolean 可选示例值：true

忽略证书验证，默认值：false。

TaskGroupId long 可选示例值：0

任务组ID。0表示未绑定任务组。

DownloadConfig object 可选示例值：--

文件下载任务配置。如果创建文件下载类型的任务，必填该配置项。

Method integer 必选示例值：1

HTTP方法，可选值：

拨测方式为下载时，取值为1：GET。

拨测方式为上传时，取值：

2：POST

3：PUT

DnsType string 可选示例值：system

指定DNS服务器，可选值：

system（默认）：系统默认

custom：自定义DNS

doh: DoH URL

isp：运营商DNS

Headers object[] 可选示例值：--

HTTP header，最大设置100个。

Key string 必选示例值：X-Volcengine-Platform

HTTP头部的名称。

Value string 必选示例值：cloud-detect

HTTP头部的值，对应于Key的值。

Queries object[] 可选示例值：--

HTTP query参数，最大设置100个。

Key string 必选示例值：X-Volcengine-Platform

HTTP头部的名称。

Value string 必选示例值：cloud-detect

HTTP头部的值，对应于Key的值。

Timeout integer 必选示例值：30

超时时间，取值范围：1~120秒。

Redirect boolean 可选示例值：true

是否开启重定向，默认值：false。

DnsServer string 可选示例值：114.114.114.114

指定DNS服务器地址：

当DNSType为system或isp时，忽略当前值。

当DNSType为custom时，必须是合法的IP地址。

当DNSType为doh时，填写DoH地址，即：以https://开头的URL。

HttpVersion string 可选示例值：auto

HTTP版本，可选值：

auto（默认）：自动协商

http/1.1：HTTP/1.1

h2：HTTP2

h3：HTTP/3(RFC9000)

UploadFileUrl string 可选示例值：https://example.com/file

待上传文件的下载地址，长度小于1KB，若未填写，则随机生成文件内容。

MaxTransferSize long 可选示例值：1024

最大请求/响应体，单位Byte，最大为20MB。

CustomHostConfig object 可选示例值：--

自定义Host。

Strategy integer 必选示例值：1

下发策略。可选值：

1：随机

2：轮询

CustomHosts object[] 必选示例值：--

自定义的主机列表，每个对象包含原始主机名和解析列表。

RawHostPort string 必选示例值：example.com:80

域名。格式为host:port, port可省略。长度大于0。

ResolveList string[] 必选示例值：127.0.0.1:8080、[0:0:0:0:0:0:0:1]:8080

指定解析ip,caname list，格式为host:port，port可省略。列表长度大于0。

说明

当IP为IPv6时，Host需用英文中括号包裹。

IgnoreCertificate boolean 可选示例值：true

忽略证书验证，默认值：false。

DnsHijackConfig object 可选示例值：--

DNS劫持配置。

DnsHijackAllowList object[] 可选示例值：--

劫持白名单。

Host string 必选示例值：www.example.com

劫持主机名，长度≥1。

HijackList string[] 必选示例值：[1.1.1.1]

劫持判定列表，列表长度≥1。

DnsHijackBlockList object[] 可选示例值：--

劫持黑名单。

Host string 必选示例值：www.example.com

劫持主机名，长度≥1。

HijackList string[] 必选示例值：[1.1.1.1]

劫持判定列表，列表长度≥1。

HttpConfig object 可选示例值：--

HTTP任务配置，HTTP任务必填该项。

RequestBody string 可选示例值：{\"key\": \"value\"}

请求Body。

Redirect boolean 可选示例值：false

是否开启重定向。默认值：false。

Timeout integer 可选示例值：30

超时时间。单位：秒（s）。取值范围：[1,120]。默认值：30。

CustomHostConfig object 可选示例值：--

自定义Host。

Strategy integer 必选示例值：1

下发策略。可选值：

1：随机

2：轮询

CustomHosts object[] 必选示例值：--

自定义的主机列表，每个对象包含原始主机名和解析列表。

RawHostPort string 必选示例值：example.com:80

域名。格式为host:port, port可省略。长度大于0。

ResolveList string[] 必选示例值：127.0.0.1:8080、[0:0:0:0:0:0:0:1]:8080

指定解析ip,caname list，格式为host:port，port可省略。列表长度大于0。

说明

当IP为IPv6时，Host需用英文中括号包裹。

IgnoreCertificate boolean 可选示例值：false

忽略证书验证。默认值：false。

BodyType integer 可选示例值：1

HTTP Body的格式，支持文本和二进制：

1：十六进制编码

2：文本

MaxBodySize long 可选示例值：8192

最大传输大小/最大响应体，单位Byte，最大为20MB。

DnsType string 可选示例值：system

指定DNS服务器，可选值：

system（默认）：系统默认

custom：自定义DNS

doh：DoH URL

isp：运营商DNS

ProxyUrl string 可选示例值：http://proxy.example.com:8080

代理地址。

DnsServer string 可选示例值：192.168.1.1

指定DNS服务器地址。

当DNSType为system或isp时，忽略当前值。

当DNSType为custom时，必须是合法的IP地址。

当DNSType为doh时，填写DoH地址，即：以https://开头的URL。

HttpMethod integer 可选示例值：1

HTTP方法，仅HTTP和文件传输类型的任务需要。可选值：

1（默认）：GET

2：POST

3：PUT

4：DELETE

5：PATCH

6：HEAD

7：OPTIONS

HttpHeaders object[] 可选示例值：--

Http Header，最大设置100个。

Key string 必选示例值：X-Volcengine-Platform

HTTP头部的名称。

Value string 必选示例值：cloud-detect

HTTP头部的值，对应于Key的值。

HttpVersion string 可选示例值：auto

HTTP版本。可选值：

auto：自动协商

http/1.1：HTTP/1.1

h2：HTTP2

h3：HTTP/3(RFC9000)

SelectionConfig object 可选示例值：--

选点配置，如果LineIDList为空，则此字段必填。

Mode integer 必选示例值：1

节点匹配方式。

1：按节点

2：按节点组

3：按分组

LineConfig object 可选示例值：--

按节点选择配置。

Groups integer[] 必选示例值：[6]

分组方式。

1：按节点ID

2：按节点类型

3：按国家

4：按省份

5：按城市

6：按运营商

7：按PrivateRunnerID

8：按PrivateRunnerName

9：按LabelKey

10：按区域

LineList object[] 必选示例值：--

如果未分组，则使用节点列表。

Id long 必选示例值：274

节点ID。

Name string 可选示例值：中国-重庆-重庆-移动（IDC）

节点名称。

NodeCount long 必选示例值：1

样本数量。

GroupList object[] 必选示例值：--

如果分组，则使用分组列表。

Name string 必选示例值：中国移动

分组名称。

NodeCount long 必选示例值：1

样本数量。

GroupConfig object 可选示例值：--

按分组选择配置。

Groups integer[] 必选示例值：[6]

分组方式。

1：按节点ID

2：按节点类型

3：按国家

4：按省份

5：按城市

6：按运营商

7：按PrivateRunnerID

8：按PrivateRunnerName

9：按LabelKey

10：按区域

GroupList object[] 必选示例值：--

右侧已选分组列表。

Name string 必选示例值：中国移动

分组名称。

NodeCount long 必选示例值：1

样本数量。

LineGroupConfig object 可选示例值：--

按节点组选择配置。

Groups integer[] 必选示例值：[6]

分组方式。

1：按节点ID

2：按节点类型

3：按国家

4：按省份

5：按城市

6：按运营商

7：按PrivateRunnerID

8：按PrivateRunnerName

9：按LabelKey

10：按区域

LineList object[] 必选示例值：--

如果未分组，则使用节点列表。

Id long 必选示例值：274

节点ID。

Name string 可选示例值：中国-重庆-重庆-移动（IDC）

节点名称。

NodeCount long 必选示例值：1

样本数量。

GroupList object[] 必选示例值：--

如果分组，则使用分组列表。

Name string 必选示例值：中国移动

分组名称。

NodeCount long 必选示例值：1

样本数量。

LineGroupList object[] 必选示例值：--

选择的节点组列表。

Id long 必选示例值：100

节点组ID。

Name string 可选示例值：Name

节点组名称。

DnsConfig object 可选示例值：--

DNS任务配置，DNS任务必填该项

Timeout integer 可选示例值：5

超时时间。单位：秒（s）。取值范围：(0,45)。默认值：5。

SearchType integer 可选示例值：1

查询方式。可选值：

1（默认）：递归

2：迭代

Server string 可选示例值：dns.example.com

DNS服务器地址。

ServerType integer 可选示例值：3

DNS服务器类型。可选值：

1：IPv4

2：IPv6

3：自动

默认值：3。

EnableDig boolean 可选示例值：true

是否使用dig命令格式检测结果。默认值：true。

RecordType integer 可选示例值：1

指定查询的记录类型。可选值：

1：A

2：AAAA

3：CNAME

4：MX

5：TXT

6：PTR

不设置时会自动根据TargetServerType（目标服务器类型）来指定A或者AAAA。

TargetServerType integer 可选示例值：1

目标服务器IP类型。

1：IPv4

2：IPv6

3：自动

TcpConfig object 可选示例值：--

TCP任务配置，TCP任务必填该项

PayloadType integer 必选示例值：1

表示负载内容格式：

1：十六进制编码

2：文本

Payload string 可选示例值："Hello, World!" 或 "48656c6c6f20576f726c6421"（二进制内容的hex编码）

负载内容。文本内容可以直接填写，二进制内容需要按hex格式编码。

Timeout integer 可选示例值：10

监控超时时间。单位：秒（s）。默认值：10。

UdpConfig object 可选示例值：--

UDP任务配置，UDP任务必填该项

Timeout integer 可选示例值：10

监控超时时间。单位：秒（s）。

PayloadType integer 必选示例值：1

负载内容格式，可选值：

1：十六进制编码

2：文本

Payload string 可选示例值："Hello, World!" 或 "48656c6c6f20576f726c6421"（二进制内容的hex编码）

负载内容。文本内容可以直接填写，二进制内容需要按hex格式编码。

Mode integer 可选示例值：0

模式，取值：

0：默认模式，拨测节点向目标地址发送 UDP 数据包，需对端返回对应的 UDP 数据包才算检测正常。

1：扫描模式，仅检测对端端口是否处于开放状态。

AlarmIdList long[] 可选示例值：100107753

告警策略ID列表。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

LocationInfo object 示例值：--

地理位置信息。

Continent string 示例值：""

大洲。

Country string 示例值：""

国家。

Province string 示例值：""

省份。

City string 示例值：""

城市。

Isp string 示例值：""

运营商。

TaskId long 示例值：23275831

拨测任务ID。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
200	AccessDenied	User is not authorized to perform: cloud_detect:{Action} on resource:	无权限进行此操作及对应资源。

最近更新时间：2026.02.13 11:09:20

这个页面对您有帮助吗？

有用

无用