管理消費者政策

階層式服務啟用功能可讓您管理透過 Google Cloud 資源階層繼承的服務啟用狀態。詳情請參閱總覽。

ConsumerPolicy 是 Service Usage API 資源，位於Google Cloud 資源階層的每個層級。這個資源一律命名為 default，內含 enableRules，可定義要啟用哪些服務。您可以修改 ConsumerPolicy 資源，不必啟用或停用特定服務。如果服務名稱出現在清單中，表示該服務已在該層級啟用。

本文說明如何使用 Google Cloud CLI 管理專案、資料夾和機構的消費者政策。

事前準備

  1. 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.

  2. Install the Google Cloud CLI.

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 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.

    • 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.

  6. 如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

  7. Verify that billing is enabled for your Google Cloud project.

  8. 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

  9. Install the Google Cloud CLI.

  10. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  11. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  12. 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.

    • 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.

  13. 如要使用現有專案進行本指南中的操作，請確認您具有完成本指南所需的權限。如果您建立新專案，則已具備必要權限。

  14. Verify that billing is enabled for your Google Cloud project.

  15. 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

  16. 如果您未指出要管理的 Google Cloud 資源，本文中的指令會預設為目前的專案。舉例來說，gcloud beta services policies get --policy-name=default 會傳回目前專案的消費者政策。

    您可以擷取目前的專案 ID：

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

    17. 必要的角色

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

    這個預先定義的角色具備管理消費者政策所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

    所需權限

    如要管理消費者政策，必須具備下列權限：

    • 取得消費者政策： 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

    更改下列內容：

    機構

    gcloud beta services policies test-enabled SERVICE \
    --organization=ORGANIZATION_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.

    後續步驟