使用 API 配置指标范围

本文档介绍了如何使用 Google Cloud CLI 或 Cloud Monitoring API，用于配置 Google Cloud 项目的指标范围。 本页面适用于开发者和系统管理员。

本页中的命令是指资源容器，它始终是 Google Cloud 项目。

准备工作

  • 如果您不熟悉术语“指标范围”和“范围项目”，请参阅指标范围。

  • 请确保您在 范围项目以及您为该项目指定的每个项目 添加监控项目的 Monitoring Admin (roles/monitoring.admin) 角色。 如需了解详情，请参阅指标范围配置。

  • Cloud Monitoring API 检索信息的指标范围方法是同步的；但是，更改状态的 API 是异步的。Google Cloud CLI 命令会阻塞，直到异步操作完成。有关如何确定 何时异步 API 方法完成以及如何确定其状态， 请参阅异步 API 方法。

  • 如果您打算使用 curl 调用 Cloud Monitoring API，或者 使用此页面上的示例，然后完成 curl 命令设置步骤。

列出包含项目的所有指标范围

gcloud

要获取指标范围列表，以便查看 资源容器（例如 Google Cloud 项目）运行 gcloud beta monitoring metrics-scopes list 命令：

gcloud beta monitoring metrics-scopes list MONITORED_RESOURCE_CONTAINER_NAME

在运行该命令之前，请将资源容器的标识符输入变量 MONITORED_RESOURCE_CONTAINER_NAME。如果资源容器是 Google Cloud 项目，请输入 projects/PROJECT_ID_OR_NUMBER。

例如，如需列出包含项目 my-project 的指标范围，请运行以下命令：

gcloud beta monitoring metrics-scopes list projects/my-project

以下响应表明项目 my-project 包含在两个指标范围中：

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

如需获取有关指标范围的详细信息，请运行 gcloud beta monitoring metrics-scopes describe 命令。

curl

如需获取可查看项目指标的指标范围的列表，请向 locations.global.metricsScopes.listMetricsScopesByMonitoredProject 端点发送 GET 请求并添加指定项目的查询参数。

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

成功后，响应将是一组 MetricsScope 对象。

此方法不会导致系统将条目写入范围限定项目的审核日志。如需将这些操作记录在审核日志中，请为 Cloud Resource Manager API 启用数据读取。如需了解详情，请参阅配置数据访问审核日志。

获取指标范围的详细信息

gcloud

如需获取有关指标范围的详细信息，请运行 gcloud beta monitoring metrics-scopes describe 命令：

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

在运行该命令之前，请将指标范围的完全限定名称输入变量 METRICS_SCOPE_ID。以下是完全限定名称的示例：

locations/global/metricsScopes/012345012345

下面是一个响应示例。在本例中，指标范围包含一个项目，并且指标范围和项目的 ID 相同：

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

如需通过 ID 识别 Google Cloud 项目，请运行 gcloud projects list 命令并按项目 ID 过滤。例如，如需获取项目 012345012345 的名称，请运行以下命令：

gcloud projects list --filter="012345012345" --format="value(NAME)"

curl

如需获取有关指标范围的信息，请向 locations.global.metricsScopes.get 端点发送 GET 请求：

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

成功后，该响应是一个 MetricsScope 对象。

此方法不会导致系统将条目写入范围限定项目的审核日志。如需将这些操作记录在审核日志中，请为 Cloud Resource Manager API 启用数据读取。如需了解详情，请参阅配置数据访问审核日志。

将项目添加到指标范围

如果您使用的是 App Hub，请查看系统指标 必须同时配置 App Hub 宿主项目和指标范围。将 App Hub 服务项目添加到 App Hub 宿主项目不会修改项目的指标范围。同样，将项目添加到 指标范围不会修改 关联到的 App Hub 服务项目 App Hub 宿主项目。如需了解如何配置 App Hub 宿主项目，请参阅添加或移除服务项目。

gcloud

如需将资源容器（例如 Google Cloud 项目）添加到指标范围，请运行 gcloud beta monitoring metrics-scopes create 命令：

gcloud beta monitoring metrics-scopes create MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

在运行上一个命令之前，请执行以下操作：

  • 输入指标范围是哪个 Google Cloud 项目的名称或 ID 更改为变量 SCOPING_PROJECT_ID_OR_NUMBER。

  • 将资源容器的标识符输入变量 MONITORED_RESOURCE_CONTAINER_NAME。如果资源容器是 Google Cloud 项目，请输入 projects/PROJECT_ID_OR_NUMBER。

例如，以下命令会将项目 my-monitored-project 添加到名为 my-staging-projects 的项目的指标范围中：

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

上一个命令的响应会确认该命令已成功完成：

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

如需将 Google Cloud 项目添加到指标范围，请向 locations.global.metricsScopes.projects.create 端点发送 POST 请求。在以下示例中，环境变量 MONITORED_PROJECT_ID_OR_NUMBER 标识的项目会添加为受监控的项目：

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

此异步方法的响应是一个 Operation 对象。

调用此方法的应用应轮询 operation.get 端点，直到 Operation.done 字段的值为 true。当 Operation.done 字段设置为 false 时，表示操作正在进行中。如需了解详情，请参阅异步 API 命令。

下面是成功添加受监控项目时的响应示例：

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

在上一个响应中，Operation.done 字段设置为 true。此值表示命令已完成。由于命令成功完成，因此 Operation.response 字段已设置且其值为 MonitoredProject 对象。response.name 字段包含范围限定项目和受监控项目的标识符。providerAccountId 字段列出了受监控项目的名称。

调用此方法会在范围限定项目的审核日志中生成一个条目。Google Cloud 控制台不调用此 API 方法。 因此，使用 审核日志不会记录 Google Cloud 控制台。

从指标范围中移除项目

如果您使用的是 App Hub，请先移除 指标范围内的项目可确保该项目未被 一个 App Hub 应用从指标范围中移除项目不会影响应用。不过，您将无法在 App Hub 宿主项目的上下文中查看该应用的系统指标。如需了解如何配置 App Hub 宿主项目，请参阅 添加或移除服务项目。

gcloud

如需移除 Google Cloud 项目等资源容器，请执行以下操作： 从指标范围运行 gcloud beta monitoring metrics-scopes delete 命令：

gcloud beta monitoring metrics-scopes delete MONITORED_RESOURCE_CONTAINER_NAME --project=SCOPING_PROJECT_ID_OR_NUMBER

在运行上一个命令之前，请执行以下操作：

  • 输入指标范围是哪个 Google Cloud 项目的名称或 ID 更改为变量 SCOPING_PROJECT_ID_OR_NUMBER。

  • 将资源容器的标识符输入变量 MONITORED_RESOURCE_CONTAINER_NAME。如果资源容器是 Google Cloud 项目，请输入 projects/PROJECT_ID_OR_NUMBER。

例如，以下命令会从名为 my-staging-projects 的项目的指标范围中移除项目 my-monitored-project：

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

对上一条命令的响应会确认命令 已成功完成：

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

如果限定范围的项目未监控 MONITORED_RESOURCE_CONTAINER_NAME 变量指定的项目，则会报告以下错误：

NOT_FOUND: Requested entity was not found.

curl

如需从指标范围中移除 Google Cloud 项目，请向 locations.global.metricsScopes.projects.delete 端点发送 DELETE 请求：

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

对此异步方法的响应是一个 Operation 对象。

调用此方法的应用应轮询 operation.get 端点，直到 Operation.done 字段的值为 true。当 Operation.done 字段设置为 false 时，表示操作正在进行中。如需了解详情，请参阅异步 API 命令。

下面是成功移除受监控项目时的响应示例：

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

在上一个响应中，Operation.done 字段设置为 true。此值表示命令已完成。由于命令成功完成，因此 Operation.response 字段已设置且包含 @type 字段。

调用此方法会在范围限定项目的审核日志中生成一个条目。Google Cloud 控制台不调用此 API 方法。 因此，使用 Google Cloud 控制台时对指标范围的修改不会记录在审核日志中。

异步 API 方法

Cloud Monitoring API 更改系统状态的所有指标范围方法都是异步的，例例如向受监控项目添加指标范围的命令。对于这些命令，命令响应是一个 Operation 对象。

调用异步 API 方法的应用应轮询 operation.get 端点，直到 Operation.done 字段的值为 true：

  • 当 done 为 false 时，表示操作正在进行中。

    如需刷新状态信息，请向 operation.get 端点发送 GET 请求：

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    在上一个命令中，OPERATION_NAME 是一个环境变量，用于存储 Operation.name 字段的值。

  • 当 done 为 true 时，表示操作已完成且已设置 error 或 response 字段：

    • error：设置此标志时，表示异步操作失败。此字段的值是一个 Status 对象，其中包含 gRPC 错误代码和错误消息。
    • response：如果设置此标志，则表示异步操作成功完成，并且值将反映结果。

curl 命令设置

本部分介绍用于在本文档中创建 curl 命令的设置。此页面上的每个 curl 命令都包含一组 参数，后跟 API 资源的网址：

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

设置以下环境变量，来简化 curl 命令的创建过程：

  1. 创建环境变量以存储范围限定项目 ID 或编号：

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

  2. 可选。如果您计划添加或移除受监控的项目，请使用受监控的项目 ID 或编号来配置环境变量：

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. 向 Google Cloud CLI 进行身份验证：

    gcloud auth login

  4. 可选。避免为每个 gcloud 指定项目 ID 命令，请使用 gcloud CLI 将项目 ID 设置为默认值：

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. 创建授权令牌并将其存储到环境变量中：

    TOKEN=`gcloud auth print-access-token`

    令牌有效期有限。如果命令突然报告您未通过身份验证，请重新发布此命令。

  6. 要验证您是否已获得访问令牌，请回显 TOKEN 变量：

    echo ${TOKEN}
ya29.GluiBj8o....

您可能还需要指定其他参数，例如，指定 HTTP 请求的类型（例如 -X DELETE）。默认请求为 GET，因此示例未指定该请求。

后续步骤

如需了解如何将 Google Cloud 与 Terraform 结合使用，请参阅以下资源：