更新时间:2025-09-23 GMT+08:00
分享

批量更新监控视图

功能介绍

批量更新监控视图

接口约束

目前华东-青岛、拉美-墨西哥城一、土耳其-伊斯坦布尔、亚太-雅加达、中东-利雅得、亚太-马尼拉6个局点不支持该接口

调试

您可以在API Explorer中调试该接口,支持自动认证鉴权。API Explorer可以自动生成SDK代码示例,并提供SDK代码示例调试功能。

URI

POST /v2/{project_id}/widgets/batch-update

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释:

项目ID。用于明确项目归属,配置后可通过该ID查询项目下资产,可以通过调用API获取,也可以从控制台获取。获取方式请参见“获取项目ID”。

约束限制:

不涉及。

取值范围:

字符串的长度必须在 1 到 64个字符之间。

默认取值:

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

String

参数解释:

发送的实体的MIME类型。

约束限制:

不涉及。

取值范围:

最小字符数量为1,最大为64。

默认取值:

默认使用application/json; charset=UTF-8。

X-Auth-Token

String

参数解释:

用户Token。

约束限制:

不涉及。

取值范围:

最小字符数量为1,最大为16384。

默认取值:

不涉及。

表3 请求Body参数

参数

是否必选

参数类型

描述

[数组元素]

Array of UpdateWidgetInfo objects

待修改的监控视图列表

表4 UpdateWidgetInfo

参数

是否必选

参数类型

描述

group_id

String

视图分区id

widget_id

String

视图id

metrics

Array of WidgetMetric objects

指标列表

title

String

监控视图标题

threshold

Double

监控视图指标的阈值

threshold_enabled

Boolean

阈值是否展示,true:展示,false:不展示

view

String

监控视图图表类型, bar条形图,line折线图,bar_chart柱状图,table表格,circular_bar环形柱状图,area_chart面积图

metric_display_mode

String

指标展示类型,single 单指标展示,multiple 多指标展示

properties

properties object

视图展示配置

location

location object

监控视图图表坐标

unit

String

参数解释

单位

约束限制

不涉及

取值范围

长度为[0,32]个字符

默认取值

不涉及

表5 WidgetMetric

参数

是否必选

参数类型

描述

namespace

String

参数解释

查询服务的命名空间,各服务命名空间请参考“服务命名空间

约束限制

不涉及

取值范围

格式为service.item;service和item必须是字符串,必须以字母开头,只能包含0-9/a-z/A-Z/_。字符串的长度必须在 3 到 32个字符之间。

默认取值

不涉及

dimensions

DimensionInfo object

参数描述

维度信息列表。

约束限制

不涉及

metric_name

String

参数解释

多个指标名称

约束限制

不涉及

取值范围

长度为[1,1080]个字符,多个指标名称之间用逗号隔开

默认取值

不涉及

alias

Array of strings

参数解释

监控视图的指标别名列表

约束限制

当资源类型为指定资源时才允许传该参数

extra_info

ExtraInfo object

参数解释

指标信息

约束限制

不涉及

rollup_enable

Boolean

参数解释

是否开启聚合

约束限制

当rollup_enable开启时,rollup_filter和rollup_dimension必填

取值范围

  • true:表示开启聚合

  • false:表示不开启聚合

默认取值

false

rollup_filter

String

参数解释

聚合规则

约束限制

当rollup_enable开启时,rollup_filter和rollup_dimension必填

取值范围

  • last:最新值

  • max:最大值

  • min:最小值

  • average:平均值

  • sum:求和值

默认取值

不涉及

rollup_dimension

String

参数解释

聚合维度

约束限制

不涉及

取值范围

长度为[1,32]个字符

默认取值

不涉及

last_week_compare_enable

Boolean

参数解释

是否展示同比(上周同一时间)数据

约束限制

不涉及

取值范围

  • true:展示

  • false:不展示

默认取值

不涉及

yesterday_compare_enable

Boolean

参数解释

是否展示环比(昨天同一时间)数据

约束限制

不涉及

取值范围

  • true:展示

  • false:不展示

默认取值

不涉及

metric_dimension

String

参数解释

维度名称,多维度用逗号分隔,各服务支持的维度可参考:“服务维度名称”,必须以字母开头,只能包含0-9/a-z/A-Z/_/-,多维度用","分隔,每个维度的最大长度为32。总长度为[1,131]个字符。目前最大支持4个维度。举例:单维度场景:instance_id;多维度场景:instance_id,disk

约束限制

不涉及

取值范围

长度为[1,131]个字符

默认取值

不涉及

top_num

Integer

参数解释

展示数据数量

约束限制

不涉及

取值范围

最小值为1,最大值为200

默认取值

不涉及

unit

String

参数解释

单位

约束限制

不涉及

取值范围

长度为[0,32]个字符

默认取值

不涉及

order

String

参数解释

排序字段

约束限制

不涉及

取值范围

  • asc:正序

  • desc:倒序

默认取值

不涉及

topn_metric_name

String

参数解释

资源的监控指标名称,必须以字母开头,只能包含0-9/a-z/A-Z/_,字符长度最短为1,最大为64;如:弹性云服务器中的监控指标cpu_util,表示弹性服务器的CPU使用率;文档数据库中的指标mongo001_command_ps,表示command执行频率;各服务的指标名称可查看:“服务指标名称”。

约束限制

不涉及

取值范围

长度为[1,96]个字符

默认取值

不涉及

表6 DimensionInfo

参数

是否必选

参数类型

描述

name

String

参数描述

维度名称。

约束限制

不涉及

取值范围

多维度用逗号分隔,各服务支持的维度可参考:“服务维度名称”。必须以字母开头,只能包含0-9/a-z/A-Z/_/-,多维度用","分隔,每个维度的最大长度为32。总长度为[1,131]个字符。目前最大支持4个维度。举例:单维度场景:instance_id;多维度场景:instance_id,disk

默认取值

不涉及

filter_type

String

参数描述

资源类型。

约束限制

不涉及

取值范围

  • all_instances: 全部资源

  • specific_instances: 指定资源

默认取值

不涉及

values

Array of strings

参数描述

维度值列表。

约束限制

不涉及

表7 ExtraInfo

参数

是否必选

参数类型

描述

origin_metric_name

String

参数解释

指标名称

约束限制

不涉及

取值范围

长度为[1,4096]个字符

默认取值

不涉及

metric_prefix

String

参数解释

指标名称前缀

约束限制

不涉及

取值范围

长度为[1,4096]个字符

默认取值

不涉及

metric_type

String

参数解释

指标类型

约束限制

不涉及

取值范围

长度为[1,32]个字符

默认取值

不涉及

custom_proc_name

String

参数解释

自定义进程名称

约束限制

不涉及

取值范围

长度为[1,250]个字符

默认取值

不涉及

表8 properties

参数

是否必选

参数类型

描述

filter

String

聚合类型,目前只有TopN这一种类型,折线图不支持该参数

topN

Integer

Top值前N个;折线图时表示随机展示的时序数据条数

order

String

排序字段,asc正序,desc倒序,折线图不支持该参数

description

String

监控视图的描述信息

last_week_compare_enable

Boolean

是否展示同比(上周同一时间)数据,true:展示,false:不展示

yesterday_compare_enable

Boolean

是否展示环比(昨天同一时间)数据,true:展示,false:不展示

legend_location

String

图例位置标记,hide表示隐藏图例,right表示图例放在监控视图右侧,bottom表示图例放在监控视图底部,表格不支持该参数

legend_values

Array of strings

当前时序数据需要在图例中展示的统计值名称列表,表格不支持该参数,条形图和柱状图仅支持选择当前值

thresholds

Array of ThresholdInfo objects

监控视图的阈值辅助线配置

is_all_compare_enable

Boolean

同比环比总开关是否生效;true:生效;false:不生效

表9 ThresholdInfo

参数

是否必选

参数类型

描述

threshold

Number

参数解释

监控视图辅助线的阈值

约束限制

不涉及

取值范围

最小值为0,最大值为2147483647

默认取值

不涉及

threshold_color

String

参数解释

监控视图辅助线的颜色

约束限制

不涉及

取值范围

  • "#B50E65":紫色

  • "#F23030":红色

  • "#FF8800":橙色

  • "#F2E70C":黄色

默认取值

不涉及

表10 location

参数

是否必选

参数类型

描述

top

Integer

监控视图的上坐标

left

Integer

监控视图的左坐标

width

Integer

监控视图图表宽度

height

Integer

监控视图图表高度

响应参数

状态码:200

表11 响应Body参数

参数

参数类型

描述

widgets

Array of BatchUpdateWidgetInfo objects

更新结果列表

表12 BatchUpdateWidgetInfo

参数

参数类型

描述

widget_id

String

视图id

ret_status

String

修改结果;成功: successful, 失败: error

error_msg

String

如果失败则返回失败信息

状态码:400

表13 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

状态码:401

表14 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

状态码:500

表15 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

请求示例

[ {
  "widget_id" : "wgXXXXXXXXXXXXXXXXXXXXXX",
  "metrics" : [ {
    "namespace" : "SYS.ECS",
    "dimensions" : {
      "name" : "instance_id",
      "filter_type" : "all_instances"
    },
    "metric_name" : "cpu_util",
    "alias" : [ "cpuutilalias" ],
    "extra_info" : {
      "origin_metric_name" : "cpu_util",
      "metric_prefix" : "cpu",
      "metric_type" : "type",
      "custom_proc_name" : "app.sh"
    }
  } ],
  "view" : "bar",
  "metric_display_mode" : "single",
  "threshold" : 500,
  "threshold_enabled" : false,
  "title" : "widget_title_new",
  "properties" : {
    "filter" : "topN",
    "topN" : 10,
    "order" : "asc"
  },
  "location" : {
    "left" : 0,
    "top" : 3,
    "width" : 4,
    "height" : 3
  },
  "unit" : "%"
} ]

响应示例

状态码:200

OK

{
  "widgets" : [ {
    "widget_id" : "wgXXXXXXXXXXXXXXXXXXXXXX",
    "ret_status" : "successful"
  }, {
    "widget_id" : "wg9876543210123456789012",
    "ret_status" : "error",
    "error_msg" : "record not found"
  } ]
}

状态码

状态码

描述

200

OK

400

Bad Request, 请求错误

401

Unauthorized, 未提供认证信息,或认证信息错误

500

Internal Server Error, 请求未完成, 服务异常

错误码

请参见错误码

相关文档