文档首页/ 云监控服务 CES/ API参考/ API/ 云资源监控/ 监控视图/ 创建/复制/批量创建监控视图到指定的监控看板
更新时间:2025-09-23 GMT+08:00
分享

创建/复制/批量创建监控视图到指定的监控看板

功能介绍

创建/复制/批量创建监控视图到指定的监控看板

接口约束

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

调试

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

URI

POST /v2/{project_id}/dashboards/{dashboard_id}/widgets

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释:

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

约束限制:

不涉及。

取值范围:

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

默认取值:

不涉及。

dashboard_id

String

参数解释:

监控看板id

约束限制:

不涉及。

取值范围:

以db开头,包含22个字母和数字,长度为24个字符

默认取值:

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

String

参数解释:

发送的实体的MIME类型。

约束限制:

不涉及。

取值范围:

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

默认取值:

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

X-Auth-Token

String

参数解释:

用户Token。

约束限制:

不涉及。

取值范围:

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

默认取值:

不涉及。

表3 请求Body参数

参数

是否必选

参数类型

描述

[数组元素]

Array of BaseWidgetInfo objects

参数解释

监控视图信息

约束限制

不涉及

表4 BaseWidgetInfo

参数

是否必选

参数类型

描述

group_id

String

参数解释

视图分组id

约束限制

不涉及

取值范围

字符串必须以dg开头,包含22个字母和数字,长度为24个字符

默认取值

不涉及

metrics

Array of WidgetMetric objects

参数解释

指标列表

约束限制

包含的指标数量最多为200个,最少为1个

title

String

参数解释

监控视图标题

约束限制

不涉及

取值范围

长度为[1,128]个字符,允许包括以下内容:1、中文汉字;2、拉丁字母;3、英文大小写字母;4、数字(0-9);5、符号: ” " ≤ < > & / %_ : / ; “ ' ? + , ~ , ( ) º ( ) [ . -

默认取值

不涉及

threshold

Double

参数解释

监控视图指标的阈值

约束限制

不涉及

取值范围

最小值为0,最大值为1.7976931348623157e+308

默认取值

不涉及

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个;折线图时为随机展示的时序数据条数

约束限制

不涉及

取值范围

最小值为1,最大值为2147483647

默认取值

100

order

String

参数解释

排序字段

约束限制

折线图不支持该参数

取值范围

  • asc:正序

  • desc:倒序

默认取值

不涉及

description

String

参数解释

监控视图的描述信息

约束限制

不涉及

取值范围

长度为[0,200]个字符

默认取值

不涉及

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

参数解释

监控视图的上坐标

约束限制

不涉及

取值范围

最小值为0,最大值为2147483647

默认取值

不涉及

left

Integer

参数解释

监控视图的左坐标

约束限制

不涉及

取值范围

最小值为0,最大值为9

默认取值

不涉及

width

Integer

参数解释

监控视图图表宽度

约束限制

不涉及

取值范围

最小值为3,最大值为12

默认取值

不涉及

height

Integer

参数解释

监控视图图表高度

约束限制

不涉及

取值范围

最小值为3,最大值为2147483647

默认取值

不涉及

响应参数

状态码:200

表11 响应Body参数

参数

参数类型

描述

widget_ids

Array of strings

参数解释

批量创建监控视图返回结果

状态码:400

表12 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

状态码:401

表13 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

状态码:500

表14 响应Body参数

参数

参数类型

描述

error_code

String

请求异常内部业务状态码

error_msg

String

请求异常信息

request_id

String

请求ID

请求示例

[ {
  "metrics" : [ {
    "namespace" : "SYS.ECS",
    "dimensions" : {
      "name" : "instance_id",
      "filter_type" : "specific_instances",
      "values" : [ "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" ]
    },
    "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" : 0.7,
  "threshold_enabled" : true,
  "title" : "widget_title",
  "properties" : {
    "filter" : "topN",
    "topN" : 100,
    "order" : "desc"
  },
  "location" : {
    "left" : 0,
    "top" : 0,
    "width" : 4,
    "height" : 3
  },
  "unit" : "%"
} ]

响应示例

状态码:200

OK

{
  "widget_ids" : [ "wgx234567890123456789012" ]
}

状态码

状态码

描述

200

OK

400

Bad Request, 请求错误

401

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

500

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

错误码

请参见错误码

相关文档