CreateInstantSiteMonitor - Cloud Monitor - Alibaba Cloud Documentation Center

This operation creates a one-off detection task.

Operation description

Only Alibaba Cloud accounts with Network Analysis and Monitoring activated can create one-off detection tasks.

This topic provides an example of how to create a one-off detection task. In this example, the task is named task1, the detection address is http://www.aliyun.com, the detection type is HTTP, and the number of detection points is 1.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

cms:CreateInstantSiteMonitor

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
Address	string	Yes	The URL or IP address of the detection task.	http://www.aliyun.com
TaskType	string	Yes	The type of the detection task. Valid values: HTTP, PING, TCP, UDP, and DNS.	HTTP
TaskName	string	Yes	The name of the detection task. The name of the detection task.	task1
IspCities	string	No	The information about the detection points. If you do not specify this parameter, the system randomly selects three detection points. The value is a `JSONArray`. Example: [{"city":"546","isp":"465", "type":"IDC"},{"city":"572","isp":"465", "type":"LASTMILE"},{"city":"738","isp":"465"}]. These values correspond to Beijing, Hangzhou, and Qingdao. The type parameter specifies the type of the detection point. If AgentGroup is set to PC, you can set type to IDC or LASTMILE. IDC indicates that the detection point is deployed in a data center. LASTMILE indicates that the detection point is deployed on a PC that is connected to the last mile of an Internet Service Provider (ISP) network. The type parameter is optional. Default value: IDC. If AgentGroup is set to MOBILE, you do not need to specify the type parameter. For more information about how to obtain detection point information, see DescribeSiteMonitorISPCityList. Note You must specify either `IspCities` or `RandomIspCity`.	[{"city":"546","isp":"465"},{"city":"572","isp":"465"},{"city":"738","isp":"465"}]
OptionsJson	string	No	The extended options for the protocol of the detection task. The options vary based on the protocol.	{"time_out":5000}
RandomIspCity	integer	No	The number of detection points. Note You can specify either `IspCities` or `RandomIspCity`. If you specify `RandomIspCity`, the `IspCities` parameter is ignored.	1
AgentGroup	string	No	The type of the detection points. Valid values: PC and MOBILE. PC indicates detection points on PCs. MOBILE indicates detection points on mobile devices. Default value: PC.	PC

Advanced parameters for TaskType

The following tables describe the advanced parameters for the HTTP, PING, TCP, UDP, and DNS detection tasks.

HTTP

Parameter	Type	Description
http_method	String	The HTTP request method. Valid values: GET, POST, and HEAD. Default value: GET.
header	String	The custom HTTP header. Use line feeds (\n) to separate multiple headers. Each header must be a key-value pair separated by a colon (:) and must follow the HTTP protocol.
cookie	String	The cookie. The format must be the same as the format of a standard HTTP request cookie.
request_content	String	The request body. Valid formats: JSON and form. If you do not specify this parameter, the request does not have a body.
response_content	String	The expected response content. During a detection, the system checks the first 64 bytes of the response from the HTTP server.
match_rule	String	0: The detection is successful if the response does not contain response_content. 1: The detection is successful if the response contains response_content.
username	String	If you specify a username, the system includes a BasicAuth header in the HTTP request.
password	String	The password for HTTP authentication.
time_out	int	The timeout period. Unit: milliseconds. Default value: 30000.
max_redirect	int	The maximum number of redirects. The default value is 5 for ECS probes and 2 for carrier probes. To disable redirects, set this parameter to 0. Valid values: 0 to 50.

PING

Parameter	Type	Description
failure_rate	int	If the ping failure rate exceeds the value of this parameter, the detection fails. The system returns 610 (PingAllFail) or 615 (PingPartialFail). Default value: 0.1.
ping_num	int	The number of pings. Default value: 20. Valid values: 1 to 100.

TCP or UDP

Parameter	Type	Description
port	int	The port of the TCP or UDP server.
request_content	string	The request body. If request_format is set to hex, request_content must be in the compact hexadecimal format.
request_format	string	If request_format is set to a value other than hex, request_content is sent as a regular string to the TCP or UDP server.
response_content	string	The response content. The detection fails if the response from the TCP or UDP server does not contain response_content. If request_format is set to hex, response_content must be in the compact hexadecimal format. If request_format is set to a value other than hex, response_content is a regular string.

Parameter	Type	Description
dns_server	string	The address of the DNS server. The address can be a domain name or an IP address.
dns_type	string	The type of the DNS query. Valid values: A, NS, CNAME, MX, TXT, and ANY.
expect_value	string	A list of expected values separated by spaces.
match_rule	string	The relationship between the list of expected values and the DNS list. The detection fails if the relationship is not met. Empty string or IN_DNS: The list of expected values is a subset of the DNS list. DNS_IN: The DNS list is a subset of the list of expected values. EQUAL: The DNS list is the same as the list of expected values. ANY: The DNS list and the list of expected values have an intersection. The intersection is not empty.

Response elements

Element	Type	Description	Example
	object
Code	string	The status code. Note A value of 200 indicates that the request was successful.	200
Message	string	The returned message.	successful
RequestId	string	The request ID.	68192f5d-0d45-4b98-9724-892813f86c71
Success	string	Indicates whether the operation was successful. Valid values: true: The operation was successful. false: The operation failed.	true
CreateResultList	array<object>	The results of creating the one-off detection tasks.
	object	The results of creating the one-off detection tasks.
TaskId	string	The ID of the detection task.	2c8dbdf9-a3ab-46a1-85a4-f094965e****
TaskName	string	The name of the detection task.	task1

Examples

Success response

JSON format

{
  "Code": "200",
  "Message": "successful",
  "RequestId": "68192f5d-0d45-4b98-9724-892813f86c71",
  "Success": "true",
  "CreateResultList": [
    {
      "TaskId": "2c8dbdf9-a3ab-46a1-85a4-f094965e****",
      "TaskName": "task1"
    }
  ]
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidQueryParameter	%s
400	IllegalAddress	Illegal HTTP address
400	OperationError	Operation failed
400	TaskNotExists	Task does not exist
400	OperatorInvalid	Operator invalid
400	OperatorCityInvalid	Operator City invalid
400	NameRepeat	Task name repeat
400	CreateAlarmError	Create alarm error
400	NameNotExists	Task name not exists
400	Illegal Task Name	The task name of the sitemonitor task is illegal.	Site monitoring task name is illegal.
401	AccessDeniedException	You donot have sufficient access to perform this action.
500	InternalError	%s
402	LimitExceeded	The quota for this customer had been reached.
403	%s	%s
403	Forbidden	%s
503	%s	%s
406	ExceedingQuota	Exceeding quota limits.	The number of tasks exceeds the limit
409	%s	%s

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.