本文档介绍了如何使用 Google Cloud CLI 或 Cloud Monitoring API 配置 Google Cloud 项目的指标范围。本页面适用于开发者和系统管理员。
App Hub 应用和指标范围
您可以管理 App Hub 宿主项目的指标范围。您可以使用 Google Cloud 控制台或 Cloud Monitoring API 来管理此范围。
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 create 命令：
gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER
在运行上一个命令之前，请执行以下操作：
将要修改其指标范围的 Google Cloud 项目的名称或 ID 输入变量 SCOPING_PROJECT_ID_OR_NUMBER。对于 App Hub 配置，请选择 App Hub 主机项目或启用应用的文件夹的管理项目。
将所监控项目的标识符输入变量 MONITORED_PROJECT_ID_OR_NUMBER。格式为
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 请求：
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
在上面的示例中，环境变量定义如下：
MONITORED_PROJECT_ID_OR_NUMBER用于存储要添加到指标范围的项目的 ID。SCOPING_PROJECT_ID_OR_NUMBER用于存储要更新其指标范围的项目的 ID。
此异步方法的响应是一个 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 字段列出了受监控项目的名称。
调用此方法会在范围限定项目的审核日志中生成一个条目。Google Cloud 控制台不调用此 API 方法。 因此，使用 Google Cloud 控制台时对指标范围的修改不会记录在审核日志中。
从指标范围中移除项目
gcloud
如需从指标范围中移除 Google Cloud 项目，请运行 gcloud beta monitoring metrics-scopes delete 命令：
gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER
在运行上一个命令之前，请执行以下操作：
将要修改其指标范围的 Google Cloud 项目的名称或 ID 输入变量 SCOPING_PROJECT_ID_OR_NUMBER。对于 App Hub 配置，请选择 App Hub 主机项目或启用应用的文件夹的管理项目。
将所监控项目的标识符输入变量 MONITORED_PROJECT_ID_OR_NUMBER。格式为
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_PROJECT_ID_OR_NUMBER 变量指定的项目，则会报告以下错误：
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}
在上面的示例中，环境变量定义如下：
MONITORED_PROJECT_ID_OR_NUMBER用于存储要从指标范围中移除的项目的 ID。SCOPING_PROJECT_ID_OR_NUMBER用于存储要更新其指标范围的项目的 ID。
对此异步方法的响应是一个 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 控制台时对指标范围的修改不会记录在审核日志中。
列出包含项目的所有指标范围
如果您想知道哪些资源可以查看 Google Cloud 项目存储的数据，可以列出包含该项目的所有指标范围，然后查找这些范围的详细信息。本部分介绍了如何列出包含特定 Google Cloud 项目的指标范围。
gcloud
如需获取可查看 Google Cloud 项目指标的指标范围的列表，请运行 gcloud beta monitoring metrics-scopes list 命令：
gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER
在运行该命令之前，请将受监控项目的标识符输入变量 MONITORED_PROJECT_ID_OR_NUMBER。格式为 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}
在上例中，环境变量 PROJECT_ID_OR_NUMBER 存储了要查询是否包含在指标范围内的项目的 ID。
成功后，响应将是一组 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}
在前面的示例中，环境变量 SCOPING_PROJECT_ID_OR_NUMBER 存储了要查询其指标范围的项目的 ID。
成功后，该响应是一个 MetricsScope 对象。
此方法不会导致系统将条目写入范围限定项目的审核日志。如需将这些操作记录在审核日志中，请为 Cloud Resource Manager API 启用数据读取。如需了解详情，请参阅配置数据访问审核日志。
异步 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 命令的创建过程：
创建环境变量以存储范围限定项目 ID 或编号。如果您使用的是 App Hub，请将此变量设置为 App Hub 宿主项目的 ID 或启用应用的文件夹的管理项目的 ID：
SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER可选。如果您计划添加或移除受监控的项目，请使用受监控的项目 ID 或编号来配置环境变量：
MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER向 Google Cloud CLI 进行身份验证：
gcloud auth login可选。为避免必须使用每个
gcloud命令指定项目 ID，请使用 gcloud CLI 将项目 ID 设置为默认值：gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}创建授权令牌并将其存储到环境变量中：
TOKEN=`gcloud auth print-access-token`令牌有效期有限。如果命令突然报告您未通过身份验证，请重新发布此命令。
要验证您是否已获得访问令牌，请回显
TOKEN变量：echo ${TOKEN} ya29.GluiBj8o....
您可能还需要指定其他参数，例如，指定 HTTP 请求的类型（例如 -X DELETE）。默认请求为 GET，因此示例未指定该请求。
后续步骤
如需了解如何将 Google Cloud 与 Terraform 搭配使用，请参阅以下资源：