Administra los paneles con la API

Puedes administrar los paneles y gráficos mediante el recurso Dashboard en la API de Stackdriver Monitoring. El extremo admite los siguientes métodos para administrar y configurar paneles:

Si bien también puedes administrar tus paneles a través de Google Cloud Console, la API te ofrece una forma programática de administrar muchos paneles al mismo tiempo. Además, como los gráficos se implementan como widgets en los paneles, también puedes crear, configurar y manipular gráficos con la API del panel.

Antes de comenzar

Cuando creas un panel, debes especificar qué componentes o widgets deseas que se muestren y el diseño de esos widgets.

Define el diseño del panel

Los diseños definen cómo se ordenan los componentes de un panel. La API proporciona los siguientes tres diseños:

  • GridLayout: divide el espacio disponible en columnas verticales de igual ancho y organiza un conjunto de widgets con una estrategia de filas.

  • RowLayout: divide el espacio disponible en filas y organiza un conjunto de widgets horizontalmente en cada fila.

  • ColumnLayout: divide el espacio disponible en columnas verticales y organiza un conjunto de widgets verticalmente en cada columna.

Por ejemplo, a continuación se muestra la representación JSON de un panel en RowLayout con tres widgets Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Definición de widgets

Un widget contiene un único componente de panel y la configuración de cómo presentar el componente en él. Un panel puede tener más de un widget. Existen los siguientes tres tipos de objetos Widget:

  • XyChart: muestra los datos mediante los ejes Y y X. Los gráficos creados a través de Google Cloud Console son instancias de este widget.

  • Scorecard: muestra el último valor de una métrica y cómo se relaciona este valor con uno o más umbrales. Solo puedes crear este widget con la API.

  • Text: muestra el contenido textual, ya sea como texto sin formato o como string de Markdown. Solo puedes crear este widget con la API.

Además de estos objetos, también puedes agregar un marcador de posición en blanco a un panel.

Por ejemplo, a continuación se muestra la representación JSON de un widget XyChart:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Especifica los datos que se mostrarán

Si creaste gráficos a través de Google Cloud Console, ya conoces las métricas y las series temporales. Además de XyChart, puedes visualizar tus datos a través de widgets adicionales mediante la API del panel.

Para obtener información sobre las métricas y series temporales, consulta Métricas, series temporales y recursos.

Además, es posible que las guías Crea gráficos, Selecciona las métricas y Configura las opciones de vista sean útiles. Si bien estas guías están diseñadas a fin de crear gráficos a través de Google Cloud Console, los conceptos para crear un gráfico, seleccionar métricas y seleccionar opciones de vista también se aplican a la creación de gráficos mediante la API del panel.

Crea un panel

Para crear un panel nuevo personalizado, invoca el método dashboards.create y proporciónale el diseño y los widgets que se mostrarán en él.

Cuando creas un panel, la API genera automáticamente el dashboard_id. Si deseas especificar un dashboard_id personalizado, puedes establecer el campo name de un objeto Dashboard. El formato del campo de nombre se parece al siguiente:

"name": "projects/<host_project_id>/dashboards/<dashboard_id>"

En la API, host_project_id debe ser el proyecto host de un lugar de trabajo. Si especificas un identificador de proyecto de Google Cloud que no está asociado con un lugar de trabajo o que no es un proyecto host para un lugar de trabajo, se produce un error 400. Consulta Lugares de trabajo para obtener más información sobre cómo crear y administrar un lugar de trabajo.

Protocolo

Para crear un nuevo panel, envía una solicitud POST al extremo Dashboard, calificado con el diseño del panel y los widgets.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_number>/dashboards' -X POST -H "Content-Type:application/json" -H 'Authorization: Bearer <auth_token>' --data '{
        "displayName": "Untitled Dashboard",
        "gridLayout": {
          "columns": "1",
            "widgets": [
              {
                "title": "Example Scorecard",
                "scorecard": {
                  "timeSeriesQuery": {
                    "timeSeriesFilter": {
                      "filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
                      "aggregation": {
                        "perSeriesAligner": "ALIGN_RATE",
                        "crossSeriesReducer": "REDUCE_SUM"
                      }
                    },
                    "unitOverride": "1"
                  },
                  "gaugeView": {
                    "upperBound": 65
                  },
                  "thresholds": [
                    {
                      "value": 70,
                      "color": "RED",
                      "direction": "BELOW"
                    }
                  ]
                }
              }
            ]
          }' --compressed

El método muestra una respuesta similar a la del siguiente ejemplo:

{
  "name": "projects/<host_project_id>/dashboards/<dashboard_id>",
  "displayName": "Untitled Dashboard",
  "etag": "<etag_value>",
  "gridLayout": {
    "columns": "1",
    "widgets": [
      {
        "title": "Example Scorecard",
        "scorecard": {
          "timeSeriesQuery": {
            "timeSeriesFilter": {
              "filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
              "aggregation": {
                "perSeriesAligner": "ALIGN_RATE",
                "crossSeriesReducer": "REDUCE_SUM"
              }
            },
            "unitOverride": "1"
          },
          "gaugeView": {
            "upperBound": 65
          },
          "thresholds": [
            {
              "value": 70,
              "color": "RED",
              "direction": "BELOW"
            }
          ]
        }
      }
    ]
  }
}

Para ver configuraciones adicionales del panel, ve a Paneles y diseños de muestra.

Borra paneles

Para borrar un panel, invoca el método dashboards.delete y especifica el panel que deseas borrar.

Protocolo

Para borrar un panel, envía una solicitud DELETE al extremo Dashboard, calificada con el ID del panel que deseas eliminar.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -X DELETE -H 'Authorization: Bearer <auth_token>' --compressed

Si se completa correctamente, el método muestra una respuesta vacía. De lo contrario, muestra un error.

Enumera paneles

Para enumerar todos los paneles que pertenecen a un proyecto, invoca el método dashboards.list y especifica el ID del proyecto.

Protocolo

Para enumerar todos los paneles de un proyecto, envía el ID del proyecto al extremo Dashboard.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards' -H 'Authorization: Bearer <auth_token>' --compressed

El método muestra una respuesta similar a la del siguiente ejemplo:

"dashboards": [
  {
    "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
    "displayName": "Untitled Dashboard"
    "etag": "<etag_value>"
    "gridLayout" {
      "columns": 2
      "widgets": [
        {
          "title": "Produced API - Request sizes [SUM]"
          "xyChart" {
            "dataSets" {
              "timeSeriesQuery" {
                "timeSeriesFilter" {
                  "filter": "metric.type=\"aws.googleapis.com/DynamoDB/UserErrors/Sum\""
                  "aggregation" {
                    "perSeriesAligner": "ALIGN_RATE"
                  }
                }
                "unitOverride": "1"
              }
              "plotType": "LINE"
              "minAlignmentPeriod" {
                "seconds": 60
              }
            }
            "timeshiftDuration" {
            }
            "yAxis" {
              "label": "y1Axis"
              "scale": "LINEAR"
            }
            "chartOptions" {
              "mode": "COLOR"
            }
          }
        }
      ]
    }
  },
  {
    "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
    "displayName: "Untitled Dashboard"
    "etag": "<etag_value>"
    "gridLayout" {
      "columns": 2
    }
  }
]

Pagina la respuesta de la lista

El método dashboards.list admite la paginación, lo que te permite tomar los resultados de una página a la vez en lugar de todos juntos.

Protocolo

Para la página inicial de la lista de resultados, especifica el parámetro de búsqueda pageSize con solicitud:

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards?page_size=1' -H 'Authorization: Bearer <auth_token>' --compressed

El método muestra la primera página de la lista y nextPageToken. Por ejemplo:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Para cada página restante, debes incluir el nextPageToken correspondiente en la solicitud.

Obtén paneles

A fin de obtener un panel para un proyecto, invoca el método dashboards.get calificado con el ID del panel.

Protocolo

Para obtener un panel específico, envía el ID del panel al extremo Dashboard.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -H 'Authorization: Bearer <auth_token>' --compressed

El método muestra una respuesta similar a la del siguiente ejemplo:

{
  "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
  "displayName": "Demo Dashboard"
  "etag": "<etag_value>"
  "gridLayout" {
    "widgets": [
      {
        "text" {
          "content": "Hello World"
        }
      }
    ]
  }
}

Actualiza paneles

Para actualizar un panel existente, invoca el método dashboards.patch. Para obtener el valor etag actual, puedes invocar el método dashboards.get y encontrarlo en la respuesta.

Protocolo

Para actualizar un panel, envía una solicitud PATCH al extremo Dashboard y proporciona el objeto Dashboard revisado y el valor etag de la respuesta dashboards.get más reciente.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" --data '{
  "name": "projects/<host_project_id_or_name>/dashboards/<dashboard_id>",
  "displayName": "Updated Title",
  "etag": "<etag_value>",
  "gridLayout": {
    "columns": 2,
    "widgets": [
      {
        "blank": {}
      }
    ]
  }
}'

El método muestra el objeto Dashboard actualizado.