# GetMetricWidgetImage: estructura y sintaxis de Metric Widget
`MetricWidget` es un parámetro de entrada de la API [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricWidgetImage.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricWidgetImage.html). Es una cadena en formato JSON.
**Topics**
+ [Estructura general](#Metric-Widget-Overall-Structure)
+ [Formato de cada métrica de la matriz de métricas](#CloudWatch-Metric-Widget-Metrics-Array-Format)
+ [Formato de las propiedades de las anotaciones](#CloudWatch-Metric-Widget-Annotations-Format)
+ [Formato de las propiedades de yAxis](#CloudWatch-Metric-Widget-YAxis-Properties-Format)
## Estructura general
La cadena `MetricWidget` puede incluir los siguientes parámetros:
**métricas**
Las métricas que se incluirán en el gráfico, como una matriz `metrics`. Puede incluir tanto métricas sin procesar como expresiones matemáticas. Una matriz `metrics` puede incluir entre 1 y 100 métricas y expresiones. Para obtener más información sobre el formato de `metrics`, consulte [Formato de cada métrica de la matriz de métricas](#CloudWatch-Metric-Widget-Metrics-Array-Format).
Tipo: matriz de matrices
Obligatorio: sí.
**annotations**
Las anotaciones horizontales y verticales que se agregarán al gráfico, como matrices de anotaciones. Para obtener más información sobre el formato, consulte [Formato de las propiedades de las anotaciones](#CloudWatch-Metric-Widget-Annotations-Format).
Obligatorio: no
**finales**
La fecha y hora correspondientes al final de las métricas que se muestran en el gráfico. Se puede expresar como un valor absoluto, como **2018-04-25T12:00:00.000Z**, o como un valor relativo, como **-PID**.
Si no especifica `end`, se utiliza el valor predeterminado de `-PT0H` (la hora actual).
Tipo: cadena
Requerido: no
**height**
La altura del widget en píxeles. El valor predeterminado es 400.
Valores válidos: 1–2000
Tipo: número entero
Obligatorio: no, pero debe establecer este valor si también establece un valor para `width`.
**legend**
Especifica la ubicación y visibilidad de la leyenda del gráfico. `legend` contiene un campo, `position`. El valor de `position` puede ser `bottom`, `right` o `hidden`. El valor predeterminado es `bottom`.
Tipo: cadena
Requerido: no
**liveData**
Especifique `true` para mostrar *datos en tiempo real* en el widget. Los datos en directo son aquellos publicados en el último minuto que no se han agregado por completo. Para obtener más información, consulte [Uso de datos en tiempo real](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch-live-data.html).
Tipo: Booleano
Obligatorio: no
**Período**
El período predeterminado, en segundos, para todas las métricas de este widget. Este valor predeterminado se puede reemplazar en la definición de cada métrica. El valor predeterminado es 300.
Valores válidos: 1, 5, 10, 30, 60 y cualquier múltiplo de 60. Los valores 1, 5, 10 y 30 solo se admiten para métricas de alta resolución.
Tipo: entero
Obligatorio: no
**region**
Este parámetro es opcional. Si lo incluye, debe especificar la región local.
Tipo: cadena
Requerido: no
**apilados**
Especifique `true` para mostrar el gráfico como una línea apilada o `false` para mostrarlo como líneas independientes. El valor predeterminado es false.
Tipo: Booleano
Obligatorio: no
**iniciar**
La fecha y hora correspondientes al inicio de las métricas que se muestran en el gráfico. Se puede expresar como un valor absoluto, como **2018-04-25T12:00:00.000Z**, o como un valor relativo, como **-PID**.
Si no especifica `start`, se utiliza el valor predeterminado de `-PT3H` (hace tres horas).
Tipo: cadena
Requerido: no
**estadística**
La estadística predeterminada que se mostrará para cada métrica de la matriz. Este valor predeterminado se puede reemplazar en la definición de cada métrica individual de la matriz `metrics`.
Si omite esto, se usa el valor predeterminado `Average`.
Valores válidos: `SampleCount` \| `Average` \| `Sum` \| `Minimum` \| `Maximum` \| `p{{??}}` \| `TM({{??}}:{{??}})`, `TC({{??}}:{{??}})` \| `TS({{??}}:{{??}})` \| `WM({{??}}:{{??}})` \| `PR({{??}}:{{??}})` \| `IQM`
Tipo: cadena que representa una estadística válida de CloudWatch.
Obligatorio: no
**theme**
La paleta de colores utilizada para aplicar estilo al gráfico. El valor predeterminado es `light`.
Valores válidos: `light | dark`
Tipo: cadena
Requerido: no
**timezone**
La zona horaria que se utilizará para mostrar las horas en el gráfico. El formato es \+ o - seguido de cuatro dígitos. Los dos primeros dígitos indican la cantidad de horas por delante o por detrás de UTC y los dos últimos indican la cantidad de minutos. Por ejemplo, `+0130` indica una hora y 30 minutos por delante de UTC. El valor predeterminado es `+0000`.
Tipo: cadena
Requerido: no
**título**
El título que se mostrará en el gráfico.
Tipo: cadena
Requerido: no
**ver**
El formato de visualización. Especifique `timeSeries` para mostrar esta métrica como un gráfico de líneas. Especifique `bar` para mostrar la métrica como un gráfico de barras. Especifique `pie` para mostrar la métrica como un gráfico circular. El valor predeterminado es `timeSeries`.
Valores válidos: `timeSeries | bar | pie`
Tipo: cadena
Requerido: no
**width**
El ancho del widget en píxeles. El valor predeterminado es 600.
Valores válidos: 1–2000
Tipo: número entero
Obligatorio: no, pero debe establecer este valor si también establece un valor para `width`.
**yAxis**
Límites para los valores mínimo y máximo del eje Y. Esto se aplica a todas las métricas representadas en el gráfico, a menos que métricas específicas los reemplacen. Para obtener más información sobre el formato, consulte [Formato de las propiedades de yAxis](#CloudWatch-Metric-Widget-YAxis-Properties-Format).
Tipo: objeto YAxis
Obligatorio: no
## Formato de cada métrica de la matriz de métricas
Cada elemento de la matriz `metrics` define una métrica de CloudWatch que se puede mostrar en el gráfico o utilizar como parte de una expresión matemática visualizada en este. Para obtener más información sobre las expresiones matemáticas, consulte [Uso de Metric Math](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html) en la Guía del usuario de Amazon CloudWatch.
Cada métrica de la matriz tiene el siguiente formato:
```
[{{Namespace}}, {{MetricName}}, {{Dimension1Name}}, {{Dimension1Value}}, {{Dimension2Name}}, {{Dimension2Value}}...
{{{Options Object}}}]
```
**Espacio de nombres**
El espacio de nombres AWS que contiene la métrica. Para utilizar el mismo espacio de nombres que la métrica anterior de la matriz, puede especificar `"."` para cada entrada después de la primera.
Tipo: cadena
Obligatorio: sí
**MetricName**
El nombre de la métrica de CloudWatch. Para utilizar el mismo nombre que la métrica anterior de la matriz, puede especificar `"."` para cada entrada después de la primera.
Tipo: cadena
Obligatorio: sí
**DimensionName**
El nombre de una dimensión para refinar aún más los datos que se muestran. Para utilizar el mismo nombre de dimensión que la métrica anterior de la matriz, puede especificar `"."` para cada entrada después de la primera. Puede especificar cero dimensiones para una métrica o tantas dimensiones como admita la métrica.
Tipo: cadena
Requerido: no
**DimensionValue**
El valor que se utilizará para esa dimensión de la métrica. Obligatorio si existe un nombre de dimensión correspondiente.
Tipo: cadena
Obligatorio: no, a menos que exista un nombre de dimensión correspondiente.
**Objeto Options**
Especifica propiedades de representación personalizadas que se utilizarán para la métrica de CloudWatch especificada o una expresión matemática que se mostrará en el gráfico. Para obtener más información sobre el formato, consulte [Formato del objeto Options](#CloudWatch-Metric-Widget-Options-Object-Format).
Tipo: objeto Options
Obligatorio: no
*Ejemplos*
```
// 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" ]
```
### Formato del objeto Options
Especifica propiedades de representación personalizadas que se utilizarán para la métrica de CloudWatch especificada o una expresión matemática que se mostrará en el gráfico.
Si este objeto se especifica como parte de una métrica de CloudWatch en la matriz `metrics`, establece propiedades de representación personalizadas para esa métrica y reemplaza los valores predeterminados utilizados para todo el gráfico.
También puede especificar este objeto para agregar una expresión matemática al gráfico. En ese caso, las demás configuraciones de este objeto especifican las opciones de visualización para el resultado de la expresión matemática.
Esta sección describe el formato de estos objetos Options.
**color**
El código de color hexadecimal HTML de seis dígitos que se utilizará para esta métrica o expresión.
Tipo: cadena
Requerido: no
**expresión**
Una expresión matemática que se mostrará. Para obtener más información sobre las funciones y el formato de las expresiones matemáticas admitidas, consulte [Sintaxis y funciones de Metric Math](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html#metric-math-syntax) en la Guía del usuario de Amazon CloudWatch.
Tipo: cadena que representa una expresión válida de Metric Math de CloudWatch.
Obligatorio: sí, si se trata de una expresión.
**etiqueta**
La etiqueta que se mostrará para esta métrica o expresión en la leyenda del gráfico. Si no se especifica, a la métrica se le asigna una etiqueta generada automáticamente que la distingue de las demás métricas del widget.
Tipo: cadena
Requerido: no
**id**
Un identificador para esta métrica o expresión que debe ser único dentro de este widget. El identificador se puede utilizar como variable para representar esta métrica o expresión en expresiones matemáticas. Los caracteres válidos son letras, números y guiones bajos. El primer carácter debe ser una letra minúscula.
Tipo: cadena
Requerido: no
**Período**
El periodo para esta métrica, en segundos. Si se especifica, este valor reemplaza el periodo predeterminado utilizado para las demás métricas de este gráfico. Este parámetro no se aplica a las expresiones matemáticas.
Valores válidos: 1, 5, 10, 30, 60 y cualquier múltiplo de 60. Los valores 1, 5, 10 y 30 solo se admiten para métricas de alta resolución.
Tipo: entero
Obligatorio: no
**estadística**
La estadística que se mostrará para esta métrica, si es diferente de la estadística utilizada para las demás métricas del gráfico. Este parámetro no se aplica a las expresiones matemáticas.
Valores válidos: `SampleCount` \| `Average` \| `Sum` \| `Minimum` \| `Maximum` \| `p{{??}}`
Tipo: cadena que representa una estadística válida de CloudWatch.
Obligatorio: no
**visible**
Especifica si esta métrica o expresión se muestra en el gráfico. El valor predeterminado es `true`.
Establecer `visible` en `false` resulta útil si desea ocultar las métricas sin procesar que se utilizan en expresiones matemáticas y mostrar únicamente los resultados de las expresiones en el gráfico.
Tipo: Booleano
Obligatorio: no
**yAxis**
La ubicación en el gráfico donde se mostrará el eje Y para esta métrica o expresión. El valor predeterminado es `left`.
Valores válidos: `left` \| `right`
Tipo: cadena
Requerido: no
*Ejemplo*
En el siguiente ejemplo, CloudWatch recupera una métrica personalizada de `apiLatency`. En la parte superior, se especifica la estadística p50 para mostrar el valor mediano. A continuación, para la misma métrica de la misma instancia (especificada mediante los cuatro campos representados únicamente por puntos), se representa el valor Promedio. A continuación, se muestra un objeto Options con una expresión matemática que presenta el valor intermedio entre las dos métricas. Por último, otra expresión muestra la tasa de cambio.
Para mostrar únicamente los resultados de las dos expresiones en el gráfico y ocultar las métricas sin procesar, puede cambiar las dos primeras instancias de `visible` a `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"
}
]
]
}
```
## Formato de las propiedades de las anotaciones
Un único gráfico puede tener varias anotaciones horizontales y verticales. Todas las anotaciones horizontales se especifican en el campo `horizontal` y todas las anotaciones verticales se especifican en el campo `vertical`.
**horizontal**
Una matriz de anotaciones horizontales. Las anotaciones horizontales ofrecen varias opciones de sombreado, entre ellas el sombreado por encima de la línea de anotación, el sombreado por debajo de la línea de anotación y el sombreado de banda, que aparece entre dos líneas de anotación vinculadas como parte de una única anotación. Cada anotación horizontal de la matriz que no utiliza sombreado de banda tiene el siguiente formato:
```
{{{value}}, {{label}}, {{color}}, {{fill}}, {{yAxis}}, {{visible}}}
```
Cada anotación horizontal que utiliza sombreado de banda tiene el siguiente formato:
```
[{{{value}}, {{label}}, {{color}}, {{yAxis}}, {{visible}}}, {{{value}}, {{label}}}]
```
**vertical**
Una matriz de anotaciones verticales. Las anotaciones verticales ofrecen varias opciones de sombreado, entre ellas el sombreado antes de la línea de anotación, el sombreado después de la línea de anotación y el sombreado de banda, que aparece entre dos líneas de anotación vinculadas como parte de una única anotación de banda. Cada anotación vertical de la matriz que no utiliza sombreado de banda tiene el siguiente formato:
```
{{{value}}, {{label}}, {{color}}, {{fill}}, {{visible}}}
```
Cada anotación vertical que utiliza sombreado de banda tiene el siguiente formato:
```
[{{{value}}, {{label}}, {{color}}, {{visible}}}, {{{value}}, {{label}}}]
```
La matriz `horizontal` puede incluir los siguientes campos.
**valor**
El valor de la métrica en el gráfico donde aparecerá la línea de anotación horizontal. En una anotación con sombreado de banda, los dos valores de `Value` definen los límites superior e inferior de la banda.
En un gráfico con anotaciones horizontales, el gráfico se escala para que todas las anotaciones horizontales visibles aparezcan en este.
Tipo: flotante
Obligatorio: sí, si se utilizan anotaciones horizontales.
**etiqueta**
Una cadena que aparece en el gráfico junto a la anotación.
Tipo: cadena
Requerido: no
**color**
El código de color hexadecimal HTML de seis dígitos que se utilizará para la anotación. Este color se utiliza tanto para la línea de anotación como para el sombreado de relleno.
Tipo: cadena
Requerido: no
**fill**
Cómo utilizar el sombreado de relleno con la anotación. Valores válidos: `above` para aplicar sombreado por encima de la anotación; `below` para aplicar sombreado por debajo de la anotación; y, `none`, para no aplicar sombreado. Si se omite `fill`, no se aplica sombreado.
La excepción es una anotación con sombreado de banda. Estas anotaciones siempre aplican sombreado entre los dos valores y se ignora cualquier valor de `fill`.
Tipo: cadena
Requerido: no
**visible**
Establezca este valor en `true` para que la anotación aparezca en el gráfico o en `false` para ocultarla. El valor predeterminado es `true`.
Tipo: Booleano
Obligatorio: no
**yAxis**
Si el gráfico incluye varias métricas, especifica si los números de `Value` hacen referencia a la métrica asociada al eje Y izquierdo o al eje Y derecho. Los valores válidos son `right` y `left`.
Tipo: cadena
Requerido: no
La matriz `vertical` puede incluir los siguientes campos.
**valor**
La marca de tiempo en la que aparecerá la línea de anotación vertical. Se debe especificar como una marca de tiempo absoluta, como `2018-08-28T15:25:26Z`. En una anotación con sombreado de banda, los dos valores de `Value` definen los límites inicial y final de la banda.
Tipo: cadena
Obligatorio: sí, si se utilizan anotaciones verticales.
**etiqueta**
Una cadena descriptiva que aparece en el gráfico junto a la anotación.
Tipo: cadena
Requerido: no
**color**
El código de color hexadecimal HTML de seis dígitos que se utilizará para la anotación. Este color se utiliza tanto para la línea de anotación como para el sombreado de relleno.
Tipo: cadena
Requerido: no
**fill**
Cómo utilizar el sombreado de relleno con la anotación. Valores válidos: `before` para aplicar sombreado antes de la anotación; `after` para aplicar sombreado después de la anotación; y, `none`, para no aplicar sombreado. Si se omite `fill`, no se aplica sombreado.
La excepción es una anotación con sombreado de banda. Estas anotaciones siempre aplican sombreado entre los dos valores y se ignora cualquier valor de `fill`.
Tipo: cadena
Requerido: no
**visible**
Establezca este valor en `true` para que la anotación aparezca en el gráfico o en `false` para ocultarla. El valor predeterminado es `true`.
Tipo: Booleano
Obligatorio: no
*Ejemplos*
```
// 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"
}
]
]
}
```
## Formato de las propiedades de yAxis
Define los valores mínimo y máximo del eje Y del gráfico. Establezca este valor dentro del objeto `MetricWidget` para que afecte a todas las métricas del widget. Para reemplazar la configuración del widget para una métrica específica, establézcalo en el objeto Options de esa métrica en la matriz `metrics`.
**izquierda**
Configuraciones opcionales de `min` y`max` para el eje Y izquierdo.
Tipo: objeto YAxis
Obligatorio: no
**derecha**
Configuraciones opcionales de `min` y `max` para el eje Y derecho.
Tipo: objeto YAxis
Obligatorio: no
Cada uno de los objetos `left` y `right` puede incluir los siguientes parámetros:
**min**
El valor mínimo de este eje Y.
Tipo: flotante
Obligatorio: no
**max**
El valor máximo de este eje Y.
Tipo: flotante
Obligatorio: no
*Ejemplo*
```
{
left: {
min: 0,
max: 100
},
right: {
min: 0
}
}
```