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

Updated on 2025-10-30 GMT+08:00

View PDF

Updating Graphs in Batches

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.

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:widgets:put	Write	-	ces:namespace	-	-

URI

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

**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

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Constraints: None Value range: The value can contain 1 to 64 characters. Default value: The default type is application/json; charset=UTF-8.
X-Auth-Token	No	String	Definition User token. Constraints: None Value range: The value can contain 1 to 16,384 characters. Default value: None

**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.
widget_id	Yes	String	Graph ID.
metrics	No	Array of WidgetMetric objects	Metric list.
title	No	String	Graph name.
threshold	No	Double	Threshold of metrics on the graph.
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.
metric_display_mode	No	String	Metric display mode. The value can be single or multiple.
properties	No	properties object	Graph display configuration.
location	No	location object	Graph coordinates.
unit	No	String	Definition Unit. Constraints N/A Range [0,32] Default Value N/A

**Table 5** WidgetMetric
Parameter	Mandatory	Type	Description
namespace	Yes	String	Definition Namespace of a service. For details about the namespace of each service, see Namespaces. Constraints N/A Range The value is in the service.item format. The values of service and item must be a string, starting with a letter and containing only digits (0–9), letters (case-insensitive), and underscores (_). It must contain 3 to 32 characters. Default Value N/A
dimensions	Yes	DimensionInfo object	Description Dimension list. Constraints N/A
metric_name	Yes	String	Definition Multiple metric names. Constraints N/A Range The value can contain 1 to 1,080 characters. Multiple metric names are separated by commas (,). Default Value N/A
alias	No	Array of strings	Definition Metric aliases of the graph. Constraints This parameter can be transferred only when the resource type is set to Specified resources.
extra_info	No	ExtraInfo object	Definition Metric information. Constraints N/A
rollup_enable	No	Boolean	Definition Whether to enable aggregation. Constraints If rollup_enable is enabled, rollup_filter and rollup_dimension are mandatory. Range true: enabled false: disabled Default Value false
rollup_filter	No	String	Definition Aggregation rule. Constraints If rollup_enable is enabled, rollup_filter and rollup_dimension are mandatory. Range last: latest value max: maximum value min: minimum value average sum Default Value N/A
rollup_dimension	No	String	Definition Aggregation dimension. Constraints N/A Range 1 to 32 characters Default Value N/A
last_week_compare_enable	No	Boolean	Definition Whether to display comparison data (same period last week). Constraints N/A Range true: display false: not display Default Value N/A
yesterday_compare_enable	No	Boolean	Definition Whether to display comparison data (same period yesterday). Constraints N/A Range true: display false: not display Default Value N/A
metric_dimension	No	String	Definition Dimension name. For details about the dimensions supported by each service, see Service Dimension Names. The value must start with a letter and can only contain digits, letters, underscores (_), and hyphens (-). Multiple dimensions are separated by commas (,). Each dimension allows 32 characters. The total length is 1 to 131 characters. A maximum of four dimensions are supported. Example: instance_id for single-dimension scenarios; instance_id,disk for multi-dimension scenarios. Constraints N/A Range 1 to 131 characters Default Value N/A
top_num	No	Integer	Definition Number of displayed data records. Constraints N/A Range 1 to 200 Default Value N/A
unit	No	String	Definition Unit. Constraints N/A Range [0,32] Default Value N/A
order	No	String	Definition Sorting field. Constraints N/A Range asc: ascending desc: descending Default Value N/A
topn_metric_name	No	String	Definition 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 Names. Constraints N/A Range 1 to 96 characters Default Value N/A

**Table 6** DimensionInfo
Parameter	Mandatory	Type	Description
name	Yes	String	Description Dimension name. Constraints N/A Range Multiple dimensions are separated using commas (,). For details about the dimensions supported by each cloud service, see Services Interconnected with Cloud Eye. The value must start with a letter. Each dimension allows 1 to 32 characters and can only contain letters, digits, underscores (_), and hyphens (-). Multiple dimensions are separated using commas (,). The value can contain 1 to 131 characters. A maximum of four dimensions are supported. Example: instance_id for single-dimension scenarios; instance_id,disk for multi-dimension scenarios. Default Value N/A
filter_type	Yes	String	Description Resource type. Constraints N/A Range all_instances: all resources specific_instances: specified resources Default Value N/A
values	No	Array of strings	Description Dimension value list. Constraints N/A

**Table 7** ExtraInfo
Parameter	Mandatory	Type	Description
origin_metric_name	Yes	String	Definition Metric name. Constraints N/A Range 1 to 4,096 characters Default Value N/A
metric_prefix	No	String	Definition Metric name prefix. Constraints N/A Range 1 to 4,096 characters Default Value N/A
metric_type	No	String	Definition Metric type. Constraints N/A Range 1 to 32 characters Default Value N/A
custom_proc_name	No	String	Definition Custom process name. Constraints N/A Range 1 to 250 characters Default Value N/A

**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.
topN	No	Integer	Top N values. In a line chart, this parameter indicates the number of time series data records that are randomly displayed.
order	No	String	Sorting field. The value can be asc (ascending order) or desc (descending order). A line chart does not support this parameter.
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.
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.
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	Definition Threshold of the threshold line configured for the graph. Constraints N/A Range The value ranges from 0 to 2147483647. Default Value N/A
threshold_color	Yes	String	Definition Color of the threshold line for the graph. Constraints N/A Range "#B50E65": purple "#F23030": red "#FF8800": orange "#F2E70C": yellow Default Value N/A

**Table 10** location
Parameter	Mandatory	Type	Description
top	Yes	Integer	Grids between the graph and the top of the dashboard.
left	Yes	Integer	Grids between the graph and the left side of the dashboard.
width	Yes	Integer	Graph width.
height	Yes	Integer	Graph height.

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.
ret_status	String	Update result. The value can be successful or 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.