按 API 管理信息中心

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页面介绍如何在 Cloud Monitoring API 中使用 Dashboard 资源管理自定义信息中心和这些信息中心内的微件。您还可以通过 Google Cloud Console 管理自定义信息中心,但该 API 提供了一种以编程方式管理多个信息中心的程序化方式。您还可以使用 Cloud Monitoring API 创建、配置和操纵信息中心微件。

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

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

您不能使用 API 检索、修改或删除预定义的信息中心。

开始前须知

创建信息中心时,您必须指定要显示的组件或微件,以及这些微件的布局。

信息中心布局

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

  • GridLayout:将可用空间划分为等宽的垂直列,并使用行优先策略排列一组微件。

  • MosaicLayout:将可用空间划分为网格。每个微件可以占用一个或多个网格块。

  • RowLayout:将可用空间划分为不同的行,并在每行中横向安排一组微件。

  • ColumnLayout:将可用空间划分为垂直列,并在每一列中垂直排列一组微件。

例如,下面显示了 RowLayout 中带有三个 Text 微件的信息中心的 JSON 表示法:

{
  "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 创建的折线图、条形图、堆叠面积图和热图图表都是此微件的实例。创建折线图、堆叠条形图或堆叠面积图时,您可以指定指标引用左侧或右侧的 Y 轴。绘制多个指标的图表时,您可以使用两个 Y 轴。

    SLO 图表也是 XyChart 微件的实例,但不支持使用 API 创建 SLO 图表。

  • AlertChart:显示单条件提醒政策的摘要。此微件以线形图的形式显示数据,显示阈值并列出待解决的突发事件数量。

  • CollapsibleGroup:显示微件的集合。您可以收起群组视图。要在信息中心包含这些微件,信息中心必须具有 MosaicLayout

  • LogsPanel:显示存储在当前 Google Cloud 项目中的项目级日志条目。您可以配置微件,以显示可通过当前指标范围访问的 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"
          }
        }
      }
    ]
  }
}

指定要显示的数据

任何显示从时间序列检索的数据的微件中都有嵌入的 TimeSeriesQuery 对象。此对象指定要在微件中使用的时间序列数据。

您可以按如下方式指定要显示的时间序列数据:

如果您是通过 Google Cloud Console 创建的信息中心微件,那么您已经很熟悉指标和时间序列。

如需了解指标和时间序列,请参阅指标、时间序列和资源

此外,您可能会发现创建和管理信息中心微件选择要在图表中显示的数据设置视图选项指南很有帮助。虽然这些指南是使用 Google Cloud Console 创建信息中心的编写,但这些概念也适用于使用 Cloud Monitoring API 创建微件。

使用 curl 的示例

本部分介绍了使用 curl 工具调用 Cloud Monitoring API 的惯例和设置。本页面上的示例使用 curl 工具向 REST 端点发送 HTTP 请求来访问 API。如需设置示例调用中使用的变量,请使用以下信息。

身份验证

  1. 创建一个环境变量来保存您的 Cloud 项目 ID。以下示例使用 PROJECT_ID

    PROJECT_ID=a-gcp-project-12345
    
  2. 向 Google Cloud CLI 进行身份验证:

    gcloud auth login
    
  3. (可选)您可以使用 gcloud CLI 将项目 ID 设置为默认值,从而避免为每个命令指定项目 ID:

    gcloud config set project ${PROJECT_ID}
    
  4. 创建授权令牌并将其捕获到环境变量中。以下示例调用变量 ACCESS_TOKEN

    ACCESS_TOKEN=`gcloud auth print-access-token`
    

    您必须定期刷新访问令牌。如果正常工作的命令突然报告您未经身份验证,请重新发出此命令。

  5. 如需验证是否已获得访问令牌,请回显 ACCESS_TOKEN 变量:

    echo ${ACCESS_TOKEN}
    ya29.ImW8Bz56I04cN4qj6LF....
    
  6. 创建一个环境变量来保存信息中心的 ID。这些示例使用变量 DASHBOARD_ID

调用 curl

每次 curl 调用都包含一组参数,后跟资源的网址。通用参数包括 PROJECT_IDDASHBOARD_IDACCESS_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

下面演示了一个 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

如需了解详情,请参阅 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/${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

获取信息中心

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

协议

如需获取特定的自定义信息中心,请将信息中心 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 方法并在响应中找到它。

协议

要更新自定义信息中心,请向 Dashboard 端点发送 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 值。