# GetMetricWidgetImage：指标小组件的结构和语法
`MetricWidget` 是 [https://docs.amazonaws.cn/AmazonCloudWatch/latest/APIReference/API_GetMetricWidgetImage.html](https://docs.amazonaws.cn/AmazonCloudWatch/latest/APIReference/API_GetMetricWidgetImage.html) API 的一个输入参数。该参数是一个 JSON 格式的字符串。
**Topics**
+ [整体结构](#Metric-Widget-Overall-Structure)
+ [指标数组中每个指标的格式](#CloudWatch-Metric-Widget-Metrics-Array-Format)
+ [注释属性格式](#CloudWatch-Metric-Widget-Annotations-Format)
+ [yAxis 属性格式](#CloudWatch-Metric-Widget-YAxis-Properties-Format)
## 整体结构
`MetricWidget` 字符串可以包含以下参数：
**metrics**
要包含在图表中的指标（以 `metrics` 数组形式）。这可以包括原始指标以及指标的数学表达式。一个 `metrics` 数组可以包含 1-100 个指标和表达式。有关 `metrics` 格式的更多信息，请参阅[指标数组中每个指标的格式](#CloudWatch-Metric-Widget-Metrics-Array-Format)。
类型：数组
必需：是。
**annotations**
要添加到图表中的横向和纵向注释（作为注释数组）。有关该格式的更多信息，请参阅[注释属性格式](#CloudWatch-Metric-Widget-Annotations-Format)。
必需：否
**最终**
图表中显示的指标结束日期和时间。这可以表示为绝对值，例如 **2018-04-25T12:00:00.000 Z**，也可以表示为相对值，例如 **-PID**。
如果未指定 `end`，则将使用默认值 `-PT0H`（当前时间）。
类型：字符串
必需：否
**height**
小组件的高度（以像素为单位）。默认值为 400。
有效值：1–2000
类型：整数
必需：否，但如果您还设置了 `width` 的值，则应设置此值。
**legend**
指定图表图例的位置和可见性。`legend` 包含一个字段 `position`。`position` 的值可以是 `bottom`、`right` 或 `hidden`。默认值为 `bottom`。
类型：字符串
必需：否
**liveData**
指定 `true` 以在小组件中显示*实时数据*。实时数据是将在最后一分钟内发布的，尚未完全聚合的数据。有关更多信息，请参阅[使用实时数据](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/cloudwatch-live-data.html)。
类型：布尔值
必需：否
**时段**
此小组件中所有指标的默认周期（以秒为单位）。可以在每个指标的定义中覆盖此默认值。默认值为 300。
有效值：1、5、10、30、60 以及 60 的任意倍数。1、5、10 和 30 专用于高精度指标。
类型：整数
必需：否
**region**
此参数为可选的。如果将其包括在内，则必须指定本地区域。
类型：字符串
必需：否
**堆叠图**
指定 `true` 以将图表显示为堆叠折线图，也可指定 `false` 以将其显示为单独的折线图。默认值为 false。
类型：布尔值
必需：否
**开启**
图表中显示的指标开始日期和时间。这可以表示为绝对值，例如 **2018-04-25T12:00:00.000 Z**，也可以表示为相对值，例如 **-PID**。
如果您未指定 `start`，则使用默认值 `-PT3H`（三小时前）。
类型：字符串
必需：否
**统计数据**
要为数组中的每个指标显示的默认统计数据。可以在 `metrics` 数组内的每个单独指标定义中覆盖此默认值。
如果省略该参数，则会使用默认值 `Average`。
有效值：`SampleCount` \| `Average` \| `Sum` \| `Minimum` \| `Maximum` \| `p{{??}}` \| `TM({{??}}:{{??}})`, `TC({{??}}:{{??}})` \| `TS({{??}}:{{??}})` \| `WM({{??}}:{{??}})` \| `PR({{??}}:{{??}})` \| `IQM`
类型：属于有效 CloudWatch 统计数据的字符串。
必需：否
**theme**
用于设置图表样式的调色板。默认值为 `light`。
有效值：`light | dark`
类型：字符串
必需：否
**timezone**
用于在图表中显示时间的时区。格式为 \+ 或- 加四位数字。前两位数字表示比 UTC 提前或落后的小时数，最后两位数字表示分钟数。例如，`+0130` 表示比 UTC 提前 1 小时 30 分钟的时间。默认值为 `+0000`。
类型：字符串
必需：否
**删除实例快照**
要显示的图表标题。
类型：字符串
必需：否
**查看**
显示格式。指定 `timeSeries` 以将此指标显示为折线图。指定 `bar` 以将此指标显示为柱状图。指定 `pie` 以将此指标显示为饼图。默认值为 `timeSeries`。
有效值：`timeSeries | bar | pie`
类型：字符串
必需：否
**width**
小组件的宽度（以像素为单位）。默认为 600。
有效值：1–2000
类型：整数
必需：否，但如果您还设置了 `width` 的值，则应设置此值。
**yAxis**
y 轴的最小值和最大值。这适用于要绘制图表的每个指标，但特定指标将其覆盖的除外。有关该格式的更多信息，请参阅[yAxis 属性格式](#CloudWatch-Metric-Widget-YAxis-Properties-Format)。
类型：YAxis 对象
必需：否
## 指标数组中每个指标的格式
`metrics` 数组中的每一项都是要在图表中显示，或者用作图表中所显示某个数学表达式的一部分的 CloudWatch 指标。有关数学表达式的更多信息，请参阅《Amazon CloudWatch 用户指南》中的[使用指标数学](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/using-metric-math.html)。
该数组中的每个指标都采用以下格式：
```
[{{Namespace}}, {{MetricName}}, {{Dimension1Name}}, {{Dimension1Value}}, {{Dimension2Name}}, {{Dimension2Value}}...
{{{Options Object}}}]
```
**命名空间**
包含该指标的 Amazon 命名空间。要使用与数组中前一个指标相同的命名空间，可以为第一个条目之后的每个条目指定 `"."`。
类型：字符串
是否必需：是
**MetricName**
CloudWatch 指标的名称。要使用与数组中前一个指标相同的名称，可以为第一个条目之后的每个条目指定 `"."`。
类型：字符串
是否必需：是
**DimensionName**
用于进一步细化要显示的数据的维度名称。要使用与数组中前一个指标相同的维度，可以为第一个条目之后的每个条目指定 `"."`。您可以为一个指标指定零个维度，也可以在该指标支持的维度数量范围内指定多个维度。
类型：字符串
必需：否
**DimensionValue**
要用于该指标维度的值。如果有相应的维度名称，则为必需。
类型：字符串
必需：否，除非有相应的维度名称。
**Options Object**
指定要用于指定 CloudWatch 指标的自定义渲染属性，或者指定要在图表上显示的数学表达式。有关该格式的更多信息，请参阅[选项对象格式](#CloudWatch-Metric-Widget-Options-Object-Format)。
类型：选项对象
必需：否
*示例*
```
// The simplest example, a metric with no dimensions
[ "AWS/EC2", "CPUUtilization" ]
// A metric with a single dimension
[ "AWS/EC2", "CPUUtilization", "InstanceId", "i-01234567890123456" ]
// A metric with a single dimension and rendering properties
[ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-01234567890123456", { yAxis: "right"} ]
// The following example graphs the DiskReadBytes metric for three instances.
[ "AWS/EC2", "DiskReadBytes", "InstanceId", "i-01234567890123456" ],
[ ".", ".", ".", "i-abc" ],
[ ".", ".", ".", "i-123" ]
```
### 选项对象格式
指定要用于指定 CloudWatch 指标的自定义渲染属性，或者指定要在图表上显示的数学表达式。
如果将此对象指定为 `metrics` 数组中某个 CloudWatch 指标的一部分，则将为该指标设置自定义渲染属性并覆盖整个图表使用的默认值。
也可以指定此对象来向图表添加数学表达式。在这种情况下，此对象中的其他设置用于指定数学表达式结果的显示选项。
本节介绍了这些选项对象的格式。
**color**
用于此指标或表达式的六位数 HTML 十六进制颜色代码。
类型：字符串
必需：否
**expression**
要显示的数学表达式。要详细了解受支持的数学表达式函数和格式，请参阅《Amazon CloudWatch 用户指南》中的[指标数学语法和函数](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/using-metric-math.html#metric-math-syntax)。
类型：属于有效 CloudWatch 指标数学表达式的字符串。
必需：是（如果属于表达式）。
**label**
要在图表图例中为此指标或表达式显示的标签。如果未指定，则会为该指标提供一个自动生成的标签，用于将其与小组件中的其他指标区分开来。
类型：字符串
必需：否
**id**
此指标或表达式的标识符，在此小组件中必须唯一。此 id 可用作变量来代表该指标或数学表达式中的表达式。有效字符包括字母、数字和下划线。第一个字符必须是小写字母。
类型：字符串
必需：否
**时段**
此指标的周期（以秒为单位）。如果指定了此参数，则会覆盖此图表中其他指标使用的默认周期。此参数不适用于数学表达式。
有效值：1、5、10、30、60 以及 60 的任意倍数。1、5、10 和 30 专用于高精度指标。
类型：整数
必需：否
**统计数据**
要为此指标显示的统计数据（如果与图表中其他指标使用的统计数据不同）。此参数不适用于数学表达式。
有效值: `SampleCount` \| `Average` \| `Sum` \| `Minimum` \| `Maximum` \| `p{{??}}`
类型：属于有效 CloudWatch 统计数据的字符串。
必需：否
**visible**
指定是否将在图表上显示此指标或表达式。默认值为 `true`。
如果要隐藏数学表达式中使用的原始指标，并且仅在图表上显示表达式结果，则将 `visible` 设置为 `false` 将非常实用。
类型：布尔值
必需：否
**yAxis**
在图表上显示该指标或表达式的 y 轴位置。默认值为 `left`。
有效值：`left` \| `right`
类型：字符串
必需：否
*示例*
在以下示例中，CloudWatch 检索了一个自定义的 `apiLatency` 指标。在顶部指定显示 p50 统计数据的中值。然后对于同一实例上的相同指标（由四个仅为周期的字段指定），将绘制平均值图。然后是一个带有数学表达式的选项对象，其中显示了两个指标的中间值。最后，另一个表达式会显示变化比率。
要在图表上仅显示两个表达式的结果并隐藏原始指标，可以将 `visible` 的前两个实例更改为 `false`。
```
{
"metrics": [
[
"MyNamespace",
"apiLatency",
"InstanceId",
"i-0987654321abcdef0",
{
"id": "m1",
"stat": "p50",
"label": "Median value",
"visible": true,
"color": "#dddddd",
"yAxis": "left",
"period": 300
}
],
[
".",
".",
".",
".",
{
"id": "m2",
"stat": "Average",
"label": "Average value",
"visible": true,
"color": "#cccccc",
"yAxis": "left",
"period": 300
}
],
[
{
"expression": "(m1+m2)/2",
"id": "e1",
"label": "Half way between average and median",
"visible": true,
"color": "#000000",
"yAxis": "left"
}
],
[
{
"expression": "RATE(e1)",
"yAxis": "right",
"label": "rate of change of the half way point"
}
]
]
}
```
## 注释属性格式
单个图表可以包含多个横向和纵向注释。所有横向注释都通过一个 `horizontal` 字段指定，所有纵向注释都通过一个 `vertical` 字段指定。
**horizontal**
横向注释数组。横向注释具有多种阴影填充选项，包括注释行上阴影、注释行下阴影，以及在单个注释中的两个链接注释行之间显示的阴影“带”。数组中没有阴影带的每个横向注释都采用以下格式：
```
{{{value}}, {{label}}, {{color}}, {{fill}}, {{yAxis}}, {{visible}}}
```
有阴影带的每个横向注释都采用以下格式：
```
[{{{value}}, {{label}}, {{color}}, {{yAxis}}, {{visible}}}, {{{value}}, {{label}}}]
```
**vertical**
纵向注释数组。纵向注释具有多种阴影填充选项，包括注释行前阴影、注释行后阴影，以及在单个注释段中的两条链接注释行之间显示的阴影“带”。数组中没有阴影带的每个纵向注释都采用以下格式：
```
{{{value}}, {{label}}, {{color}}, {{fill}}, {{visible}}}
```
有阴影带的每个纵向注释都采用以下格式：
```
[{{{value}}, {{label}}, {{color}}, {{visible}}}, {{{value}}, {{label}}}]
```
`horizontal` 数组可以包含以下字段。
**值**
图表中要显示横向注释行的指标值。在阴影带注释中，`Value` 的两个值用于定义阴影带的上边缘和下边缘。
使用横向注释的图表将会缩放，从而确保所有可见的横向注释都在图表中显示。
类型：浮点值
必需：是（如果使用横向注释）。
**label**
在图表中注释旁显示的字符串。
类型：字符串
必需：否
**color**
用于注释的六位数 HTML 十六进制颜色代码。该颜色既用于注释行，也用于阴影填充。
类型：字符串
必需：否
**fill**
如何在注释中使用阴影填充。有效值为 `above`（注释上阴影）、`below`（注释下阴影）和 `none`（无阴影）。如果省略 `fill`，则为无阴影。
唯一的例外是有阴影带的注释。此类注释会在这两个值之间始终填充阴影，`fill` 的任何值都将被忽略。
类型：字符串
必需：否
**visible**
将此设置为 `true` 以在图表中显示注释，或设置为 `false` 以隐藏注释。默认值为 `true`。
类型：布尔值
必需：否
**yAxis**
如果图表包含多个指标，则指定 `Value` 中的数字是否表示与左侧 Y 轴或右侧 Y 轴关联的指标。有效值为 `right` 和 `left`。
类型：字符串
必需：否
`vertical` 数组可以包含以下字段。
**值**
要显示纵向注释行的时间戳。必须将其指定为绝对时间戳，例如 `2018-08-28T15:25:26Z`。在阴影带注释中，`Value` 的两个值用于定义阴影带的起始和结束边缘。
类型：字符串
必需：是（如果使用纵向注释）。
**label**
在图表中注释旁显示的描述性字符串。
类型：字符串
必需：否
**color**
用于注释的六位数 HTML 十六进制颜色代码。该颜色既用于注释行，也用于阴影填充。
类型：字符串
必需：否
**fill**
如何在注释中使用阴影填充。有效值为 `before`（注释前阴影）、`after`（注释后阴影）和 `none`（无阴影）。如果省略 `fill`，则为无阴影。
唯一的例外是有阴影带的注释。此类注释会在这两个值之间始终填充阴影，`fill` 的任何值都将被忽略。
类型：字符串
必需：否
**visible**
将此设置为 `true` 以在图表中显示注释，或设置为 `false` 以隐藏注释。默认值为 `true`。
类型：布尔值
必需：否
*示例*
```
// A single horizontal annotation with fill shading above the annotation line, based on the metric associated with the right Y-axis
"annotations": {
"horizontal": [
{
"visible":true,
"color":"#9467bd",
"label":"Critical range",
"value":20,
"fill":"above",
"yAxis":"right"
}
]
}
// A horizontal band annotation. Each value has a label, but other parameters for the band need to be specified only with the first number
"annotations": {
"horizontal": [
[
{
"label":"Band top",
"value":200,
"color":"#9467bd",
"visible":true,
"yAxis":"right"
},
{
"value":95.5,
"label":"Band bottom"
}
]
]
}
// A single vertical annotation with fill shading after the annotation line
"annotations": {
"vertical": [
{
"visible": true,
"color": "#9467bd",
"label": "Bug fix deployed",
"value": "2018-08-28T15:25:26Z",
"fill": "after"
}
]
}
// A vertical band annotation. Each annotation line has a label, but other parameters for the band are specified only with the first value
"annotations": {
"vertical": [
[
{
"label": "Band start",
"value": "2018-08-27T15:25:26Z",
"color": "#9467bd",
"visible": true
},
{
"value": "2018-08-28T15:25:26Z",
"label": "Band end"
}
]
]
}
```
## yAxis 属性格式
定义图表 Y 轴的最小值和最大值。在 `MetricWidget` 对象中设置此参数会影响小组件中的所有指标。要为特定指标覆盖小组件设置，请在 `metrics` 数组中该指标的选项对象中对其进行设置。
**左**
左侧 Y 轴的可选 `min` 和 `max` 设置。
类型：YAxis 对象
必需：否
**右**
右侧 Y 轴的可选 `min` 和 `max` 设置。
类型：YAxis 对象
必需：否
每个 `left` 和 `right` 对象都可以包含以下参数：
**min**
此 Y 轴的最小值。
类型：浮点值
必需：否
**max**
此 Y 轴的最大值。
类型：浮点值
必需：否
*示例*
```
{
left: {
min: 0,
max: 100
},
right: {
min: 0
}
}
```