使用 API 管理指标范围

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

如需将 AWS 帐号与 Google Cloud 项目的指标范围相关联,您必须使用 Google Cloud Console。如需了解详情,请参阅查看 AWS 帐号的指标

准备工作

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

  • 确保您在范围项目上的 Identity and Access Management (IAM) 角色可让您修改该项目的指标范围。

  • 对于您要添加为受监控项目的每个项目,请确保您的 IAM 角色可让您修改项目的指标范围。 如需了解所需的 IAM 角色,请参阅指标范围配置

  • Cloud Monitoring API 检索信息的指标范围方法是同步的;但是,更改状态的 API 是异步的。如需了解如何确定异步方法何时完成以及如何确定其状态,请参阅异步 API 方法

curl 命令参数

您可以直接调用指标范围 API。本页提供了使用 curl 的示例命令。每个 curl 命令都包含一组参数,后跟 API 资源的网址:

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

本页中的示例依赖于以下环境变量:

  • TOKEN:存储身份验证令牌。
  • SCOPING_PROJECT_ID_OR_NUMBER:存储指标范围限定项目的 ID 或编号。
  • MONITORED_PROJECT_ID_OR_NUMBER:存储要添加到指标范围或从中移除的项目的 ID 或编号。

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

如需了解示例所需的设置,请参阅 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 启用数据读取。如需了解详情,请参阅配置数据访问审核日志

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

如需获取可查看项目指标的指标范围的列表,请向 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 启用数据读取。如需了解详情,请参阅配置数据访问审核日志

将项目添加到指标范围

如需将 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": "GCP",
    "providerAccountId": "...",
    ...
  }
}

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

调用此方法会在范围限定项目的审核日志中生成一个条目。如果您使用 Cloud Console 将项目添加到指标范围,则该操作不会记录在审核日志中。Cloud Console 不调用此 API 方法。

从指标范围中移除项目

如需从指标范围中移除 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 字段。

调用此方法会在范围限定项目的审核日志中生成一个条目。如果您使用 Cloud Console 从指标范围中移除项目,则该操作不会记录在审核日志中。Cloud Console 不调用此 API 方法。

异步 API 方法

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

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

  • donefalse 时,表示操作正在进行中。

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

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

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

  • donetrue 时,表示操作已完成且已设置 errorresponse 字段:

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

curl 命令设置

本部分介绍用于在本文档中创建 curl 命令的设置。

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

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

    SCOPING_PROJECT_ID_OR_NUMBER=a-sample-project
    
  2. 可选。如果您计划添加或移除受监控的项目,请使用受监控项目 ID 或编号来配置环境变量:

    MONITORED_PROJECT_ID_OR_NUMBER=a-monitored-project
    
  3. 向 Cloud SDK 验证身份:

    gcloud auth login
    
  4. 可选。为避免必须使用每个 gcloud 命令指定项目 ID,请使用 Cloud SDK 将项目 ID 设置为默认值:

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}
    
  5. 创建授权令牌并将其存储到环境变量中:

    TOKEN=`gcloud auth print-access-token`
    

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

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

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