管理使用方政策

预览版 — Hierarchical service activation

此功能 受服务专用条款的约束。 非正式版功能“按原样”提供，且可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

借助分层服务启用，您可以管理通过 Google Cloud 资源层次结构继承的服务启用状态。如需了解详情，请参阅概览。

ConsumerPolicy 是在Google Cloud 资源层次结构的每个级别中找到的 Service Usage API 资源。此资源始终命名为 default，包含用于定义已启用哪些服务的 enableRules。您可以修改 ConsumerPolicy 资源，而不是启用或停用特定服务。如果服务名称位于该列表中，则表示该服务已在该层次级别启用。

本文档介绍了如何使用 Google Cloud CLI 管理项目、文件夹和组织的消费者政策。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

如果您要使用现有项目来完成本指南，请验证您是否拥有完成本指南所需的权限。如果您创建了新项目，则您已拥有所需的权限。

Verify that billing is enabled for your Google Cloud project.

Enable the Service Usage API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable serviceusage.googleapis.com

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

如果您要使用现有项目来完成本指南，请验证您是否拥有完成本指南所需的权限。如果您创建了新项目，则您已拥有所需的权限。

Verify that billing is enabled for your Google Cloud project.

Enable the Service Usage API:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable serviceusage.googleapis.com

1. 如果您未指明要管理的 Google Cloud 资源，本文档中的命令将默认针对当前项目执行。例如，gcloud beta services policies get --policy-name=default 会返回当前项目的消费方政策。

   您可以检索当前项目 ID：

   gcloud config list --format='text(core.project)'

所需的角色

如需获得管理消费者政策所需的权限，请让您的管理员为您授予目标资源的 Service Usage Admin (roles/serviceusage.serviceUsageAdmin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含管理消费者政策所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能管理消费者政策：

• 获取消费者政策： serviceusage.consumerpolicy.get
• 更新消费者政策：
  • serviceusage.consumerpolicy.analyze
  • serviceusage.consumerpolicy.update
• 获取有效政策： serviceusage.effectivepolicy.get
• 检查服务是否已启用： serviceusage.values.test

您也可以使用自定义角色或其他预定义角色来获取这些权限。

获取消费者政策

您可以使用 gcloud beta services policies get 命令检索项目、文件夹或组织的 ConsumerPolicy。

此命令会返回在该确切资源级别设置的 enableRules，而不是继承的规则。如需查看包含继承规则的更完整视图，您可以检索有效政策。仅支持 default 政策名称。

项目

gcloud beta services policies get --policy-name=default \
    --project=PROJECT_ID \
    --output-file=OUTPUT_FILE

替换以下内容：

• PROJECT_ID：您的Google Cloud 项目 ID。 或者，省略该标志以默认使用当前项目。
• OUTPUT_FILE：（可选）输出文件的路径，用于保存消费者政策的内容。支持的文件格式为 JSON 和 YAML。

文件夹

gcloud beta services policies get --policy-name=default \
    --folder=FOLDER_ID \
    --output-file=OUTPUT_FILE

替换以下内容：

• FOLDER_ID：您的Google Cloud 文件夹 ID。
• OUTPUT_FILE：（可选）输出文件的路径，用于保存消费者政策的内容。支持的文件格式为 JSON 和 YAML。

组织

gcloud beta services policies get --policy-name=default \
    --organization=ORGANIZATION_ID \
    --output-file=OUTPUT_FILE

替换以下内容：

• ORGANIZATION_ID：您的Google Cloud 组织资源 ID。
• OUTPUT_FILE：（可选）输出文件的路径，用于保存消费者政策的内容。支持的文件格式为 JSON 和 YAML。

更新使用方政策

您可以使用 gcloud beta services policies update 命令更新 ConsumerPolicy。这样一来，您就可以替换当前政策，并使用 YAML 文件一次性更新许多已启用的服务。

此命令不会自动启用服务依赖项。您必须在输入文件中明确列出所有服务依赖项。您可以使用 --validate-only 标志在应用更改之前预览更改。

gcloud beta services policies update --consumer-policy-file=PATH_TO_CONSUMER_POLICY

将 PATH_TO_CONSUMER_POLICY 替换为包含消费者政策的 YAML 文件的路径，例如：

gcloud beta services policies update --consumer-policy-file=/path/to/the/file.yaml

支持的标志：

• --bypass-api-usage-check 以绕过使用情况检查。否则，如果您要停用的任何服务在过去 30 天内使用过或在过去 3 天内启用过，系统都会返回错误。

• --bypass-dependency-check 可绕过依赖项检查。添加服务时，政策中必须包含所有服务依赖项。移除服务时，政策中的任何其他服务都不能依赖于该服务。 否则，更新不会成功，系统会返回错误。

• --validate-only 以验证更新，但不实际执行操作。

请注意以下几点：

• 如需获取政策文件的 YAML 模板，请先检索消费者政策，然后使用 --output-file 标志将政策保存到文件中。然后，修改此文件并将其用作更新命令的输入。模板示例：

  name: projects/PROJECT_ID/consumerPolicies/default
  enableRules:
    services:
      - services/SERVICE
      - ...
      - ...
  

  替换以下内容：

  • PROJECT_ID：您的Google Cloud 项目 ID。 其他受支持的资源名称采用类似格式，例如：folders/FOLDER_ID/consumerPolicies/default。

  • SERVICE：服务的名称，例如 bigquery.googleapis.com。

获取有效政策

您可以使用 gcloud beta services policies get-effective 命令检索资源的有效政策。

有效政策将资源的 ConsumerPolicy 与其所有祖先的政策相结合。这样一来，您就可以全面了解所有已启用的服务，包括直接在资源上启用的所有服务，以及从其祖先继承的服务。

项目

gcloud beta services policies get-effective --project=PROJECT_ID \
    --view=VIEW

替换以下内容：

• PROJECT_ID：您的Google Cloud 项目 ID。 或者，省略该标志以默认使用当前项目。
• VIEW：BASIC（用于检索有限的元数据）或 FULL（用于检索完整的元数据，包括每个服务在层次结构中启用的位置）。默认值为 BASIC。

文件夹

gcloud beta services policies get-effective --folder=FOLDER_ID \
    --view=VIEW

替换以下内容：

• FOLDER_ID：您的Google Cloud 文件夹 ID。
• VIEW：BASIC（用于检索有限的元数据）或 FULL（用于检索完整的元数据，包括每个服务在层次结构中启用的位置）。默认值为 BASIC。

组织

gcloud beta services policies get-effective --organization=ORGANIZATION_ID \
    --view=VIEW

替换以下内容：

• ORGANIZATION_ID：您的Google Cloud 组织资源 ID。
• VIEW：BASIC（用于检索有限的元数据）或 FULL（用于检索完整的元数据，包括层次结构中启用每个服务的位置）。默认值为 BASIC。

检查服务是否已启用

您可以使用 gcloud beta services policies test-enabled 命令检查资源上是否已启用某项服务。

在检查服务状态时，此命令会考虑有效政策和完整的 Google Cloud 资源层次结构。

项目

gcloud beta services policies test-enabled SERVICE \
    --project=PROJECT_ID

替换以下内容：

• SERVICE：您要检查的服务的名称。
• PROJECT_ID：您的Google Cloud 项目 ID。 或者，省略该标志以默认使用当前项目。

文件夹

gcloud beta services policies test-enabled SERVICE \
    --folder=FOLDER_ID

替换以下内容：

• SERVICE：您要检查的服务的名称。
• FOLDER_ID：您的Google Cloud 文件夹 ID。

组织

gcloud beta services policies test-enabled SERVICE \
    --organization=ORGANIZATION_ID

替换以下内容：

• SERVICE：您要检查的服务的名称。
• ORGANIZATION_ID：您的Google Cloud 组织资源 ID。

示例

检索消费者政策

• 检索当前项目的使用方政策：

  gcloud beta services policies get

  输出：

  name: projects/PROJECT_ID/consumerPolicies/default
  enableRules:
   services:
    - services/apikeys.googleapis.com
    - services/compute.googleapis.com
    - services/oslogin.googleapis.com
    - services/serviceusage.googleapis.com
  updateTime: 2025-09-11T23:05:22.758394Z
  createTime: 2025-01-31T20:17:37.272343Z
  etag: W/"W9nsVJK0V1m7ee7tM7pFDg=="

更新使用方政策

• 成功更新了使用方政策：

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

  输出：

  Operation [operations/ucpat.p39-581601899707-86fe7e37-c7f9-4624-90c4-d54754d57eed] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"1970-01-01T00:00:00Z",
      "enableRules":[
          {
              "services":[
                  "services/apikeys.googleapis.com"
              ]
          }
      ],
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"1970-01-01T00:00:00Z"
  }

• 未能成功更新使用方政策：

  gcloud beta services policies update --consumer-policy-file=/tmp/test.json

  错误消息：

  ERROR: (gcloud.beta.services.policies.update) Invalid consumer_policy_file format. Please provide path to a yaml file.

• 尝试在服务最近被使用或启用时更新使用方政策：

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml

  输出：

  The operation "operations/ucpat.p39-581601899707-4884bdb0-d899-49ac-9c83-38457950ef33" resulted in a failure "The services apikeys.googleapis.com have usage in the last 30 days or were enabled in the past 3 days. Please specify force if you want to proceed with the destructive policy change. Help Token: AVSZLmtCfGwMm4oHmOyExdDEFRQ0pFiBrl879nbZlY2JkfVzeU63u66ApXYr6MIEAoig..."

• 在服务最近被使用或启用时，通过绕过使用情况检查来更新使用方政策：

  gcloud beta services policies update --consumer-policy-file=/tmp/test.yaml --bypass-api-usage-check

  输出：

  Operation [operations/ucpat.p39-581601899707-8ffda670-ed04-4776-8d43-d2f8e1817e00] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"1970-01-01T00:00:00Z",
      "enableRules":[
          {
              "services":[
                  "services/serviceusage.googleapis.com"
              ]
          }
      ],
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"1970-01-01T00:00:00Z"
  }

检索有效政策

• 检索当前项目的有效政策的 BASIC 视图：

  gcloud beta services policies get-effective

  输出：

  EnabledRules:
   Services:
    -   services/apikeys.googleapis.com
    -   services/compute.googleapis.com
    -   services/computescanning.googleapis.com
    -   services/containeranalysis.googleapis.com
    -   services/containerscanning.googleapis.com
    -   services/gkebackup.googleapis.com
    -   services/osconfig.googleapis.com
    -   services/oslogin.googleapis.com
    -   services/serviceusage.googleapis.com

• 检索当前项目的有效政策的 FULL 视图：

  gcloud beta services policies get-effective --view=FULL

  输出：

  EnabledRules:
   Services:
    -   services/apikeys.googleapis.com
    -   services/compute.googleapis.com
    -   services/computescanning.googleapis.com
    -   services/containeranalysis.googleapis.com
    -   services/containerscanning.googleapis.com
    -   services/gkebackup.googleapis.com
    -   services/osconfig.googleapis.com
    -   services/oslogin.googleapis.com
    -   services/serviceusage.googleapis.com
  
  Metadata of effective policy:
  EnabledService: services/apikeys.googleapis.com
  EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
  
  EnabledService: services/bcidcloudenforcer-pa.googleapis.com
  EnabledPolicies: ['folders/FOLDER_ID/consumerPolicies/default']
  
  EnabledService: services/compute.googleapis.com
  EnabledPolicies: ['projects/PROJECT_ID/consumerPolicies/default']
  ...

检查服务是否已启用

• 检查当前项目已启用的 API 密钥服务的状态：

  gcloud beta services policies test-enabled apikeys.googleapis.com

  输出：

  Service apikeys.googleapis.com is ENABLED for resource projects/test-project Hierarchical Service Activation.

• 检查当前项目已停用的 App Hub 服务状态：

  gcloud beta services policies test-enabled apphub.googleapis.com

  输出：

  Service apphub.googleapis.com is NOT ENABLED for resource projects/test-project Hierarchical Service Activation.

后续步骤

• 如需启用和停用服务，请参阅管理服务启用状态。
• 如需检查服务依赖项，请参阅列出服务依赖项。