创建告警规则(V1)
功能介绍
创建一条告警规则。创建告警规则V1接口只支持配置单资源单策略规则,建议使用创建告警规则(推荐)与前端功能配套使用。
调试
您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。
URI
POST /V1.0/{project_id}/alarms
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
project_id |
是 |
String |
参数解释: 租户ID。用于明确项目归属,配置后可通过该ID查询项目下资产,可以通过调用API获取,也可以从控制台获取。获取方式请参见“获取项目ID”。 约束限制: 不涉及。 取值范围: 长度为[1,64]个字符。 默认取值: 不涉及。 |
请求参数
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
Content-Type |
否 |
String |
参数解释: 发送的实体的MIME类型。 约束限制: 不涉及。 取值范围: 长度为[1,64]个字符。 默认取值: 默认使用application/json,如果API是对象、镜像上传等接口,媒体类型可按照流类型的不同进行确定。 |
X-Auth-Token |
否 |
String |
参数解释: 用户Token。调用获取用户Token接口,请求响应成功后在响应消息头中包含的“X-Subject-Token”的值即为Token值。 约束限制: 不涉及。 取值范围: 长度为[1,16384]个字符。 默认取值: 不涉及。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
alarm_name |
是 |
String |
参数解释: 告警名称。 约束限制: 不涉及。 取值范围: 只能包含0-9/a-z/A-Z/_/-或汉字,长度1-128。 默认取值: 不涉及。 |
alarm_description |
否 |
String |
参数解释: 告警描述。 约束限制: 不涉及。 取值范围: 长度[0,256]个字符。 默认取值: 不涉及。 |
metric |
是 |
CreateAlarmMetric object |
参数解释: 创建规则中的监控指标信息。 约束限制: 不涉及。 |
condition |
是 |
Condition object |
参数解释: 告警规则设置的告警策略。 约束限制: 不涉及。 |
alarm_enabled |
否 |
Boolean |
参数解释: 是否启用该条告警。 约束限制: 不涉及。 取值范围: 布尔值。
默认取值: true |
alarm_action_enabled |
否 |
Boolean |
参数解释: 是否启用该条告警触发的动作。 约束限制: 若alarm_action_enabled为true,对应的alarm_actions、ok_actions至少有一个不能为空。若alarm_actions、ok_actions同时存在时,alarm_actions和ok_actions中的notification_list值保持一致。 取值范围: 布尔值。
默认取值: true |
alarm_level |
否 |
Integer |
参数解释: 告警级别。 约束限制: 不涉及。 取值范围: 只能为1、2、3、4。分别对应紧急、重要、次要、提示。 默认取值: 2 |
alarm_type |
否 |
String |
参数解释: 告警类型。 约束限制: 针对事件类型的告警时,告警类型为EVENT.SYS(系统事件)或EVENT.CUSTOM(自定义事件)。 针对资源分组的告警时,告警类型为RESOURCE_GROUP。 针对指定资源的告警时,告警类型为MULTI_INSTANCE。 取值范围:
默认取值: 不涉及。 |
alarm_actions |
否 |
Array of AlarmActions objects |
参数解释: 告警触发的动作。结构样例如下: { "type": "notification","notificationList":["urn:smn:southchina:68438a86d98e427e907e0097b7e35d47:sd"] } 其中type取值为notification(通知)、 autoscaling(弹性伸缩)。 约束限制: 最多包含10个告警触发时的动作。 |
insufficientdata_actions |
否 |
Array of AlarmActions objects |
参数解释: 数据不足触发的动作(该参数已废弃,建议无需配置)。 约束限制: 最多包含10个告警动作。 |
ok_actions |
否 |
Array of AlarmActions objects |
参数解释: 告警恢复触发的动作。 约束限制: 最多包含10个告警触发时的动作。 |
enterprise_project_id |
否 |
String |
参数解释: 企业项目ID。如何查询企业项目ID,请参考9.5-获取企业项目ID。 约束限制: 不涉及。 取值范围: 长度为0或者32个字符。 默认取值: 0,表示默认的企业项目default。 |
alarm_action_begin_time |
否 |
String |
参数解释: 告警通知开启时间。 约束限制: 不涉及。 取值范围: 只能包含数字、“:”,长度为[1,64]个字符。 默认取值: 不涉及。 |
alarm_action_end_time |
否 |
String |
参数解释: 告警通知关闭时间。 约束限制: 不涉及。 取值范围: 只能包含数字、“:”,长度为[1,64]个字符。 默认取值: 不涉及。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
namespace |
是 |
String |
参数解释: 服务指标命名空间。如:弹性云服务器的命名空间为SYS.ECS,文档数据库的命名空间为SYS.DDS,各服务的命名空间可查看:“服务命名空间”。 约束限制: 当alarm_type为(EVENT.SYS|EVENT.CUSTOM)时允许为空。 取值范围: 格式为service.item;service和item必须是字符串,必须以字母开头,只能包含0-9/a-z/A-Z/_,字符总长度最短为3,最大为32。 默认取值: 不涉及。 |
metric_name |
是 |
String |
参数解释: 资源的监控指标名称。如:弹性云服务器中的监控指标cpu_util,表示弹性服务器的CPU使用率;文档数据库中的指标mongo001_command_ps,表示command执行频率;各服务的指标名称可查看:“服务指标名称”。 约束限制: 不涉及。 取值范围: 必须以字母开头,只能包含0-9/a-z/A-Z/_,长度为[1,96]个字符。 默认取值: 不涉及。 |
dimensions |
否 |
Array of Dimension objects |
参数解释: 指标维度。 约束限制: 目前最大可添加4个维度。如果不使用resource_group_id,则dimensions值必填。 |
resource_group_id |
否 |
String |
参数解释: 创建告警规则时选择的资源分组ID。 约束限制: 如果根据资源分组创建告警规则,则resource_group_id不能为空,dimensions中至少指定一个维度信息,name不能为空,且alarm_type值为RESOURCE_GROUP;如:rg1603786526428bWbVmk4rP。 取值范围: 只能包含字母、数字、“_”,“-”,长度为[0,64]个字符。 默认取值: 不涉及。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
name |
是 |
String |
参数解释: 监控维度名称,如ECS的维度为instance_id。各服务资源的指标维度名称可查看:“服务维度名称”。 约束限制: 不涉及。 取值范围: 以字母开头,只能包含字母、数字、“_”、“-”。长度[1,32]个字符。 默认取值: 不涉及。 |
value |
否 |
String |
参数解释: 监控维度取值,例如ECS的ID。 约束限制: 不涉及。 取值范围: 长度为[0,256]个字符。 默认取值: 不涉及。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
comparison_operator |
是 |
String |
参数解释: 告警阈值的比较条件。 约束限制: 不涉及。 取值范围: 只能是>、=、<、>=、<=。 默认取值: 不涉及。 |
count |
是 |
Integer |
参数解释: 触发告警的连续发生次数。 约束限制: 不涉及。 取值范围: 取值范围[1, 5]。告警类型为事件告警时,取值范围为[1, 100]。 默认取值: 不涉及。 |
filter |
是 |
String |
参数解释: 数据聚合的方式. 约束限制: 不涉及。 取值范围: 支持max、min、average、sum、variance,分别表示最大值、最小值、平均值、求和值、方差值。 默认取值: 不涉及。 |
period |
是 |
Integer |
参数解释: 指标周期,单位是秒。如想了解各个云服务的指标原始周期可以参考“支持服务列表” 约束限制: 不涉及。 取值范围: 枚举值。
默认取值: 不涉及。 |
unit |
否 |
String |
参数解释: 数据的单位。 约束限制: 不涉及。 取值范围: 长度为[0,32]个字符。 默认取值: 不涉及。 |
value |
是 |
Number |
参数解释: 告警阈值。具体阈值取值请参见附录中各服务监控指标中取值范围,如支持监控的服务列表中ECS的CPU使用率cpu_util取值范围可配置80。 约束限制: 单一阈值时value和alarm_level配对使用,当hierarchical_value和value同时使用时以hierarchical_value为准。 取值范围: 最小值为-1.7976931348623157e+108,最大值为1.7976931348623157e+108。 默认取值: 不涉及。 |
suppress_duration |
否 |
Integer |
参数解释: 告警抑制时间,单位为秒,对应页面上创建告警规则时告警策略最后一个字段,该字段主要为解决告警频繁的问题。 约束限制: 不涉及。 取值范围: 枚举值,只能为0、300、600、900、1800、3600、10800、21600、43200、86400。
默认取值: 不涉及。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
[数组元素] |
否 |
Array of Notification objects |
参数解释: 告警触发的动作。 约束限制: 最多包含20个动作。 |
参数 |
是否必选 |
参数类型 |
描述 |
---|---|---|---|
type |
是 |
String |
参数解释: 告警通知类型。 约束限制: 不涉及。 取值范围: 取值如下: notification:通知; autoscaling:弹性伸缩。 默认取值: 不涉及。 |
notificationList |
是 |
Array of strings |
参数解释: 告警状态发生变化时,被通知对象的列表。 约束限制: 通知对象ID最多可以配置20个。 topicUrn可从SMN获取,具体操作请参考查询Topic列表。当type为notification时,notificationList列表不能为空;当type为autoscaling时,列表必须为[]。 说明:若alarm_action_enabled为true,对应的alarm_actions、insufficientdata_actions(该参数已废弃,建议无需配置)、ok_actions至少有一个不能为空。若alarm_actions、insufficientdata_actions(该参数已废弃,建议无需配置)、ok_actions同时存在时,notificationList值保持一致。 |
响应参数
状态码:201
参数 |
参数类型 |
描述 |
---|---|---|
alarm_id |
String |
告警规则的ID。 |
状态码:400
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
请求错误。 |
状态码:401
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
未提供认证信息,或认证信息错误。 |
状态码:403
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
请求页面被禁止访问。 |
状态码:408
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
请求超出了服务器的等待时间。 |
状态码:429
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
前请求过多。 |
状态码:500
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
请求未完成,服务异常。 |
状态码:503
参数 |
参数类型 |
描述 |
---|---|---|
- |
String |
系统暂时不可用,请求受限。 |
请求示例
{ "alarm_name" : "alarm-rp0E", "alarm_description" : "", "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", "count" : 1 }, "alarm_enabled" : true, "alarm_action_enabled" : true, "alarm_level" : 2, "alarm_actions" : [ { "type" : "notification", "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ] } ], "ok_actions" : [ { "type" : "notification", "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ] } ], "insufficientdata_actions" : [ { "type" : "notification", "notificationList" : [ "urn:smn:southchina:68438a86d98e427e907e0097b7e35d48:sd" ] } ] }
响应示例
状态码:201
Created
{ "alarm_id" : "al1604473956229Ym1m1Wx6e" }
状态码
状态码 |
描述 |
---|---|
201 |
Created |
400 |
Bad Request |
401 |
Unauthorized |
403 |
Forbidden |
408 |
Request Timeout |
429 |
Too Many Requests |
500 |
Internal Server Error |
503 |
Service Unavailable |
错误码
请参见错误码。