管理服务启用

预览版 — Hierarchical service activation

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

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

本文档介绍了如何使用 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 list --enabled 会返回当前项目的已启用服务列表。

   您可以检索当前项目 ID：

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

所需的角色

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

此预定义角色包含管理服务启用所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需管理服务启用状态，您需要具备以下权限：

• 列出服务：
  • serviceusage.effectivepolicy.get
  • serviceusage.services.list
  • serviceusage.services.get
• 启用服务：
  • serviceusage.consumerpolicy.get
  • serviceusage.consumerpolicy.update
  • serviceusage.groups.listExpandedMembers
• 停用服务：
  • serviceusage.consumerpolicy.get
  • serviceusage.consumerpolicy.update
  • serviceusage.consumerpolicy.analyze

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

列出服务

您可以使用 gcloud beta services list 命令列出已为项目、文件夹或组织启用或可用的 Google API 和服务。

服务启用状态和可用性可以从资源祖先继承。资源的已启用服务包括在资源本身上启用的服务，以及在所有资源祖先上启用的服务。

注意： 如果之前在“Service Usage”版本中隐藏了某些服务，那么在使用分层服务启用功能时，这些服务现在可能会显示在已启用服务的列表中。这并不一定意味着它们是新启用的。如果需要，您可以停用这些功能。

项目

gcloud beta services list --enabled \
    --project=PROJECT_ID

请将 PROJECT_ID 替换为您的Google Cloud 项目 ID。或者，省略该标志以默认使用当前项目。

文件夹

gcloud beta services list --enabled \
    --folder=FOLDER_ID

将 FOLDER_ID 替换为您的Google Cloud 文件夹 ID。

组织

gcloud beta services list --enabled \
    --organization=ORGANIZATION_ID

将 ORGANIZATION_ID 替换为您的Google Cloud 组织资源 ID。

请注意以下几点：

• 您必须指定以下标志之一：

  • --available 列出可启用以供使用的服务。
  • --enabled 列出已启用以供使用的服务。

• 您可以使用其他标志来过滤和限制列出的服务。

启用服务

您可以使用 gcloud beta services enable 命令为项目、文件夹或组织启用一项或多项服务。

此命令会更新目标资源中的 ConsumerPolicy。如需了解详情，请参阅管理消费者政策。

项目

gcloud beta services enable SERVICE \
    --project=PROJECT_ID

替换以下内容：

• SERVICE：您要启用的服务的名称。如需启用多项服务，请使用以空格分隔的服务名称，例如，以下命令可同时启用 API 密钥服务和 BigQuery 服务：gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com。
• PROJECT_ID：您的Google Cloud 项目 ID。 或者，省略该标志以默认使用当前项目。

文件夹

gcloud beta services enable SERVICE \
    --folder=FOLDER_ID

替换以下内容：

• SERVICE：您要启用的服务的名称。如需启用多项服务，请使用以空格分隔的服务名称，例如：gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com。
• FOLDER_ID：您的Google Cloud 文件夹 ID。

组织

gcloud beta services enable SERVICE \
    --organization=ORGANIZATION_ID

替换以下内容：

• SERVICE：您要启用的服务的名称。如需启用多项服务，请使用以空格分隔的服务名称，例如：gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com。
• ORGANIZATION_ID：您的Google Cloud 组织资源 ID。

支持的标志：

• --async 可立即返回结果，而无需等待正在进行的操作完成。

• --skip-dependency 可跳过启用任何服务依赖项。否则，默认情况下会启用所有服务依赖项。

  您可以检查服务依赖项。如需了解详情，请参阅列出服务依赖项。

• --validate-only 以验证启用情况，而无需实际执行操作。

请注意以下几点：

• 如果您尝试启用已启用的服务，系统会显示一条错误消息，指出该服务已启用并存在于消费者政策中。（如果服务已启用，但其依赖项未启用，该命令将成功执行。）

• 如果您在文件夹或组织级层启用某项服务，组织政策限制条件 constraints/serviceuser.services 可能无法按预期运行。 我们建议您改用“限制资源服务使用”限制条件。 如需了解详情，请参阅限制资源使用。

• Google Cloud 为许多Google Cloud 服务创建和管理服务账号。这些服务账号称为“服务代理”。如果您遇到 service account not found 错误，可能需要使用 gcloud beta services identity create 命令创建服务代理。

停用服务

您可以使用 gcloud beta services disable 命令为项目、文件夹或组织停用一项或多项服务。

此命令会更新目标资源中的 ConsumerPolicy。如需了解详情，请参阅管理消费者政策。

注意： 现有资源可能会阻止您停用某项服务。您可以删除这些资源，然后再次尝试停用该服务。或者，您也可以使用组织政策限制条件限制资源使用。

项目

gcloud beta services disable SERVICE \
    --project=PROJECT_ID

替换以下内容：

• SERVICE：您要停用的服务的名称。如需停用多项服务，请使用以空格分隔的服务名称，例如：gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com。
• PROJECT_ID：您的Google Cloud 项目 ID。 或者，省略该标志以默认使用当前项目。

文件夹

gcloud beta services disable SERVICE \
    --folder=FOLDER_ID

替换以下内容：

• SERVICE：您要停用的服务的名称。如需停用多项服务，请使用以空格分隔的服务名称，例如：gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com。
• FOLDER_ID：您的Google Cloud 文件夹 ID。

组织

gcloud beta services disable SERVICE \
    --organization=ORGANIZATION_ID

替换以下内容：

• SERVICE：您要停用的服务的名称。如需停用多项服务，请使用以空格分隔的服务名称，例如：gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com。
• ORGANIZATION_ID：您的Google Cloud 组织资源 ID。

支持的标志：

• --async - 立即返回，而无需等待正在进行的操作完成。

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

• 您可以指定以下标志之一：

  • --bypass-dependency-service-check 可绕过依赖项检查；任何依赖于您要停用的已启用服务都将保持启用状态。
  • --disable-dependency-services 以继续停用相应服务以及任何依赖于您要停用的服务的已启用服务。

  您可以检查服务依赖项。如需了解详情，请参阅列出服务依赖项。

• --force 以继续操作，即使存在依赖于该服务的已启用服务，或者该服务在过去 30 天内被使用过，或者在过去 3 天内被启用过。任何依赖服务也会被停用。

  --bypass-api-usage-check、--bypass-dependency-service-check 和 --disable-dependency-services 标志的优先级均高于 --force 标志。

  同时使用 --disable-dependency-services 和 --bypass-api-usage-check 标志等同于使用 --force 标志。系统会停用服务及其依赖项，而不检查其使用情况。

• --validate-only 以验证停用，而无需实际执行该操作。

示例

启用服务

• 启用 BigQuery 服务，但不启用其依赖项：

  gcloud beta services enable bigquery.googleapis.com --skip-dependency

  输出：

  Operation [operations/ucpat.p39-581601899707-73a57d57-aa46-4d0b-a5ee-57034a42f2b3] complete. Result: {
        "@type":"type.googleapis.com/google.api.serviceusage.with Hierarchical Service Activationbeta.ConsumerPolicy",
        "createTime":"2025-01-31T20:17:37.272343Z",
        "enableRules":[
            {
                "services":[
                    "services/apikeys.googleapis.com",
                    "services/compute.googleapis.com",
                    "services/oslogin.googleapis.com",
                    "services/serviceusage.googleapis.com",
                    "services/bigquery.googleapis.com"
                ]
            }
        ],
        "etag":"W/\"W9nsVJK0V1m7ee7tM7pFDg==\"",
        "name":"projects/PROJECT_ID/consumerPolicies/default",
        "updateTime":"2025-09-11T23:05:22.758394Z"
    }

• 启用 BigQuery 服务及其依赖项：

  gcloud beta services enable bigquery.googleapis.com

  输出：

  Operation [operations/ucpat.p39-581601899707-73192b0f-053c-46ee-911a-7eca6b8fe899] complete. Result: {
        "@type":"type.googleapis.com/google.api.serviceusage.with Hierarchical Service Activationbeta.ConsumerPolicy",
        "createTime":"2025-01-31T20:17:37.272343Z",
        "enableRules":[
            {
                "services":[
                    "services/apikeys.googleapis.com",
                    "services/compute.googleapis.com",
                    "services/oslogin.googleapis.com",
                    "services/serviceusage.googleapis.com",
                    "services/cloudresourcemanager.googleapis.com",
                    "services/dataplex.googleapis.com",
                    "services/bigquery.googleapis.com",
                    "services/bigquerystorage.googleapis.com",
                    "services/bigqueryconnection.googleapis.com",
                    "services/analyticshub.googleapis.com",
                    "services/bigquerymigration.googleapis.com",
                    "services/dataform.googleapis.com",
                    "services/bigquerydatapolicy.googleapis.com",
                    "services/bigquerydatatransfer.googleapis.com",
                    "services/bigqueryreservation.googleapis.com"
                ]
            }
        ],
        "etag":"W/\"FDXMAIdsBW7BrXjL7oP6FA==\"",
        "name":"projects/PROJECT_ID/consumerPolicies/default",
        "updateTime":"2025-09-12T19:44:23.675769Z"
    }

停用服务

• 尝试停用具有有效依赖项的 BigQuery 服务：

  gcloud beta services disable bigquery.googleapis.com

  错误消息：

  ERROR: (gcloud.beta.services.disable) The services are depended on by the following active service(s) {"bigquery.googleapis.com": ["services/bigquerystorage.googleapis.com"]} . Please remove the active dependent services or provide the --disable-dependency-services flag to disable them, or --bypass-dependency-service-check to ignore this check.

• 尝试停用最近使用过的 BigQuery 服务：

  gcloud beta services disable bigquery.googleapis.com --disable-dependency-services

  错误消息：

  ERROR: (gcloud.beta.services.disable) The operation "operations/ucpat.p39-581601899707-d35c2e2b-d2a3-47af-a1c0-033ed65df236" resulted in a failure "The services bigquery.googleapis.com,bigquerystorage.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.

• 停用 BigQuery 服务及其依赖项并绕过使用情况检查：

  gcloud beta services disable bigquery.googleapis.com --disable-dependency-services --bypass-api-usage-check

  输出：

  Operation [operations/ucpat.p39-581601899707-5c02aa04-7ad7-4eb6-a6a1-dc68653bcdb4] complete. Result: {
      "@type":"type.googleapis.com/google.api.serviceusage.v2beta.ConsumerPolicy",
      "createTime":"2025-01-31T20:17:37.272343Z",
      "enableRules":[
          {
              "services":[
                  "services/analyticshub.googleapis.com",
                  "services/apikeys.googleapis.com",
                  "services/bigqueryconnection.googleapis.com",
                  "services/bigquerydatapolicy.googleapis.com",
                  "services/bigquerydatatransfer.googleapis.com",
                  "services/bigquerymigration.googleapis.com",
                  "services/bigqueryreservation.googleapis.com",
                  "services/cloudresourcemanager.googleapis.com",
                  "services/compute.googleapis.com",
                  "services/dataform.googleapis.com",
                  "services/dataplex.googleapis.com",
                  "services/oslogin.googleapis.com",
                  "services/serviceusage.googleapis.com"
              ]
          }
      ],
      "etag":"W/\"TqbPaELDHlZQOj7As1P06g==\"",
      "name":"projects/PROJECT_ID/consumerPolicies/default",
      "updateTime":"2025-09-30T21:39:40.746125Z"
  }

后续步骤

• 如需管理政策，请参阅管理消费者政策。
• 如需检查服务依赖项，请参阅列出服务依赖项。