Skip to content

Create a Dial Testing Task¶

POST /api/v1/dialing_task/add

Overview¶

Body Request Parameters¶

Parameter Name	Type	Required	Description
type	string	Y	Dial Testing type Can be empty: false $lowerIn: ['http', 'tcp', 'dns', 'browser', 'icmp', 'websocket']
regions	array	Y	Region list Can be empty: false
task	json	Y	Task configuration Can be empty: false $maxDictLength: 20000
task.url	string	Y	URL Can be empty: false
task.method	string	N	Optional when type is browser Can be empty: false
task.name	string	Y	Task name Can be empty: false
task.frequency	string	Y	Dial Testing frequency Can be empty: false Options: ['1m', '5m', '15m', '30m', '1h', '6h', '12h', '24h']
task.advance_options	json	N	Advanced options Can be empty: false
task.advance_options_headless	json	N	Advanced options setting for browser Can be empty: false
task.success_when_logic	string	N	Logical relationship within success_when conditions, default is `and` Can be empty: false Options: ['and', 'or']
task.success_when	array	Y	Success_when Can be empty: false
task.enable_traceroute	boolean	N	Traceroute Can be empty: false
task.packet_count	integer	N	Number of pings sent each time Can be empty: false
task.host	string	Y	Required when type=tcp/icmp Can be empty: false
task.port	string	Y	Required when type=tcp Can be empty: false
task.timeout	string	N	Optional when type=tcp/icmp Can be empty: false
task.message	string	Y	Required when type=websocket Can be empty: false
task.post_mode	string	N	Availability judgment mode Default-default Script-mode-script Can be empty: false
task.post_script	string	N	Script content Can be empty: false Allow empty string: true
tags	array	N	List of tag names Can be empty: false Example: ['xx', 'yy']

Additional Parameter Explanation¶

Data Description.

Parameter Name	Type	Required	Description
type	string	Y	Dial Testing type, options: `http`, `tcp`, `dns`, `browser`, `icmp`, `websocket`
regions	array	Y	Task execution region
task	json	Y	Task details
task.name	string	Y	Task name
task.url	string	Y	URL
task.method	string	Y	URL request method
task.status	string	Y	Task status, options: `ok`, `stop`
task.frequency	string	Y	Task frequency
task.advance_options	json	N
task.success_when_logic	enum	N	Options: [`and`, `or`], logical relationship within success_when parameters, default is `and`
task.success_when	array	Y/N	Required when type=http, optional when type=browser
task.enable_traceroute	boolean	N	Optional when type=tcp/icmp
task.packet_count	integer	N	Optional when type=icmp
task.host	string	Y	Required when type=tcp/icmp
task.port	string	Y	Required when type=tcp
task.timeout	string	N	Optional when type=tcp/icmp
task.message	string	Y/N	Required when type=websocket
task.post_mode	string	N	Availability judgment mode Default-default Script-mode-script
task.post_script	string	N	Availability judgment script content
tags	array	N	Tag list

Note: For detailed information about the internal parameters of the dial testing task task, refer to Custom Dial Testing ¶

{
  "regions": ["us", "singapore"],
  "task": {
    "url": "http://example.com/some/api",
    "method": "POST",
    "external_id": "ID defined by external system for this task",
    "post_url": " Provided by Studio backend https://dataway.cn?token=tkn_xxx",
    "status": "ok/stop",
    "name": "Task Naming",
    "frequency": "1m",
    "regions": "beijing",
    "advance_options": {
      "request_options": {
        "follow_redirect": true,
        "headers": {
          "header1": "value1",
          "header2": "value2"
        },
        "cookies": "",
        "auth": {
          "username": "",
          "password": ""
        }
      },
      "request_body": {
        "body_type": "text/plain|application/json|text/xml",
        "body": ""
      },
      "certificate": {
        "ignore_server_certificate_error": false,
        "private_key": "",
        "certificate": ""
      },
      "proxy": {
        "url": "",
        "headers": {
          "header1": "value1"
        }
      }
    },
    "success_when_logic": "and",
    "success_when": [
      {
        "body": {
          "contains": "",
          "not_contains": "",
          "is": "",
          "is_not": "",
          "match_regex": "",
          "not_match_regex": ""
        },
        "header": {
          "header-name": {
            "contains": "",
            "not_contains": "",
            "is": "",
            "is_not": "",
            "match_regex": "",
            "not_match_regex": ""
          },
          "another-header-name": "..."
        },
        "response_time": "100ms",
        "status_code": [
          { "is": "200" },
          { "is_not": "400" },
          { "match_regex": "ok*" },
          { "not_match_regex": "*bad" }
        ]
      },
      {
        "AND_another_assert": "..."
      }
    ]
  },
  "tags": ["Tag Name"]
}

_ Explanation of task.frequency parameter _
The time frequency range for Free Plan workspaces is 30m/1h/6h/12h/24h

Request Example¶

curl 'https://us1-openapi.truewatch.com/api/v1/dialing_task/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"type":"http","regions":["reg_xxxx20"],"task":{"frequency":"1m","method":"GET","url":"https://www.google.com","name":"test","advance_options":{"request_options":{"follow_redirect":false,"headers":{},"cookies":"","auth":{"username":"","password":""}},"request_body":{"body_type":"","body":""},"secret":{"not_save":false}},"success_when":[{"body":[{"contains":"200"}]}],"success_when_logic":"and"},"tags":["test"]}' \
--compressed

Response¶

{
    "code": 200,
    "content": {
        "createAt": 1686193610,
        "creator": "acnt_xxxx32",
        "deleteAt": -1,
        "id": null,
        "regions": [
            "reg_xxxx20"
        ],
        "status": 0,
        "tagInfo": [
            {
                "id": "tag_xxxx32",
                "name": "test"
            }
        ],
        "task": {
            "advance_options": {
                "request_body": {
                    "body": "",
                    "body_type": ""
                },
                "request_options": {
                    "auth": {
                        "password": "",
                        "username": ""
                    },
                    "cookies": "",
                    "follow_redirect": false,
                    "headers": {}
                },
                "secret": {
                    "not_save": false
                }
            },
            "external_id": "dial_xxxx32",
            "frequency": "1m",
            "method": "GET",
            "name": "test",
            "owner_external_id": "wksp_xxxx32",
            "post_url": "http://testing-openway.truewatch.com?token=tkn_xxxxx",
            "status": "ok",
            "tagInfo": [],
            "success_when": [
                {
                    "body": [
                        {
                            "contains": "200"
                        }
                    ]
                }
            ],
            "success_when_logic": "and",
            "url": "https://www.google.com"
        },
        "type": "http",
        "updateAt": 1686193610,
        "updator": "acnt_xxxx32",
        "uuid": "dial_xxxx32",
        "workspaceUUID": "wksp_xxxx32"
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "712401530723551303"
}