管理服務啟用狀態

預先發布版 — 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)'

必要的角色

如要取得管理服務啟用狀態所需的權限，請要求管理員授予您目標資源的服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備管理服務啟用狀態所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要管理服務啟用狀態，必須具備下列權限：

• 列出服務：
  • 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 和服務。

服務啟用和可用性可從資源祖先繼承。資源的已啟用服務包括資源本身啟用的服務，以及所有資源上層啟用的服務。

注意： 如果使用階層式服務啟用功能，先前在服務用量版本中隱藏的服務，現在可能會顯示在已啟用服務的清單中。這不一定表示這些功能是新啟用。如需停用這些功能，請參閱這篇文章。

專案

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 可能無法正常運作。建議改用「Restrict Resource Service Usage」限制。詳情請參閱「限制資源用量」。

• 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"
    }

停用服務

• Attempting to disable BigQuery service with active dependencies:

  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"
  }

後續步驟

• 如要管理政策，請參閱「管理消費者政策」。
• 如要檢查服務依附元件，請參閱「列出服務依附元件」。