Querying Alarm Rules (V1)

Function

This API is used to query alarm rules. You can specify the paging parameters to limit the number of query results displayed on a page. You can also set the sorting order of query results. When you use this API to query alarm rules for multiple resources and policies, it returns only one alarm policy. In this case, use Querying Alarm Rules (Recommended) and the console functions together.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ces:alarms:list

List

-

g:EnterpriseProjectId

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
ces:alarms:list	List	-	g:EnterpriseProjectId	-	-

URI

GET /V1.0/{project_id}/alarms

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. It is used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID from the API or console. For details, see Obtaining a Project ID. Constraints N/A Range 1 to 64 characters. Default Value N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
start	No	String	Definition Pagination start value. The value is alarm_id. Constraints N/A Range The value starts with al and is followed by 22 characters of letters, digits, or a combination of both. The value can contain a total of 24 characters. Default Value N/A
limit	No	Integer	Definition Number of records that can be returned. Constraints N/A Range (0,100] Default Value 100
order	No	String	Definition Result sorting method, which is sorted by creation time. Constraints N/A Range Enumeration values: asc: ascending order. desc: descending order. Default Value desc
enterprise_project_id	No	String	Definition Enterprise project ID. To query all enterprise projects, set this parameter to all_granted_eps . To query a specific enterprise project, set this parameter to the ID of that enterprise project. For details, see Obtaining a Project ID. Constraints N/A Range The value contains 36 characters. It can only contain lowercase letters, digits, hyphens (-), and underscores (_). The value can also be 0 (the default enterprise project) or all_granted_eps (all enterprise projects). Default Value all_granted_eps

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Constraints N/A Range 1 to 64 characters Default Value Default value application/json; charset=UTF-8 is recommended. For APIs used to upload objects or images, the MIME type varies with the flow type.
X-Auth-Token	No	String	Definition User token. Constraints N/A Range 1 to 16,384 characters Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
metric_alarms	Array of MetricAlarmsResp objects	Definition List of queried alarm objects.
meta_data	MetaDataResp object	Definition Metadata of query results, including the pagination information.

**Table 5** MetricAlarmsResp
Parameter	Type	Description
alarm_name	String	Definition Alarm name. Range The value allows 1 to 128 characters and can only contain digits, letters, underscores (_), and hyphens (-).
alarm_description	String	Definition Alarm description. Range N/A
relation_id	String	Definition Alarm rule ID or resource group ID. Range N/A
metric	ListAlarmMetricResp object	Definition Metric information in the created rule.
condition	AlarmRuleConditionResp object	Definition Alarm policy configured in the alarm rule.
alarm_enabled	Boolean	Definition Whether to enable the alarm rule. Range A boolean value. true: enabled. false: disabled.
alarm_level	Integer	Definition Alarm severity. Range The value can be: 1: critical. 2: major. 3: minor. 4: warning.
alarm_type	String	Definition Alarm type. Range For event alarms, the alarm type is EVENT.SYS (system events) or EVENT.CUSTOM (custom events). For alarms generated for resource groups, the alarm type is RESOURCE_GROUP. For alarms generated for specific resources, the alarm type is MULTI_INSTANCE. EVENT.SYS: The alarm rule is created for system events. EVENT.CUSTOM: The alarm rule is created for custom events. RESOURCE_GROUP: The alarm rule is created for resource groups. MULTI_INSTANCE: The alarm rule is created for specific resources.
alarm_action_enabled	Boolean	Definition Whether to enable alarm notifications when the alarm is triggered. Range A boolean value. true: enabled. false: disabled.
ignore_insufficient_data	Boolean	Definition Whether to generate an alarm record due to insufficient data (no notification is sent). Range The value can be: true: An alarm record is generated due to insufficient data. false: No alarm record is generated due to insufficient data.
alarm_actions	Array of NotificationResp objects	Definition Information about the notification group or topic subscription when an alarm is triggered. A structure example is as follows: {"type": "notification", "notificationList": ["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] }
ok_actions	Array of NotificationResp objects	Definition Information about the notification group or topic subscription when the alarm is cleared. An example structure is as follows: { "type": "notification", "notificationList": ["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] }
insufficientdata_actions	Array of NotificationResp objects	Definition Notification group or topic subscription when an alarm notification is triggered due to insufficient data. A structure example is as follows: {"type": "notification", "notificationList": ["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] }
alarm_action_begin_time	String	Definition Time when an alarm rule is applied. Notifications are sent only within the validity period of the alarm rule. For example, if alarm_action_begin_time is set to 08:00 and alarm_action_end_time is set to 20:00, notifications are sent only from 08:00 to 20:00. Range The value allows 1 to 64 characters and can only contain digits and colons (:).
alarm_action_end_time	String	Definition Time when an alarm rule becomes invalid. For example, if alarm_action_begin_time is set to 08:00 and alarm_action_end_time is set to 20:00, notifications are sent only from 08:00 to 20:00. Range The value allows 1 to 64 characters and can only contain digits and colons (:).
effective_timezone	String	Definition Time zone, for example, GMT-08:00, GMT+08:00, or GMT+0:00. Range 1 to 16 characters
alarm_id	String	Definition Alarm rule ID. Range The value starts with al and is followed by 22 characters that may include letters, digits, or a combination of both. The value can contain a total of 24 characters.
update_time	Long	Definition Time when the alarm status changed. The value is a UNIX timestamp in milliseconds. Range 0 - 9999999999999
alarm_state	String	Definition Alarm status. Range The value can only be ok, alarm, or insufficient_data. ok: normal. alarm: active. insufficient_data: insufficient data.
enterprise_project_id	String	Definition Enterprise project ID. Range The value allows 36 characters and can only contain lowercase letters, digits, hyphens (-), and underscores (_). The value can also be 0 (default enterprise project ID) or all_granted_eps (all enterprise project IDs).

**Table 6** ListAlarmMetricResp
Parameter	Type	Description
namespace	String	Definition Metric namespace. For example, the ECS namespace is SYS.ECS , and the DDS namespace is SYS.DDS . For details, see Services Interconnected with Cloud Eye. Range The value is in the service.item format and allows 3 to 32 characters. The values of service and item must start with a letter and contain only letters, digits, and underscores (_).
dimensions	Array of DimensionResp objects	Definition Metric dimension. A maximum of four dimensions can be added.
metric_name	String	Definition Metric name of the resource. For example, the ECS metric cpu_util indicates the CPU usage of an ECS. The DDS metric mongo001_command_ps indicates the command execution frequency. For details about the metric names of each service, see their documentation. You can navigate there from Services Interconnected with Cloud Eye. Range The value must start with a letter and allow 1 to 96 characters. It can only contain letters, digits, and underscores (_).
resource_group_id	String	Definition ID of the resource group selected during the alarm rule creation, for example, rg1603786526428bWbVmk4rP. Range The value can contain 1 to 64 characters and can only contain letters, digits, hyphens (-), and underscores (_).
resource_group_name	String	Definition Name of the resource group selected during the alarm rule creation, for example, Resource-Group-ECS-01. Range 0 to 128 characters

**Table 7** DimensionResp
Parameter	Type	Description
name	String	Definition Monitoring dimension name. For example, the dimension of an ECS is instance_id . For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye. Range The value must start with a letter and can only contain letters, digits, underscores (_), and hyphens (-). 1 to 32 characters.
value	String	Definition Monitoring dimension value, for example, the ECS ID. Range [0,256]

**Table 8** AlarmRuleConditionResp
Parameter	Type	Description
comparison_operator	String	Definition Threshold symbol. Range The value can be >, <, >=, <=, =, !=, cycle_decrease, cycle_increase, or cycle_wave. cycle_decrease indicates the decrease relative to the last period. cycle_increase indicates the increase relative to the last period. cycle_wave indicates the increase or decrease relative to the last period.
count	Integer	Definition Number of consecutive times that an alarm is triggered. Range An integer ranging from 1 to 5.
filter	String	Definition Data aggregation method. Range The value can be: average: average value variance min: minimum value max: maximum value sum
period	Integer	Definition Metric period, in seconds. For details about the original metric period for each cloud service, see Services Interconnected with Cloud Eye. 0: The alarm is triggered immediately. This value applies only to event scenarios. 1: original metric period. For example, if the original period of an RDS metric is 60s, the metric data is collected and calculated every 60s. 300: The metric data is collected and calculated every 5 minutes. 1200: The metric data is collected and calculated every 20 minutes. 3600: The metric data is collected and calculated every hour. 14400: The metric data is collected and calculated every 4 hours. 86400: The metric data is collected and calculated every day. Range The value can be:
unit	String	Definition Original data unit. Range 0 to 32 characters.
selected_unit	String	Definition Data unit. Range 0 to 32 characters.
value	Number	Definition Alarm threshold. For detailed thresholds, see the value range of each metric in the appendix. For example, you can set ECS cpu_util in Services Interconnected with Cloud Eye to 80 . Range -1.7976931348623157e+108 to 1.7976931348623157e+108
suppress_duration	Integer	Definition Alarm suppression duration, in seconds. This parameter corresponds to the last field in the alarm policy when you create an alarm rule. This field is used to mitigate frequent alarm occurrences. Range The value can be: 0: A metric alarm is generated only once. An event alarm is not suppressed in the immediate triggering scenario, and is generated only once in the accumulated triggering scenario. 300: An alarm is generated every 5 minutes once the alarm triggering condition is met. 600: An alarm is generated every 10 minutes once the alarm triggering condition is met. 900: An alarm is generated every 15 minutes once the alarm triggering condition is met. 1800: An alarm is generated every 30 minutes once the alarm triggering condition is met. 3600: An alarm is generated every 60 minutes once the alarm triggering condition is met. 10800: An alarm is generated every 3 hours once the alarm triggering condition is met. 21600: An alarm is generated every 6 hours once the alarm triggering condition is met. 43200: An alarm is generated every 12 hours once the alarm triggering condition is met. 86400: An alarm is generated once every day once the alarm triggering condition is met.

**Table 9** NotificationResp
Parameter	Type	Description
type	String	Definition Alarm notification type. Range notification: notification groups or topic subscriptions. autoscaling: AS notifications. This value is used only for AS.
notificationList	Array of strings	Definition Recipients to be notified of the alarm status changes.

**Table 10** MetaDataResp
Parameter	Type	Description
count	Integer	Definition Number of records that can be returned. Range 0 - 2147483647
total	Integer	Definition Total number of query results. Range 0 - 2147483647
marker	String	Definition Start of the next page, which is used for pagination. For example, you have queried 10 records this time and alarm_id of the tenth record is al1441967036681YkazZ0deN. In your next query, you can set start to al1441967036681YkazZ0deN to begin from the subsequent alarm rule ID. Range 1–9999

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
-	String	Request error.

Status code: 401

**Table 12** Response body parameters
Parameter	Type	Description
-	String	The authentication information is not provided or is incorrect.

Status code: 403

**Table 13** Response body parameters
Parameter	Type	Description
-	String	Access to the requested page is forbidden.

Status code: 408

**Table 14** Response body parameters
Parameter	Type	Description
-	String	The request timed out.

Status code: 429

**Table 15** Response body parameters
Parameter	Type	Description
-	String	Too many requests.

Status code: 500

**Table 16** Response body parameters
Parameter	Type	Description
-	String	Failed to complete the request because of an internal service error.

Status code: 503

**Table 17** Response body parameters
Parameter	Type	Description
-	String	The system is currently unavailable.

Example Requests

Request example 1: List 10 alarm rules in the descending order by creation time. Start from the one with alarm_id equal to al1441967036681YkazZ0deN.
```
GET
https://{Cloud Eye endpoint}/V1.0/{project_id}/alarms?start=al1441967036681YkazZ0deN&limit=10&order=desc
```
Request example 2: List 10 alarm rules under all enterprise projects in the descending order by creation time. Start from the one with alarm_id equal to al1441967036681YkazZ0deN.
```
GET
https://{Cloud Eye endpoint}/V1.0/{project_id}/alarms?start=al1441967036681YkazZ0deN&limit=10&order=desc&enterprise_project_id=all_granted_eps
```

Example Responses

Status code: 200

{
  "metric_alarms" : [ {
    "alarm_id" : "al1604473956229Ym1m1Wx6e",
    "alarm_name" : "alarm-rp0E",
    "alarm_description" : "",
    "relation_id" : "",
    "metric" : {
      "namespace" : "SYS.ECS",
      "dimensions" : [ {
        "name" : "instance_id",
        "value" : "33328f02-3814-422e-b688-bfdba93d4051"
      } ],
      "metric_name" : "network_outgoing_bytes_rate_inband"
    },
    "condition" : {
      "period" : 300,
      "filter" : "average",
      "comparison_operator" : ">=",
      "value" : 6,
      "unit" : "B/s",
      "selected_unit" : "",
      "count" : 1
    },
    "alarm_level" : 2,
    "alarm_type" : "MULTI_INSTANCE",
    "alarm_enabled" : true,
    "alarm_action_enabled" : true,
    "ignore_insufficient_data" : false,
    "alarm_actions" : [ {
      "type" : "notification",
      "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ]
    } ],
    "ok_actions" : [ {
      "type" : "notification",
      "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ]
    } ],
    "insufficientdata_actions" : [ ],
    "update_time" : 1604473956000,
    "alarm_state" : "insufficient_data",
    "enterprise_project_id" : "0"
  } ],
  "meta_data" : {
    "count" : 1,
    "marker" : "",
    "total" : 1
  }
}