使用 API 配置指标范围

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

本页面中的命令引用的是“资源容器”。虽然资源容器可以是组织、文件夹或项目，但本页面介绍的命令仅支持 Google Cloud 项目。

准备工作

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

  • 确保范围项目以及要添加为受监控项目的每个项目上的 Identity and Access Management (IAM) 角色包含 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 启用数据读取。如需了解详情，请参阅配置数据访问审核日志。

将项目添加到指标范围

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

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

  • 在变量 SCOPING_PROJECT_ID_OR_NUMBER 中输入要修改其指标范围的 Google Cloud 项目的名称或 ID。

  • 在变量 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 控制台对指标范围进行的修改不会记录在审核日志中。

从指标范围中移除项目

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

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

  • 在变量 SCOPING_PROJECT_ID_OR_NUMBER 中输入要修改其指标范围的 Google Cloud 项目的名称或 ID。

  • 在变量 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 结合使用，请参阅以下资源：