本文档介绍如何使用 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。
您无法检索、修改或删除预定义的信息中心。
准备工作
创建信息中心时，您必须指定要显示的组件或微件，以及这些微件的布局。您还可以向信息中心添加永久过滤条件。
信息中心布局
布局定义了信息中心组件的排序方式。该 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：使用 X 轴和 Y 轴显示数据。通过 Google Cloud 控制台创建的折线图、条形图、堆叠面积图和热图图表是此微件的实例。如果您创建折线图、堆叠条形图或堆叠面积图，则可以指定指标表示左侧或右侧 Y 轴。绘制多个指标的图表时，您可以使用两个 Y 轴。SLO 图表也是
XyChart微件的实例，但不支持使用 API 创建 SLO 图表。AlertChart：显示单一条件提醒政策的摘要。此微件以折线图的形式显示数据，并显示阈值及列出未结突发事件的数量。CollapsibleGroup：显示一组 widget。 您可以收起组的视图。如需将这些 widget 添加到信息中心内，信息中心必须有一个MosaicLayout。IncidentList：显示突发事件列表。您可以配置该微件，以显示特定提醒政策或特定资源类型的突发事件。LogsPanel：显示存储在当前 Google Cloud 项目中的项目范围日志条目。您可以配置该 widget，以显示存储在 Google Cloud 项目中的日志条目（可通过当前的指标范围访问）。Scorecard：显示指标的最新值，以及该值与一个或多个阈值的关系。TimeSeriesTable：显示指标的最新值。您可以根据列对表格进行排序、过滤表格或在显示结果中添加或移除列。Text：以原文或 Markdown 字符串的形式显示文字内容。
除了这些对象之外，您还可以向信息中心添加空白占位符。
例如，下面显示了配置右侧 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"
}
}
}
]
}
}
信息中心过滤条件
在设计信息中心时，您可能会找到多种查看信息中心显示的数据的方式。例如，当信息中心显示虚拟机 (VM) 实例的指标时，您可能需要查看所有虚拟机的指标，并且可能需要查看特定可用区的指标。在这类情况下，我们建议您创建一个永久过滤器，并将该过滤器的默认值设为最常用的视图。永久过滤条件可以应用于部分或所有信息中心微件。使用 Google Cloud 控制台查看信息中心时，信息中心工具栏会显示永久过滤条件和菜单，您可以使用这些过滤条件暂时更改过滤条件的值。
永久信息中心过滤条件有多种类型：
信息中心范围的过滤条件适用于信息中心内支持过滤条件标签并且未指定该标签值的所有微件。
例如，如果图表包含过滤条件
zone = us-central1-a，该图表会忽略基于标签zone的信息中心过滤条件。同样，没有zone标签的图表会忽略包含此标签的信息中心过滤条件。模板变量是应用于特定 widget 的具名变量。每个变量都代表特定的标签和值。您可以确定模板变量适用的微件。
所有过滤器类型都使用相同的数据结构表示。如需了解详情，请参阅 DashboardFilter。
例如，下面显示了定义了模板变量和信息中心范围的过滤条件的信息中心的部分 JSON 表示法：
{
"category": "CUSTOM",
"dashboardFilters": [
{
"filterType": "RESOURCE_LABEL",
"labelKey": "zone",
"stringValue": "us-central1-b",
"templateVariable": "my_zone_temp_var"
},
{
"filterType": "RESOURCE_LABEL",
"labelKey": "project_id",
"stringValue": "my-project-id",
"templateVariable": ""
}
],
"displayName": "Illustrate Template Variables",
...
在显示的 JSON 中，dashboardFilters 结构中的第一个条目是一个名为 my_zone_temp_var 的模板变量。第二个条目是适用于整个信息中心的过滤条件。对于适用于所有信息中心 widget 的过滤器，templateVariable 字段的值设置为零长度字符串 ""。
模板变量的数据结构不会列出其适用的微件。相反，当您将 widget 与模板变量相关联时，widget 的查询会被修改为包含对该变量的引用。 使用 Monitoring Query Language (MQL) 配置图表时，请将查询字符串和变量附加到查询字符串：
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n|
every 1m\n| ${my_zone_temp_var}\n"
使用 PromQL 定义图表时，请将用大括号括起来的变量附加到查询字符串：
"prometheusQuery" :
"compute_googleapis_com:instance_cpu_utilization {project_id=\"my-project\", ${my_zone_temp_var}}\n"
上面的示例说明了如何过滤由 PromQL 定义的 widget，以仅显示 Google Cloud 项目 my-project 中且与模板变量匹配的时序。
使用时序过滤条件定义图表时，请将变量附加到过滤器字符串：
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
resource.type=\"gce_instance\" ${my_zone_temp_var}"
以下 JSON 图示显示了在图表的完整定义上下文中出现的查询字符串：
{
...
"displayName": "Illustrate Template Variables",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"title": "MQL",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization\n| every 1m\n| ${my_zone_temp_var} \n"
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 0,
"yPos": 0
},
{
"height": 4,
"widget": {
"title": "LTS",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"minAlignmentPeriod": "60s",
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"apiSource": "DEFAULT_CLOUD",
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${my_zone_temp_var}"
}
}
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 6,
"yPos": 0
}
]
}
}
指定要显示的数据
显示从时序检索到的数据的任何微件中都嵌入了一个 TimeSeriesQuery 对象。此对象用于指定在微件中使用的时间序列数据。
您可以按如下方式指定要显示的时间序列数据：
使用 Monitoring 过滤器。过滤条件用于
TimeSeriesFilter和TimeSeriesFilterRatio查询中。如需详细了解如何以这种方式检索指标数据，请参阅检索时序数据。利用 MQL。此方法在
TimeSeriesQuery对象中使用 MSQL 查询。查询字符串将作为timeSeriesQueryLanguage字段的值进行传递。- 如需了解有关 MQL 的一般信息，请参阅使用 Monitoring 查询语言。
- 如需了解如何为图表提供 MQL 查询，请参阅从 Monitoring API 使用 MQL：图表。
如果您通过 Google Cloud 控制台创建了信息中心 widget，那么您已经非常熟悉指标和时序。
如需了解指标和时序，请参阅指标、时序和资源。
以下指南也可能会对您有所帮助：
虽然这些指南是使用 Google Cloud 控制台创建信息中心的，但这些概念也适用于使用 Cloud Monitoring API 创建微件。
示例设置
本部分介绍了使用 curl 工具调用 Cloud Monitoring API 的规则和设置。本文档中的示例使用 curl 工具向 REST 端点发送 HTTP 请求来访问该 API。如需设置示例调用中使用的变量，请使用以下信息。
Authentication
创建环境变量来存放 Google Cloud 项目的 ID。这些示例使用
PROJECT_ID：PROJECT_ID=a-gcp-project-12345
向 Google Cloud CLI 进行身份验证：
gcloud auth login（可选）您不必使用每个命令都指定项目 ID，只需使用 gcloud CLI 将其设为默认命令即可：
gcloud config set project ${PROJECT_ID}创建授权令牌并将其存储到环境变量中。 这些示例调用变量
ACCESS_TOKEN：ACCESS_TOKEN=`gcloud auth print-access-token`您必须定期刷新访问令牌。如果原来正常工作的命令突然报告您未通过身份验证，请重新发布该命令。
要验证您是否已获得访问令牌，请回显
ACCESS_TOKEN变量：echo ${ACCESS_TOKEN} ya29.ImW8Bz56I04cN4qj6LF....创建环境变量来存放信息中心的 ID。这些示例使用变量
DASHBOARD_ID。
调用 curl
每个 curl 调用都包含一组参数，其后面是资源的网址。常见参数包括由 PROJECT_ID、DASHBOARD_ID 和 ACCESS_TOKEN 环境变量指定的值。您可能还需要指定其他参数，例如，指定 HTTP 请求的类型（例如，-X DELETE）。
每个 curl 调用具有以下一般结构：
curl -H "Authorization: Bearer $ACCESS_TOKEN" <other_args> https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/<request>
例如，如需列出项目中的所有自定义信息中心，请发出以下请求：
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards
下图说明了该命令对一个 Google Cloud 项目的响应：
{
"dashboards": [
{
"name": "projects/123456789000/dashboards/c2ab1f1c-b8b9-1234-9c48-c7745802b659",
"displayName": "Grid-layout example",
"etag": "76a95cc500a7c7d6b3799709c13afe91",
"gridLayout": {
"widgets": [
{
"text": {
"content": "Text Widget 1",
"format": "RAW"
}
},
{
"text": {
"content": "**Text Widget 2**",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "_Text Widget 3_",
"format": "MARKDOWN"
}
}
]
}
},
{
"name": "projects/123456789000/dashboards/cae85db7-6920-4e67-a45c-97a94c0e2679",
"displayName": "Row-layout example",
"etag": "a600be01afe0b37762cd7a9b92fc3e7e",
"rowLayout": {
"rows": [
{
"widgets": [
{
"text": {
"content": "Text Widget 1",
"format": "RAW"
}
},
{
"text": {
"content": "**Text Widget 2**",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "_Text Widget 3_",
"format": "MARKDOWN"
}
}
]
}
]
}
}
]
}
创建信息中心
如需创建新的自定义信息中心，请调用 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 值。