CreateSiteMonitor - CloudMonitor - Alibaba Cloud Documentation Center

Creates a site monitoring task.

Operation description

This topic describes how to create a site monitoring task. The example creates a task named HanZhou_ECS1 to monitor the URL https://www.aliyun.com over HTTPS.

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:CreateSiteMonitor

create

*All Resource

*

None

Request parameters

Parameter	Type	Required	Description	Example
Address	string	Yes	The URL or IP address to monitor.	https://www.aliyun.com
TaskType	string	Yes	The type of monitoring task. Valid protocols include HTTP(S), PING, TCP, UDP, DNS, SMTP, POP3, FTP, and WEBSOCKET.	HTTP
TaskName	string	Yes	The name of the monitoring task. The name must be 4 to 100 characters long and can contain letters, digits, underscores (_), and Chinese characters.	HanZhou_ECS1
Interval	string	No	The monitoring frequency in minutes. Valid values: 1, 5, 15, 30, and 60. Default: 1.	1
IspCities	string	No	The detection points. If you do not specify this parameter, the system randomly selects three detection points from different Internet Service Providers (ISPs). The value must be a JSON array. Example: `[{"city":"546","isp":"465"},{"city":"572","isp":"465"},{"city":"738","isp":"465"}]`. The values correspond to Beijing, Hangzhou, and Qingdao. For more information, see DescribeSiteMonitorISPCityList.	[{"city":"546","isp":"465"},{"city":"572","isp":"465"},{"city":"738","isp":"465"}]
OptionsJson	string	No	The advanced options for the specified protocol. The available options vary based on the protocol type.	{"time_out":5000}
AlertIds	string	No	The ID of the alert rule. For more information, see DescribeMetricRuleList.	SystemDefault_acs_ecs_dashboard_InternetOutRate_Percent
AgentGroup	string	No	The group of detection points for the network probe task. `PC` indicates detection points on PCs. `MOBILE` indicates detection points on mobile devices. `FC` indicates detection points in a VPC. The default value is `PC`.	PC
CustomSchedule	string	No	The custom detection schedule. Specify a time period and the days of the week for detection.	{"start_hour":0,"end_hour":24, "days":[0], "time_zone":"Local"}
VpcConfig	string	No	The network information required to create a network probe task in a VPC. This must be a JSON object that contains the `vpcId`, `vswitchId`, `securityGroupId`, and `region` fields.	{"vpcId": "vpc-xxxxxx", "vswitchId": "vsw-xxxxxx", "securityGroupId": "sg-xxxxxx", "region": "cn-beijing"}

The following tables describe the advanced parameters for the HTTP(S), PING, TCP, UDP, DNS, WEBSOCKET, SMTP, POP3, and FTP task types.

HTTP(S)

Parameter	Type	Description
http_method	String	The HTTP or HTTPS request method. Valid values: GET, POST, and HEAD. Default: GET.
header	String	The custom HTTP header. Separate multiple headers with line feeds (\n). Each header must be in `key:value` format and follow the HTTP protocol.
cookie	String	The cookie, formatted as a standard HTTP request cookie.
request_content	String	The request content, in JSON or form format. If you do not specify this parameter, the request body is empty.
response_content	String	The expected response content. The system checks the first 64 bytes of the server's response.
match_rule	String	0: The probe is successful if the response does not contain the response_content value. 1: The probe is successful if the response contains the response_content value.
username	String	The username for Basic authentication. If specified, a `BasicAuth` header is included in the HTTP request.
password	String	The password for Basic authentication.
time_out	int	The timeout period in milliseconds. Default: 5000.
max_redirect	int	The maximum number of redirects. Default: 5 for ECS detection points and 2 for carrier detection points. Set to 0 to disable redirects. Valid values: 0 to 50.

PING

Parameter	Type	Description
failure_rate	Text	The failure rate threshold. If the ping failure rate exceeds this value, the probe fails and returns error code 610 (PingAllFail) or 615 (PingPartialFail). Default: 0.1.
ping_num	int	The number of ping packets to send. Default: 10. Valid values: 1 to 100.

Parameter	Type	Description
dns_server	string	The address of the DNS server. This can be a domain name or an IP address.
dns_type	string	The DNS query type. Valid values: A, NS, CNAME, MX, TXT, ANY, and AAAA.
expect_value	string	A space-separated list of expected values.
match_rule	string	The matching rule between the expected values and the DNS query results. The probe fails if this rule is not met. `IN_DNS` or empty string: The expected values must be a subset of the DNS results. `DNS_IN`: The DNS results must be a subset of the expected values. `EQUAL`: The DNS results must be identical to the expected values. `ANY`: The DNS results and the expected values must have at least one value in common.

Parameter	Type	Description
port	int	The FTP server port. Default: 21 for FTP and 990 for FTPS.
username	string	The username for FTP login. If not specified, anonymous login is used.
password	string	The password for FTP login.

POP3 or SMTP

Parameter	Type	Description
port	int	The server port. Default: 110 for POP3, 995 for POP3S, and 25 for SMTP.
username	string	The username for POP3 or SMTP login. Both username and password are required.
password	string	The password for POP3 or SMTP login. Both username and password are required.

TCP or UDP

Parameter	Type	Description
port	int	The TCP or UDP server port.
request_content	string	The request content. If `request_format` is `hex`, this value must be in compact hexadecimal format.
request_format	string	The format of the request content. If this is not `hex`, the `request_content` is sent as a regular string.
response_content	string	The expected response content. The probe fails if the server response does not contain this value. If `request_format` is `hex`, this value must be in compact hexadecimal format. Otherwise, it is treated as a regular string.

WEBSOCKET

Parameter	Type	Description
request_content	string	The message content to send.
empty_message	boolean	Specifies whether an empty message or no message from the server is considered a success.

Response elements

Element	Type	Description	Example
	object
Code	string	The status code of the operation. Note A value of `200` indicates success.	200
Message	string	The message returned for the request.	Successful
RequestId	string	The ID of the request.	68192f5d-0d45-4b98-9724-892813f86c71
Success	string	Indicates whether the request was successful. Valid values: true: The request was successful. false: The request failed.	true
Data	object	The results of the monitoring task.
AttachAlertResult	object
Contact	array<object>	The results of associating the alert rules.
	object	The result for a single alert rule association.
Code	string	The status code for the association operation. Note A value of `200` indicates success.	200
Message	string	The message returned for the association operation.	successful
RequestId	string	The request ID for the association operation.	5dd33455-4f65-4b0c-9200-33d66f3f340b
Success	string	Indicates whether the alert rule was successfully associated. Valid values: true: The association was successful. false: The association failed.	true
RuleId	string	The ID of the alert rule.	SystemDefault_acs_ecs_dashboard_InternetOutRate_Percent
CreateResultList	object
CreateResultList	array<object>	A list of results for each created task. This is returned only if the task creation is successful.
	object	The result for a single created task. This is returned only if the task creation is successful.
TaskId	string	The ID of the created monitoring task.	2c8dbdf9-a3ab-46a1-85a4-f094965e****
TaskName	string	The name of the created monitoring task.	HanZhou_ECS1

Examples

Success response

JSON format

{
  "Code": "200",
  "Message": "Successful",
  "RequestId": "68192f5d-0d45-4b98-9724-892813f86c71",
  "Success": "true",
  "Data": {
    "AttachAlertResult": {
      "Contact": [
        {
          "Code": "200",
          "Message": "successful",
          "RequestId": "5dd33455-4f65-4b0c-9200-33d66f3f340b",
          "Success": "true",
          "RuleId": "SystemDefault_acs_ecs_dashboard_InternetOutRate_Percent"
        }
      ]
    }
  },
  "CreateResultList": {
    "CreateResultList": [
      {
        "TaskId": "2c8dbdf9-a3ab-46a1-85a4-f094965e****",
        "TaskName": "HanZhou_ECS1"
      }
    ]
  }
}

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	NameRepeat	Task name repeat
400	CreateAlarmError	Create alarm error
400	NameNotExists	Task name not exists
400	OperatorCityInvalid	Invalid Isp.	Invalid Isp
401	AccessDeniedException	You donot have sufficient access to perform this action.
500	InternalError	The request processing has failed due to some unknown error.
402	LimitExceeded	The quota for this customer had been reached.
403	Forbidden	%s
403	RestrictedUser	The user's operation is restricted, please register NAAM product code
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.