CreateInstantSiteMonitor - Cloud Monitor - Alibaba Cloud Documentation Center

Call the CreateInstantSiteMonitor operation to create a one-time detection task.

Operation description

Only Alibaba Cloud accounts that have Network Analysis and Monitoring activated can create one-time detection tasks.

This topic provides an example of how to create a one-time detection task. The example creates a task named task1 that detects the address 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 must be 4 to 100 characters in length and can contain letters, digits, and underscores (_).	task1
IspCities	string	No	The detection points. If you do not specify this parameter, the system randomly selects three detection points. The value must be a JSON array. 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, valid values for type are IDC and LASTMILE. IDC indicates that the detection point is deployed in a data center. LASTMILE indicates that the detection point is deployed on the PC of a netizen that is connected to the last mile of an ISP network. The type parameter is optional. The default value is IDC. You do not need to specify this parameter if AgentGroup is set to MOBILE. For more information about how to obtain detection points, 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 type of the detection task. The extended options vary based on the protocol type.	{"time_out":5000}
RandomIspCity	integer	No	The number of detection points. Note You must specify either `IspCities` or `RandomIspCity`. If you specify `RandomIspCity`, `IspCities` 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 (:) in compliance with HTTP.
cookie	String	The cookie. The format must be the same as the format of standard HTTP request cookies.
request_content	String	The request body. JSON and form formats are supported. If you do not specify this parameter, the request does not contain a body.
response_content	String	The expected response. During a detection, the first 64 bytes of the response returned by the HTTP server are checked.
match_rule	String	0: The detection is successful if the response does not contain the value of response_content. 1: The detection is successful if the response contains the value of response_content.
username	String	If you specify a username, the BasicAuth header is carried 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. In this case, 610 (PingAllFail) or 615 (PingPartialFail) is returned. 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, the value of request_content must be in the compact hexadecimal format.
request_format	string	If request_format is set to a value other than hex, the value of request_content is sent to the TCP or UDP server as a common string.
response_content	string	The response. The detection fails if the response returned by the TCP or UDP server does not contain the value of response_content. If response_format is set to hex, the value of response_content must be in the compact hexadecimal format. If response_format is set to a value other than hex, the value of response_content is a common string.

Parameter	Type	Description
dns_server	string	The address of the DNS server. The value can be a domain name or an IP address.
dns_type	string	The DNS query type. Valid values: A, NS, CNAME, MX, TXT, and ANY.
expect_value	string	The list of expected values. Separate multiple values with spaces.
match_rule	string	The relationship between the list of expected values and the DNS list. The detection fails if the specified 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.

Response elements

Element	Type	Description	Example
	object
Code	string	The status code. Note A value of 200 indicates that the call is 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 the one-time detection task.
	object	The results of the one-time detection task.
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.