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

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

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

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

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

此功能仅适用于 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

信息中心简介

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

信息中心布局

布局定义了信息中心组件的排序方式。该 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 支持以下显示样式：

    • 折线图
    • 条形图
    • 堆叠面积图
    • 热图

  • 从一个维度显示的 widget（例如最新值）：

    • PieChart：显示一组时序的最新值，其中每个时序都会为饼图贡献一个扇区。

    • Scorecard：显示某个时序的最新值，以及该值与一个或多个阈值的关系。

    • TimeSeriesTable：显示每个时序的最新值或汇总值。表支持自定义。例如，您可以对单元格进行颜色编码，并配置列名称和数据校准。

  • 显示提醒政策或突发事件信息的 widget：

    • AlertChart：显示单一条件提醒政策的摘要。此 widget 以折线图的形式显示数据，并显示阈值及列出未结突发事件的数量。

    • IncidentList：显示突发事件列表。您可以将该 widget 配置为显示特定提醒政策或特定资源类型的突发事件。

  • 显示日志条目和错误的 widget：

  • 文本和组织 widget：

    • CollapsibleGroup：显示一组 widget。您可以收起组视图。

    • SingleViewGroup：显示一组 widget 中的一个 widget。您可以选择要显示的 widget。

    • SectionHeader：在信息中心内创建一个水平分隔线，并在信息中心的目录中创建一个条目。

    • Text：以原文或 Markdown 字符串的形式显示文字内容。

    如需在信息中心中添加文本和组织 widget，信息中心必须具有 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 以指明信息中心包含有助于您排查失败问题的信息。

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

例如，下面展示了指定名为 playbook 的标签的 Dashboard 对象。

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

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

信息中心过滤条件和变量

在设计信息中心时，您可能会确定多种查看信息中心显示的数据的方式。例如，假设信息中心显示虚拟机 (VM) 实例的时序数据。您可能希望查看所有虚拟机的时序数据，也可能希望仅查看特定可用区中的数据。在这种情况下，我们建议您创建固定的过滤条件或变量，然后将该过滤条件的默认值设置为最常查看的可用区。

固定的过滤条件会应用于支持过滤条件中指定的标签的所有信息中心 widget，除非该 widget 包含具有相同标签键的过滤条件。例如，当某个图表包含过滤条件 zone = us-central1-a 时，该图表会忽略标签键为 zone 的固定过滤条件。同样，如果图表没有键为 zone 的标签，则系统会忽略此过滤条件。

变量类似于固定的过滤条件，但仅应用于特定 widget。变量可以基于标签（例如固定的过滤条件），也可以仅包含一个值。仅包含值的变量包含一个或多个默认值，以及所有可能的值列表。如果您未指定默认值，则默认值会设置为通配符运算符 (*)。如需定义所有可能的值集合，您可以提供值数组或编写 SQL 查询。

对于查询数据的 widget，您可以在 widget 的查询中添加变量，并可以使用变量来控制 widget 的可见性。如果查询依赖于变量，则在您更改变量的值时，widget 请求的数据也会更改。因此，显示的数据也会更改。当您使用变量来控制 widget 的可见性时，工具栏中会显示 可见图标。如需了解与可见性相关的限制，请参阅设置 widget 的可见性。

对于固定的过滤条件和变量，信息中心工具栏会显示每个变量，以及一个菜单，您可以通过该菜单临时更改变量的值。固定的过滤条件和变量使用相同的数据结构进行表示。为了帮助您区分过滤条件和变量，在工具栏中，变量名称前面会附加美元符号 $。如需了解详情，请参阅 DashboardFilter。

如需查看示例，了解如何使用变量来控制 widget 的可见性，请参阅已配置 widget 可见性的信息中心。

如需了解如何使用基于标签的变量或仅包含值的变量更新 widget 的查询，请参阅以下部分：

创建过滤条件和变量

控制台

如需了解如何使用 Google Cloud 控制台创建固定的过滤条件和变量，请参阅以下文档：

API

如需定义固定的过滤条件和变量，请使用 dashboardFilters 数据结构。

  • 如需创建变量，请将 templateVariable 字段的值设置为变量的名称。如果您想创建固定的过滤条件，请省略此字段或将值设置为空字符串。
  • 如需创建固定的过滤条件或基于标签的变量，您必须指定 labelKey 字段。如果您需要仅包含值的变量，请省略此字段。

  • 设置过滤条件或变量的默认值。此字段的配置决定了用户能否从值菜单中仅选择一个选项，或者能否选择多个值。

    • 如需设置单个默认值以及限制用户在值菜单中仅选择一个选项，请将 valueType 字段设置为 STRING，并设置 stringValue 字段：
    "valueType": "STRING",
"stringValue": "my-default-value",
    • 如需设置至少一个默认值并允许用户在值菜单中选择多个选项，请将 valueType 字段设置为 STRING_ARRAY，并设置 stringArrayValue 字段。在以下示例中，有三个默认值。
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • 可选：如需为仅包含值的变量指定所有可能的值列表，请设置 stringArray 字段或 timeSeriesQuery 字段。如果您指定查询，则必须是分析查询。

例如，请考虑以下 dashboardFilters 对象：

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

上述 JSON 定义了一个固定的过滤条件和两个变量：

  • 固定的过滤条件的标签键为 zone，它会显示在工具栏上。valueType 和 stringValue 字段指定单个默认值。如需了解详情，请参阅 dashboardFilters 数据结构的 API 参考文档页面。

  • 基于标签的变量的名称为 my_label_based_variable，标签键为 instance_id。此变量的默认值设置为特定实例 ID。您还可以使用数组来配置默认值。在工具栏上，系统会显示过滤条件以及名称 my_label_based_variable。

  • 仅包含值的变量名为 my_value_only_variable。此条目未指定默认值，因此系统会自动应用通配符运算符 (*)。此外，此变量使用 SQL 查询生成变量的可能的值列表。

请注意，dashboardFilters 对象不会列出变量应用于的 widget。您需要更新 widget 的查询，使其依赖于变量。

取消引用变量的一般语法

对于所有 widget（由 SQL 定义的 widget 除外），请使用以下语法将变量应用于查询：

  • 如需应用基于标签的变量，并将标签键和标签值解析为查询语言的有效过滤条件表达式，请使用 ${my_label_based_variable}。

  • 如需仅应用基于标签的变量值，请使用 ${my_label_based_variable.value}。比较必须使用正则表达式。

  • 如需仅应用仅包含值的变量的值，请使用 ${my_value_only_variable}。对于仅包含值的变量，请勿添加 .value 子句。比较必须使用正则表达式。

日志面板 widget

如需将变量应用于日志面板 widget，请更新查询窗格。这些 widget 的语法遵循一般语法下指定的语法。

控制台

例如，以下查询使用正则表达式将 jsonPayload.message 字段的值与包含基于标签的变量值的字符串值进行比较：

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

再举一个示例，请考虑一个仅包含值的变量 value_only_severity_variable，并且假设在值菜单中选择了三个值：ERROR、INFO 和 NOTICE。接下来，您将以下内容添加到日志面板 widget 的查询窗格中：

severity =~ "${value_only_severity_variable}"

下面展示了呈现的表单：

severity =~ "^(ERROR|INFO|NOTICE)$"

API

例如，以下 JSON 说明了如何使用基于标签的变量更新日志面板 widget 的查询：

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

例如，以下查询使用正则表达式将 jsonPayload.message 字段的值与包含基于标签的变量值的字符串值进行比较：

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

再举一个示例，请考虑一个仅包含值的变量 value_only_severity_variable，并且假设在菜单中选择了三个值：ERROR、INFO 和 NOTICE。接下来，您将以下内容添加到日志面板 widget 的查询窗格中：

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

以下示例展示了日志面板 widget 执行的查询：

severity =~ "^(ERROR|INFO|NOTICE)$"

如果您已为日志面板配置查询，然后选择相应按钮以打开 Logs Explorer，则系统会在打开 Logs Explorer 之前解析变量。

下表说明了日志面板如何解析示例变量。如上所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

语法 所选
值		 已解析的日志面板表达式
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

示例变量基于资源标签 instance_id。
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

包含 PromQL 查询的图表

如需更新包含 PromQL 查询的图表，使其依赖于基于标签的变量，请按照一般语法中列出的指导操作。

控制台

例如，以下查询依赖于基于标签的变量 my_label_based_variable 解析为过滤表达式：

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

您还可以修改查询，使其仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

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

如果您有仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

zone=~"${my_value_only_variable}"

API

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_variable 解析为过滤表达式：

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

您还可以修改查询，使其仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

如果您有仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

zone=~\"${my_value_only_variable}\"

下表说明了 PromQL 如何解析示例变量。如上所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

语法 所选
值		 已解析的 PromQL 表达式
${my_label_based_variable} 12345 instance_id == '12345'

示例变量基于资源标签 instance_id。
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

包含 SQL 查询的图表

如果您想更新 SQL 定义的 widget，使其依赖于变量，请更新 WHERE 子句以引用该变量的值。对于所有变量，请使用“at”符号作为变量名称的前缀，例如：@variable_name。对于基于标签的变量，请在变量名称后附加 .value (@my_label_based_variabe.value)。

对于 SQL 查询，变量替换依赖于 BigQuery，并且不会受到 SQL 注入的影响。如需了解详情，请参阅运行参数化查询。

控制台

由于 SQL 不会将通配符运算符解释为“任何值”，因此我们建议您在 SQL 查询中使用变量时始终使用 IF 语句。以下示例说明了其数据类型为字符串的仅包含值的变量的用法：

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

如果变量的菜单选项允许用户选择多个值，则必须使用 CAST 函数将变量的值转换为 GoogleSQL 数据类型。以下查询展示了此语法：

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

建议使用前面的示例中所示的 IF 语句，因为 SQL 不会将通配符运算符解释为“任何值”。因此，如果您省略 IF 语句并选择通配符运算符，则查询结果为空表。在第二个示例中，UNNEST 函数会将数组转换为表。

如需添加格式正确的 WHERE 子句，请执行以下操作：

  1. 修改 widget。
  2. 在工具栏中，选择插入变量过滤条件，然后选择您要更新其 WHERE 子句的变量。
  3. 在打开的对话框中，查看生成的代码，然后点击复制并关闭。

  4. 将复制的代码粘贴到查询窗格中，并进行必要的修改。

    例如，假设您创建一个名为 LogName 的变量，该变量会生成日志名称列表，并将结果输出到包含一个名为 log_name 的列的表中。接下来，创建一个图表，选择插入变量过滤条件，然后选择变量 LogName。系统会生成以下代码：

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    在此示例中，您需要修改生成的代码，并将 LogName = 替换为 log_name =，以便进行表联接：

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. 点击运行，然后点击应用。

  6. 如需保存修改后的信息中心，请在工具栏中点击保存。

API

由于 SQL 不会将通配符运算符解释为“任何值”，因此我们建议您在 SQL 查询中使用变量时始终使用 IF 语句。以下示例说明了其数据类型为字符串的仅包含值的变量的用法：

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

例如，下面展示了显示 SQL 查询结果的图表的部分 JSON 表示法。为了支持按日志名称过滤结果，添加了一个引用名为 LogName 的变量的 WHERE 子句：

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

变量 LogName 还会发出查询，以确定可能的日志名称列表：

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

如果变量的菜单选项允许用户选择多个值，则必须使用 CAST 函数将变量的值转换为 GoogleSQL 数据类型。以下查询展示了此语法：

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

建议使用前面的示例中所示的 IF 语句，因为 SQL 不会将通配符运算符解释为“任何值”。因此，如果您省略 IF 语句并选择通配符运算符，则查询结果为空表。在第二个示例中，UNNEST 函数会将数组转换为表。

包含 Monitoring 过滤条件查询的图表

如需更新包含采用 Monitoring 过滤条件形式的查询的图表，使其依赖于基于标签的变量，请按照一般语法中列出的指导操作。

控制台

如果您使用 Google Cloud 控制台创建图表，并且使用菜单驱动的界面，则可以通过使用变量的应用于图表字段或通过修改 widget 并从过滤条件菜单中选择基于标签的变量来更新图表的查询。过滤条件菜单会列出所有基于标签的变量和所有标签键。

如需更新图表的查询，使其依赖于基于值的变量，请执行以下操作：

  1. 修改图表。
  2. 在查询窗格中，点击添加过滤条件，然后选择一个标签键。例如，您可以选择可用区。
  3. 在值菜单中，选择仅包含值的变量。
  4. 点击应用。
  5. 如需保存修改后的信息中心，请在工具栏中点击保存。

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_variable，解析为过滤条件表达式：

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

采用 Monitoring 过滤条件形式的查询的 widget 无法按基于标签的变量中的值过滤时序；但是，您可以按仅包含值的变量进行过滤。例如，以下查询展示了按 zone 进行过滤的查询的过滤条件字段的值，具体取决于仅包含值的变量的值：

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

API

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_variable，解析为过滤条件表达式：

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

采用 Monitoring 过滤条件形式的查询的 widget 无法按基于标签的变量中的值过滤时序；但是，您可以按仅包含值的变量进行过滤。例如，以下查询展示了按 zone 进行过滤的查询的 "filter" 字段，具体取决于仅包含值的变量的值：

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

下表说明了 Monitoring 过滤条件如何解析示例变量。如上所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

语法 所选
值		 已解析的过滤表达式
${my_label_based_variable} 12345 resource.instance_id == "12345"

示例变量基于资源标签 instance_id。
${my_label_based_variable} * 已忽略
${my_label_based_variable.value} 12345 不支持
${my_label_based_variable.value} * 不支持
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

准备工作

在您要创建和管理信息中心的 Google Cloud 项目中，完成以下操作：

创建信息中心

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

name 字段为可选字段。name 字段的值具有以下结构：

"name": "projects/PROJECT_ID_OR_NUMBER/dashboards/DASHBOARD_ID"

创建信息中心时，API 会自动生成 DASHBOARD_ID。如果您要指定自定义 DASHBOARD_ID，可以指定 Dashboard 对象的 name 字段。

gcloud

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

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

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

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

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

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

Terraform

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

如需使用 Terraform 创建信息中心，请执行以下操作：

  1. 为您的项目安装和配置 Terraform。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

  2. 使用 Terraform 资源 google_monitoring_dashboard。

    在命令中设置以下字段：

    • dashboard_json：信息中心的 JSON 表示形式（采用 Dashboards 格式）。

      如需查看此格式的示例，您可以使用 APIs Explorer 列出信息中心，也可以在 Google Cloud 控制台中打开信息中心并查看 JSON 表示形式。

    • parent：项目的完全限定名称。例如，您可以将此字段设置为 "projects/PROJECT_ID"，其中 PROJECT_ID 是您的 Google Cloud 项目的 ID。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

REST

如需创建新的信息中心，请向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

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

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

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

删除信息中心

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

gcloud

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

gcloud monitoring dashboards delete DASHBOARD_ID --project=PROJECT_ID

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • DASHBOARD_ID：信息中心的 ID。

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

Terraform

您可以使用 Terraform 删除资源。如需了解如何删除资源，请参阅 Terraform 命令 destroy。

REST

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

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

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • ${DASHBOARD_ID}：用于存储信息中心 ID 的环境变量。

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

列出信息中心

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

gcloud

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

gcloud monitoring dashboards list --project=PROJECT_ID

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

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

Terraform

您无法使用 Terraform 向项目发送查询，并将响应作为信息中心列表。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

REST

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

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

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

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

对列表响应进行分页

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

gcloud

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

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

Terraform

您无法使用 Terraform 向项目发送查询，并将响应作为信息中心分页列表。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

REST

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

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

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

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

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

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

获取信息中心

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

gcloud

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

gcloud monitoring dashboards describe DASHBOARD_ID --format=json --project=PROJECT_ID

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • DASHBOARD_ID：信息中心的 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 monitoring dashboards describe 参考文档。

Terraform

您无法使用 Terraform 向项目发送查询，并将响应作为单个信息中心。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

REST

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

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

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • ${DASHBOARD_ID}：用于存储信息中心 ID 的环境变量。

在上面的表达式中，${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"
}

更新信息中心

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

gcloud

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

gcloud monitoring dashboards update DASHBOARD_ID --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

在运行上述命令之前，请替换以下内容：

  • PROJECT_ID：项目的标识符。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • DASHBOARD_ID：信息中心的 ID。

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

上述示例使用 my-updated-dashboard.json 文件更新现有自定义信息中心。响应（其中包含新的 etag 值）是更新后的信息中心列表的副本。

Terraform

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

如需使用 Terraform 更新信息中心，请执行以下操作：

  1. 为您的项目安装和配置 Terraform。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

  2. 使用 Terraform 资源 google_monitoring_dashboard。

    在命令中设置以下字段：

    • dashboard_json：信息中心的 JSON 表示形式（采用 Dashboards 格式）。

    • parent：项目的完全限定名称。例如，您可以将此字段设置为 "projects/PROJECT_ID"，其中 PROJECT_ID 是您的 Google Cloud 项目的 ID。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

REST

要更新自定义信息中心，请将 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}

在运行上述命令之前，请配置以下各项：

  • ${PROJECT_ID}：用于存储要在其中创建信息中心的项目 ID 的环境变量。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
  • ${DASHBOARD_ID}：用于存储信息中心 ID 的环境变量。

上述示例使用 my-updated-dashboard.json 文件更新现有自定义信息中心。响应（其中包含新的 etag 值）是更新后的信息中心列表的副本。

后续步骤