On this page

Function
Constraints
Debugging
URI
Request Parameters
Response Parameters
Example Requests
Example Responses
Status Codes
Error Codes

Show all

Help Center/ Cloud Eye/ API Reference/ API V2/ Graphs/ Updating Graphs in Batches

Updating Graphs in Batches

Updated on 2025-07-18 GMT+08:00

View PDF

Function

This API is used to update graphs in batches.

Constraints

This API is not supported in the following regions: CN East-Qingdao, LA-Mexico City1, TR-Istanbul, AP-Jakarta, ME-Riyadh, and AP-Manila.

Debugging

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

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Tenant ID. Regex Pattern: ^[a-zA-Z0-9-]{1,64}$

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	MIME type of the request body. The default type is application/json; charset=UTF-8. Default value: application/json; charset=UTF-8
X-Auth-Token	Yes	String	User token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
[items]	Yes	Array of UpdateWidgetInfo objects	List of graphs to be modified.

**Table 4** UpdateWidgetInfo
Parameter	Mandatory	Type	Description
group_id	No	String	Graph partition ID. Regex Pattern: ^dg([a-z]\|[A-Z]\|[0-9]){22}\|default$
widget_id	Yes	String	Graph ID. Regex Pattern: ^wg([a-z]\|[A-Z]\|[0-9]){22}$
metrics	No	Array of WidgetMetric objects	Metric list.
title	No	String	Graph name. Regex Pattern: ^([\u4E00-\u9FFF]\|[a-z]\|[A-Z]\|[0-9]\|_\|-\|:\|;\|$\|$\|\.\|~\|（\|）)+$
threshold	No	Double	Threshold of metrics on the graph. Value range: 0-1.7976931348623157E308
threshold_enabled	No	Boolean	Whether to display thresholds of metrics. The value can be true (to display) and false (not to display).
view	No	String	Graph type. The value can be bar, line, bar_chart, table, circular_bar, or area_chart. Enumeration values: bar line bar_chart table circular_bar area_chart
metric_display_mode	No	String	Metric display mode. The value can be single or multiple. Enumeration values: single multiple
properties	No	properties object	Graph display configuration.
location	No	location object	Graph coordinates.
unit	No	String	Unit.

**Table 5** WidgetMetric
Parameter	Mandatory	Type	Description
namespace	Yes	String	Service dimension. Regex Pattern: ^([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_)\.([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_)$
dimensions	Yes	DimensionInfo object	Dimension list.
metric_name	Yes	String	Metric name. Multiple metric names are separated by commas (,).
alias	No	Array of strings	Alias list of metrics on the graph.
extra_info	No	ExtraInfo object	Metric information.
rollup_enable	No	Boolean	Details: Whether to enable aggregation. Restrictions When RollupEnable is enabled, RollupFilter and RollupDimension are mandatory. Value Range true indicates that aggregation is enabled. false indicates that aggregation is disabled. Default value: false
rollup_filter	No	String	Aggregation rule. The value can be last, max, min, average, or sum. Enumeration values: last max min average sum
rollup_dimension	No	String	Aggregation dimension.
last_week_compare_enable	No	Boolean	Whether to display comparison data (same period last week). The value can be true or false.
yesterday_compare_enable	No	Boolean	Whether to display comparison data (same period yesterday). The value can be true or false.
metric_dimension	No	String	Dimension name. Use commas (,) to separate multiple dimensions. For details about the dimensions supported by each cloud service, see Services Interconnected with Cloud Eye. Regex Pattern: ^([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_\|-){0,31}(,([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_\|-){0,31}){0,3}$
top_num	No	Integer	Number of displayed data records. Value range: 1-200
unit	No	String	Unit.
order	No	String	How resources of top N metrics are sorted on a graph. The value can be asc or desc. Enumeration values: asc desc
topn_metric_name	No	String	Metric name of a resource. The name must start with a letter and contain only digits, letters, and underscores. The length ranges from 1 to 64 characters. For example, cpu_util of an ECS indicates the CPU usage of the ECS. mongo001_command_ps in DDS indicates the command execution frequency. For details about the metric name of each service, see Service metric name.

**Table 6** DimensionInfo
Parameter	Mandatory	Type	Description
name	Yes	String	Dimension name. Use commas (,) to separate multiple dimensions. For details about the dimensions supported by each cloud service, see Services Interconnected with Cloud Eye. Regex Pattern: ^([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_\|-){0,31}(,([a-z]\|[A-Z]){1}([a-z]\|[A-Z]\|[0-9]\|_\|-){0,31}){0,3}$
filter_type	Yes	String	Resource type. The value can be all_instances (all resources) or specific_instances (specified resources). Enumeration values: all_instances specific_instances
values	No	Array of strings	Dimension value list.

**Table 7** ExtraInfo
Parameter	Mandatory	Type	Description
origin_metric_name	Yes	String	Metric name. Regex Pattern: ^([a-z]\|[A-Z]\|[0-9]\|_\|-\|~\|\.\|/\|:)*$
metric_prefix	No	String	Metric name prefix. Regex Pattern: ^([a-z]\|[A-Z]\|[0-9]\|_\|-\|~\|\.\|/\|:)*$
metric_type	No	String	Metric type. Regex Pattern: ^([a-z]\|[A-Z]\|[0-9]\|_\|-\|~\|\.\|/\|:)*$
custom_proc_name	No	String	Custom process name.

**Table 8** properties
Parameter	Mandatory	Type	Description
filter	No	String	Aggregation type. Currently, the value can only be TopN. A line chart does not support this parameter. Enumeration values: topN
topN	No	Integer	Top N values. In a line chart, this parameter indicates the number of time series data records that are randomly displayed. Value range: 1-2147483647 Default value: 100
order	No	String	Sorting field. The value can be asc (ascending order) or desc (descending order). A line chart does not support this parameter. Enumeration values: asc desc
description	No	String	Description of the graph.
last_week_compare_enable	No	Boolean	Whether to display comparison data (same period last week). The value can be true or false.
yesterday_compare_enable	No	Boolean	Whether to display comparison data (same period yesterday). The value can be true or false.
legend_location	No	String	Legend position flag. The value can be hide, right, or bottom. Tables do not support this parameter. Enumeration values: hide right bottom
legend_values	No	Array of strings	List of statistical values to be displayed in the legend for the current time series. This parameter is not supported in tables. For bar charts and bar charts, only last can be selected. Enumeration values: last max min avg sum
thresholds	No	Array of ThresholdInfo objects	Threshold line configured for the graph.
is_all_compare_enable	No	Boolean	Whether to enable PoP comparison. The value can be true or false.

**Table 9** ThresholdInfo
Parameter	Mandatory	Type	Description
threshold	Yes	Number	Threshold of the threshold line for the graph. Value range: 0-2147483647
threshold_color	Yes	String	Color of the threshold line for the graph, which can be purple (#B50E65), red (#F23030), orange (#FF8800), and yellow (#F2E70C). Enumeration values: #B50E65 #F23030 #FF8800 #F2E70C

**Table 10** location
Parameter	Mandatory	Type	Description
top	Yes	Integer	Grids between the graph and the top of the dashboard. Value range: 0-2147483647
left	Yes	Integer	Grids between the graph and the left side of the dashboard. Value range: 0-9
width	Yes	Integer	Graph width. Value range: 3-12
height	Yes	Integer	Graph height. Value range: 3-2147483647

Response Parameters

Status code: 200

**Table 11** Response body parameters
Parameter	Type	Description
widgets	Array of BatchUpdateWidgetInfo objects	Update result list.

**Table 12** BatchUpdateWidgetInfo
Parameter	Type	Description
widget_id	String	Graph ID. Regex Pattern: ^wg([a-z]\|[A-Z]\|[0-9]){22}$
ret_status	String	Update result. The value can be successful or error. Enumeration values: successful error
error_msg	String	Error message when an operation fails.

Status code: 400

**Table 13** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Status code: 401

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Status codes customized by each cloud service when a request error occurs.
error_msg	String	Request error message.
request_id	String	Request ID.

Example Requests

[ {
  "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" : "%"
} ]

Example Responses

Status code: 200

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

Status Codes


Status Code	Description
200	OK
400	The server failed to process the request.
401	Token authentication is required.
500	Failed to complete the request because of an internal server error.