本页面介绍如何使用 Cloud Monitoring API 中的 Dashboard 资源管理自定义信息中心和图表。虽然您也可以通过 Google Cloud Console 管理自定义信息中心，但 API 为您提供了同时管理多个信息中心的程序化方式。此外，由于图表是作为信息中心上的微件实现的，因此您还可以使用 Cloud Monitoring API 创建、配置和操作图表。
该端点支持以下方法来管理和配置信息中心：
dashboards.create：创建新信息中心dashboards.delete：删除指定的信息中心dashboards.list：检索给定项目中所有信息中心的列表dashboards.get：检索指定的信息中心dashboards.patch：更新指定信息中心的结构
您可以使用 curl 实用程序或使用 gcloud 命令行工具直接调用 API。
您无法使用 API 检索、修改或删除预定义的信息中心。
准备工作
通过执行以下操作，为您的项目配置 Cloud Monitoring 工作区：- 在 Cloud Console 中，选择您的 Google Cloud 项目。
转到 Cloud Console - 在导航窗格中，选择 Monitoring。
如果您从未使用过 Cloud Monitoring，那么您在 Google Cloud Console 中首次访问 Monitoring 时，系统会自动创建一个工作区，并将您的项目与该工作区相关联。否则，如果您的项目未与工作区关联，则系统会显示一个对话框，您可以创建一个工作区，也可以将您的项目添加到现有工作区。我们建议您创建一个工作区。完成选择后，请点击添加。
创建信息中心时，您必须指定要显示的组件或微件，以及这些微件的布局。
定义信息中心布局
布局定义了信息中心组件的排序方式。该 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 Console 创建的图表是此微件的实例。Scorecard：显示指标的最新值，以及该值与一个或多个阈值的关系。您只能使用 API 创建此微件。Text：以原文或 Markdown 字符串的形式显示文字内容。您只能使用 API 创建此微件。
除了这些对象之外，您还可以向信息中心添加空白占位符。
例如，下面显示了 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"
}
}
}
]
}
}
指定要显示的数据
任何显示从时间序列检索到数据的微件都将嵌入一个 TimeSeriesQuery 对象。此对象用于指定在微件中使用的时间序列数据。
您可以按如下方式指定要显示的时间序列数据：
使用 Monitoring 过滤器。过滤条件用于
TimeSeriesFilter和TimeSeriesFilterRatio查询中。如需详细了解如何以这种方式检索指标数据，请参阅读取指标数据。使用 Monitoring Query Language (MQL)。此方法在
TimeSeriesQuery对象中使用 MSQL 查询。查询字符串将作为timeSeriesQueryLanguage字段的值进行传递。- 如需一般性信息，请参阅使用 Monitoring Query Language。
- 如需了解如何为图表提供 MQL 查询，请参阅使用 Monitoring API 中的 MQL：图表。
如果您是通过 Google Cloud Console 创建的图表，则表示您已熟悉指标和时间序列。除了 XyChart 之外，您还可以使用 Cloud Monitoring API 通过其他微件直观呈现数据。
如需了解指标和时间序列，请转到指标、时间序列和资源。
此外，您可能会发现创建图表、选择指标和设置查看选项指南也很有帮助。虽然这些指南是为通过 Google Cloud Console 创建图表而编写的，但也适用于创建图表、选择指标和选择视图选项等概念，此外还可用于使用 Cloud Monitoring API 创建图表。
使用 curl 的示例
本部分介绍了使用 curl 工具调用 Cloud Monitoring API 的规则和设置。本页中的示例通过使用 curl 工具将 HTTP 请求发送到 REST 端点来访问 API。在身份验证和调用 curl 时使用以下信息，来设置示例调用中使用的变量。
身份验证
创建环境变量来保存 Cloud Monitoring 工作区宿主项目的 ID。这些示例使用
HOST_PROJECT_ID：HOST_PROJECT_ID=a-gcp-project-12345
您必须将
HOST_PROJECT_ID设置为工作区宿主项目的 ID。如果有任何其他值，则创建或修改信息中心的 API 命令将失败并显示错误代码400和“不在工作区”的错误消息。对 Cloud SDK 进行身份验证：
gcloud auth login或者，您可以使用 Cloud SDK 将其设置为默认值来避免为每个命令指定项目 ID：
gcloud config set project ${HOST_PROJECT_ID}创建授权令牌并将其存储到环境变量中。 这些示例调用变量
ACCESS_TOKEN：ACCESS_TOKEN=`gcloud auth print-access-token`您必须定期刷新访问令牌。如果原来正常工作的命令突然报告您未通过身份验证，请重新发布该命令。
如需验证您是否已获得访问令牌，请回显
ACCESS_TOKEN变量：echo ${ACCESS_TOKEN} ya29.ImW8Bz56I04cN4qj6LF....
调用 curl
每个 curl 调用都包含一组参数，其后面是资源的网址。常见参数包括由 HOST_PROJECT_ID 和 ACCESS_TOKEN 环境变量指定的值。您可能还需要指定其他参数，例如，指定 HTTP 请求的类型（例如，-X DELETE）。
每个 curl 调用具有以下一般结构：
curl -H "Authorization: Bearer $ACCESS_TOKEN" <other_args> https://monitoring.googleapis.com/v1/projects/${HOST_PROJECT_ID}/<request>
例如，如需列出项目中的所有信息中心，请发出以下请求：
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${HOST_PROJECT_ID}/dashboards
此请求会返回与您的项目关联的信息中心列表：
{
"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/[HOST_PROJECT_ID]/dashboards/[DASHBOARD_ID]"
您必须将 HOST_PROJECT_ID 设置为工作区宿主项目的 ID。如果有任何其他值，则创建或修改信息中心的 API 命令将失败并显示错误代码 400 和“不在工作区”的错误消息。
协议
如需创建新的信息中心，请向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/${HOST_PROJECT_ID}/dashboards
gcloud
如需在项目中创建信息中心，请使用 gcloud monitoring dashboards
create 命令。
gcloud monitoring dashboards create --config-from-file=my-dashboard.json
如需了解详情，请参阅 gcloud monitoring dashboards
create 参考文档。
这些示例使用 my-dashboard.json 文件创建示例信息中心。
您现在可以通过 Google Cloud Console 管理信息中心。
有关其他信息中心配置，请转到示例信息中心和布局。
删除信息中心
如需删除自定义信息中心，请调用 dashboards.delete 方法并指定要删除的信息中心。
协议
如需删除自定义信息中心，请向 Dashboard 端点发送一个 DELETE 请求，并使用要删除的信息中心的 ID 进行限定。
curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${HOST_PROJECT_ID}/dashboards/[DASHBOARD_ID]
如果成功，该方法将返回一个空响应。否则，将返回错误。
gcloud
要删除自定义信息中心，请使用 gcloud monitoring dashboards delete 并指定要删除的信息中心的完全限定 ID：
gcloud monitoring dashboards delete projects/[HOST_PROJECT_ID]/dashboards/[MY_DASHBOARD_ID]
如需了解详情，请参阅gcloud monitoring dashboards
delete参考文档。
列出信息中心
如需列出属于项目的所有自定义信息中心，请调用 dashboards.list 方法并指定项目 ID。
协议
要列出项目的所有自定义信息中心，请将项目 ID 发送到Dashboard端点。
curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${HOST_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/${HOST_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/${HOST_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/${HOST_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 值。