此页面由 Cloud Translation API 翻译。

通过 API 创建和管理信息中心

本文档介绍了如何创建和管理自定义信息中心和这些信息中心上的微件 Cloud Monitoring API 中的 Dashboard 资源。此处的示例说明了如何使用 curl 来调用 API，并展示了如何使用 Google Cloud CLI。您也可以通过 Google Cloud 控制台之后，该 API 可为您提供通过程序化方式同时管理多个信息中心

该端点支持以下方法来管理和配置信息中心：

dashboards.create：创建信息中心
dashboards.delete：删除指定的信息中心
dashboards.list：检索给定项目中所有信息中心的列表
dashboards.get：检索指定的信息中心
dashboards.patch：更新指定信息中心的结构

您可以使用 curl 实用程序或使用 Google Cloud CLI 直接调用 API。

您无法恢复、修改或删除预定义的信息中心。

信息中心简介

创建信息中心时，您必须指定哪些组件或微件以及这些 widget 的布局。您还可以向信息中心添加标签和过滤条件。标签可帮助您查找信息中心或指明信息中心内的内容类型

信息中心布局

布局定义了信息中心组件的排序方式。该 API 提供以下布局：

GridLayout：将可用空间划分为宽度相等的纵向列，并使用行优先策略排列一组微件。
MosaicLayout：将可用空间划分为网格。每个微件可以占据一个或多个网格块。
RowLayout：将可用空间划分为几行，并在每行中水平排列一组微件。
ColumnLayout：将可用空间划分为垂直列，并在每列中垂直排列一组微件。

例如，下图显示了 RowLayout 信息中心的 JSON 表示法，其中有三个 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"
            }
          }
        ]
      }
    ]
  }
}

信息中心微件

微件包含单个信息中心组件以及如何在信息中心中呈现组件的配置。一个信息中心可以有多个微件。Widget 对象有多种类型：

XyChart widget 显示 X 轴和 Y 轴上的数据。

此 widget 显示可时间序列数据或通过 SQL 查询生成的。借助此 widget，您可以将图表数据与左侧或右侧 Y 轴相关联。绘制多个指标类型的图表时，您可以使用两个 Y 轴。XyChart widget 支持以下显示样式：
- 折线图
- 条形图
- 堆积面积图
- 热图
从一个维度（例如最新值）显示的微件：
- PieChart：显示一组时序，其中每个时序会为每个时序贡献一个切片。
- Scorecard：显示 1 的最新值以及该值与一个或多个阈值的关系。
- TimeSeriesTable：显示最新值，汇总值。表支持自定义。例如，您可以为单元格设置颜色，以及配置列名称和数据对齐方式。
显示提醒政策或事件信息的微件：
- AlertChart：显示单一条件提醒政策的摘要。此微件以折线图的形式显示数据，并显示阈值及列出未结突发事件的数量。
- IncidentList：显示突发事件列表。您可以配置 widget，以显示特定提醒政策或针对特定资源类型。
显示日志条目和错误的微件：
- ErrorReportingPanel：显示错误组存储在 Google Cloud 项目。
- LogsPanel：显示存储在当前 Google Cloud 项目中的项目范围日志条目。您可以将 widget 配置为显示日志条目存储在可通过当前子网访问的 Google Cloud 项目中指标范围。
文本和组织微件：
- CollapsibleGroup：显示一组微件。您可以收起群组视图。
- SingleViewGroup：在一组微件您可以选择要显示的微件。
- SectionHeader：在以下位置创建水平分隔线并且会在信息中心的表格中内容。
- Text：以原文或 Markdown 字符串的形式显示文字内容。
要在信息中心，则必须为该信息中心设置 MosaicLayout。

除了这些对象之外，您还可以向信息中心添加空白占位符。

例如，下面显示了配置右侧 Y 轴的 XyChart 微件的 JSON 表示法：

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

信息中心标签

标签可帮助您管理和整理信息中心。例如，您可能会添加一个名为 prod 的标签，以指明信息中心显示的是时间序列数据和日志数据。或者则可以添加标签playbook来指示信息中心包含有助于您排查故障的信息。

向信息中心添加标签是可选操作。

例如，以下代码显示了一个 Dashboard 对象，指定名为 playbook 的标签。

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

如上例所示，labels 字段实现为 map，其中 key 和 value 字段都是字符串。向信息中心添加标签时，请将 key 设置为标签的名称，并将 value 字段设置为空字符串。

信息中心过滤条件

在设计信息中心时，您可能会通过多种方式来查看数据例如，假设信息中心显示虚拟机 (VM) 实例的时间序列数据。你可能需要查看所有虚拟机的时间序列数据特定可用区内的数据在本课中，在这种情况下，我们建议您创建一个永久过滤器，并将默认过滤器设置为值更改为最常用的数据视图。永久过滤条件可应用于部分或全部信息中心微件。使用 Google Cloud 控制台查看信息中心时，信息中心工具栏会显示永久性过滤条件和一个菜单，您可以使用该菜单暂时更改过滤条件的值。

信息中心的永久过滤条件有多种类型：

信息中心范围的过滤条件适用于信息中心中支持过滤条件标签且未为该标签指定值的所有微件。

例如，如果图表包含过滤条件 zone = us-central1-a，图表会忽略基于标签 zone 的信息中心过滤条件。同样，没有“zone”标签的图表会忽略带有此标签的信息中心过滤条件。
模板变量是适用于特定微件的命名变量。每个变量都对应于一个特定的标签和值。您可以决定模板变量适用的微件。

所有过滤器类型均以相同的数据结构表示。如需了解详情，请参阅 DashboardFilter。

例如，下面显示了信息中心的部分 JSON 表示法，用于定义模板变量和信息中心范围的过滤条件：

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

在显示的 JSON 中，dashboardFilters 结构中的第一个条目代表一个名为 iid 的模板变量和一个名为标签键 zone。模板变量是标签 instance_id 的别名。

模板变量的数据结构不会列出需要。而是通过以下方法将 widget 与模板变量相关联：修改微件的查询以包含对变量的引用。当该 widget 显示在信息中心内时，模板变量的值已解析。

如需了解如何为日志面板和图表添加注释，请参阅以下部分：

“日志”面板
MQL 定义的图表和表格
PromQL 定义的图表和表格
使用时间序列过滤条件定义的图表和表格

日志面板

要将日志面板配置为根据模板变量，请将该变量添加到查询窗格中。以下示例展示了按模板变量 iid 的值进行过滤的查询：

${iid}

在日志面板查询要显示的日志之前，模板变量已解决。在此示例中，如果模板变量的值为 "12345"，则将 ${iid} 替换为语句 resource.labels."instance_id"="12345"。

您还可以在查询中仅包含模板变量的值。我们建议您仅在使用正则表达式。例如，以下查询使用正则表达式来匹配具有 JSON 载荷，其中包含描述的字符串：

jsonPayload.message=~"Connected to instance: ${iid.value}"

如果您为日志面板配置了查询，请选择相应按钮打开日志浏览器时，会先解析模板变量， Logs Explorer 打开。

下表展示了系统如何通过日志面板：

语法	Selected Value	已解决的日志面板表达式
`${iid}`	`12345`	`resource.labels."instance_id"="12345"`
`${iid}`	`*`	`""`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

MQL 定义的图表和表格

使用 Monitoring Query Language (MQL) 配置图表时，请在末尾添加竖线和变量设置为以下查询字符串：

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${iid}

在图表查询要显示的时序之前，模板变量已解决。在此示例中，如果模板变量的值为 "12345"，则将 ${iid} 替换为语句 filter (resource.instance_id == '12345')。此过滤条件与时间匹配标签为 resource.instance_id 的序列，并且仅当其值为 12345。

如果您想使用正则表达式过滤时序将查询配置为仅包含模板变量的值。为了对语法进行说明，以下展示了如何使用正则表达式来确定标签 resource.instance_id 包含模板变量 iid 的值：

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~"${iid.value}"
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

下表显示了如何针对 MQL 解析模板变量查询：

语法	已选值	解析的 MQL 表达式
`${iid}`	`12345`	`filter (resource.instance_id == '12345')`
`${iid}`	`*`	`filter (true)`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.*`

PromQL 定义的图表和表格

使用 PromQL 定义图表时，将变量：

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

在图表查询要显示的时序之前，模板变量已解决。在此示例中，如果模板变量的值为 "12345"，则 ${iid} 会替换为语句 instance_id == '12345'。

与 MQL 类似，使用 PromQL 定义微件时，查询只能提取模板变量的值。我们建议您只将该值用作通过正则表达式定义的过滤器的一部分。接收者下面对语法进行了说明，下面介绍了如何使用正则表达式确定标签 instance_id 的值是否包含模板变量 iid：

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${iid.value}"
}

下表显示了如何针对 PromQL 解析模板变量查询：

语法	Selected Value	已解析的 PromQL 表达式
`${iid}`	`12345`	`instance_id == '12345'`
`${iid}`	`*`	`noop_filter=~".*"`
`${iid.value}`	`12345`	`12345`
`${iid.value}`	`*`	`.+`

使用时间序列过滤条件定义的图表和表格

使用时间序列过滤条件定义图表时，请将变量附加到过滤条件字符串：

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

与 MQL 和 PromQL 定义的图表不同，您不能使用该值时序过滤条件中模板变量的值。

下表显示了如何解析模板变量：

语法	Selected Value	已解析的过滤条件表达式
`${iid}`	`12345`	`resource.instance_id == "12345"`
`${iid}`	`*`	已忽略
`${iid.value}`	`12345`	不支持
`${iid.value}`	`*`	不支持

创建信息中心

如需创建新的自定义信息中心，请调用 dashboards.create 方法，并为其提供要显示在信息中心内的布局和微件。

创建信息中心时，API 会自动生成 dashboard_id。如果您要指定自定义 dashboard_id，可以设置 Dashboard 对象的 name 字段。名称字段的格式如下所示：

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

协议

如需创建新的信息中心，请向Dashboard端点发送 POST 请求。

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

如需在项目中创建信息中心，请使用 gcloud monitoring dashboards create 命令。

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

例如，如果您想复制信息中心，请执行以下操作：

完成获取信息中心中的步骤，下载原始信息中心
修改返回的 JSON 以移除 etag 和 name 字段，并更改 displayName 字段的值。
运行该命令以创建信息中心。

如需了解详情，请参阅 gcloud monitoring dashboards create 参考文档。

这些示例使用 my-dashboard.json 文件创建示例信息中心。您可以通过 Google Cloud 控制台管理信息中心。

如需了解其他信息中心配置，请参阅示例信息中心和布局。

删除信息中心

如需删除自定义信息中心，请调用 dashboards.delete 方法并指定要删除的信息中心。

协议

如需删除自定义信息中心，请向 Dashboard 端点发送一个 DELETE 请求，并使用要删除的信息中心的 ID 进行限定。

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

如果成功，该方法将返回一个空响应。否则，将返回错误。

gcloud

如需删除自定义信息中心，请使用 gcloud monitoring dashboards delete和指定要删除的信息中心的完全限定 ID：

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

如需了解详情，请参阅 gcloud monitoring dashboards delete 参考文档。

列出信息中心

如需列出属于某个项目的所有自定义信息中心，请调用 dashboards.list 方法并指定项目 ID。

协议

要列出项目的所有自定义信息中心，请将项目 ID 发送到Dashboard端点。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

要列出项目的所有自定义信息中心，请使用 gcloud monitoring dashboards list 命令：

gcloud monitoring dashboards list

如需了解详情，请参阅 gcloud monitoring dashboards list 参考文档。

这些示例会返回与您的项目关联的自定义信息中心。

对列表响应进行分页

dashboards.list 方法支持分页功能，您可以一次获取一页结果，而不是一次获取所有结果。

协议

对于结果列表的初始页面，请使用请求指定 pageSize 查询参数：

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

该方法返回列表的第一页和 nextPageToken。例如：

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

对于每个剩余信息页，您必须在请求中包含相应的 nextPageToken。

gcloud

如需指定每个页面的资源数量，请使用命令传递 --page-size 标记。例如：

gcloud monitoring dashboards list --page-size=1

获取信息中心

如需获取项目的特定自定义信息中心，请调用 dashboards.get 方法，并使用信息中心 ID 进行限定。

协议

如需获取特定的自定义信息中心，请将信息中心 ID 发送到 Dashboard 端点。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

该方法会返回类似于以下示例的响应：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

要获取特定的自定义信息中心，请使用 gcloud monitoring dashboards describe 命令并指定信息中心 ID：

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

该命令会返回请求的信息中心：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

如需了解详情，请参阅 gcloud monitoring dashboards describe 参考文档。

更新信息中心

如需更新现有的自定义信息中心，请调用 dashboards.patch 方法。如需获取当前的 etag 值，您可以调用 dashboards.get 方法并在响应中找到它。

协议

要更新自定义信息中心，请将 PATCH 请求发送到 Dashboard 端点，并从最近的 dashboards.get 响应提供修改后的 Dashboard 对象和 etag 值。

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

gcloud

如需更新自定义信息中心，请使用 gcloud monitoring dashboards update，指定要更新的信息中心的 ID，并将更改提供给信息中心。

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

如需了解详情，请参阅 gcloud monitoring dashboards update 参考文档。

这些示例使用 my-updated-dashboard.json 文件更新现有自定义信息中心，并返回更新后的信息中心列表的副本。返回数据包含新的 etag 值。

通过 API 创建和管理信息中心

信息中心简介

信息中心布局

信息中心微件

信息中心标签

信息中心过滤条件

日志面板

MQL 定义的图表和表格

PromQL 定义的图表和表格

使用时间序列过滤条件定义的图表和表格

创建信息中心

协议

gcloud

删除信息中心

协议

gcloud

列出信息中心

协议

gcloud

对列表响应进行分页

协议

gcloud

获取信息中心

协议

gcloud

更新信息中心

协议

gcloud

后续步骤