Faça a gestão das políticas do consumidor

Pré-visualização — Hierarchical service activation

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

A ativação hierárquica de serviços permite-lhe gerir a ativação de serviços que é herdada através da Google Cloud hierarquia de recursos. Para mais informações, consulte a vista geral.

O ConsumerPolicy é um recurso da API Service Usage encontrado em cada nível da hierarquia de recursosGoogle Cloud . Este recurso, sempre denominado default, contém os enableRules que definem os serviços ativados. Em vez de ativar ou desativar um serviço específico, pode modificar o recurso.ConsumerPolicy Quando um nome de serviço está na respetiva lista, o serviço é ativado nesse nível da hierarquia.

Este documento mostra como usar a CLI do Google Cloud para gerir políticas de consumidor para projetos, pastas e organizações.

Antes de começar

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.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

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.

Se estiver a usar um projeto existente para este guia, verifique se tem as autorizações necessárias para concluir este guia. Se criou um novo projeto, já tem as autorizações necessárias.

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.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

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.

Se estiver a usar um projeto existente para este guia, verifique se tem as autorizações necessárias para concluir este guia. Se criou um novo projeto, já tem as autorizações necessárias.

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. Se não indicar o Google Cloud recurso que quer gerir, os comandos neste documento são predefinidos para o projeto atual. Por exemplo, gcloud beta services policies get --policy-name=default devolve a política do consumidor para o projeto atual.

   Pode obter o ID do projeto atual:

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

Funções necessárias

Para receber as autorizações de que precisa para gerir políticas do consumidor, peça ao seu administrador que lhe conceda a função de IAM de administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin) no seu recurso de destino. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para gerir políticas de consumidor. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para gerir políticas do consumidor:

• Obtenha uma política do consumidor: serviceusage.consumerpolicy.get
• Atualize uma política do consumidor:
  • serviceusage.consumerpolicy.analyze
  • serviceusage.consumerpolicy.update
• Obtenha uma política em vigor: serviceusage.effectivepolicy.get
• Verifique se um serviço está ativado: serviceusage.values.test

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Obtenha uma política do consumidor

Pode obter o ConsumerPolicy de um projeto, uma pasta ou uma organização através do comando gcloud beta services policies get.

Este comando devolve o enableRules definido exatamente nesse nível de recurso e não as regras herdadas. Para uma vista mais completa que inclua regras herdadas, pode obter a política eficaz. Apenas o nome da política default é suportado.

Projeto

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

Substitua o seguinte:

• PROJECT_ID: o seu Google Cloud ID do projeto. Em alternativa, omita a flag para usar o projeto atual como predefinição.
• OUTPUT_FILE: (opcional) o caminho para um ficheiro de saída onde o conteúdo da política do consumidor pode ser guardado. Os formatos de ficheiros suportados são JSON e YAML.

Pasta

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

Substitua o seguinte:

• FOLDER_ID: o seu Google Cloud ID da pasta.
• OUTPUT_FILE: (opcional) o caminho para um ficheiro de saída onde o conteúdo da política do consumidor pode ser guardado. Os formatos de ficheiros suportados são JSON e YAML.

Organização

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

Substitua o seguinte:

• ORGANIZATION_ID: o Google Cloud ID do recurso da sua organização.
• OUTPUT_FILE: (opcional) o caminho para um ficheiro de saída onde o conteúdo da política do consumidor pode ser guardado. Os formatos de ficheiros suportados são JSON e YAML.

Atualize uma política do consumidor

Pode atualizar um ConsumerPolicy através do comando gcloud beta services policies update. Isto permite-lhe substituir a política atual e usar um ficheiro YAML para atualizar muitos serviços ativados de uma só vez.

Este comando não ativa automaticamente as dependências de serviços. Tem de listar explicitamente todas as dependências de serviços no ficheiro de entrada. Pode usar a flag --validate-only para pré-visualizar as alterações antes de as aplicar.

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

Substitua PATH_TO_CONSUMER_POLICY pelo caminho para o ficheiro YAML que contém a política do consumidor, por exemplo:

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

Bandeiras suportadas:

• --bypass-api-usage-check para ignorar as verificações de utilização. Caso contrário, o sistema devolve um erro se algum serviço que pretenda desativar tiver sido usado nos últimos 30 dias ou ativado nos últimos 3 dias.

• --bypass-dependency-check para ignorar a verificação de dependências. Quando adiciona um serviço, todas as dependências de serviços têm de estar presentes na política. Quando remove um serviço, nenhum outro serviço na política pode depender dele. Caso contrário, a atualização não é bem-sucedida e é devolvido um erro.

• --validate-only para validar a atualização sem realizar efetivamente a operação.

Tenha em conta o seguinte:

• Para obter um modelo YAML do ficheiro de política, primeiro obtenha a política do consumidor e use a flag --output-file para guardar a política num ficheiro. Em seguida, modifique este ficheiro e use-o como entrada para o comando de atualização. Modelo de exemplo:

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

  Substitua o seguinte:

  • PROJECT_ID: o seu Google Cloud ID do projeto. Outros nomes de recursos suportados seguem um formato semelhante, por exemplo: folders/FOLDER_ID/consumerPolicies/default.

  • SERVICE: o nome do serviço, por exemplo: bigquery.googleapis.com.

Obtenha uma política eficaz

Pode obter a política efetiva de um recurso através do comando gcloud beta services policies get-effective.

A política eficaz combina o ConsumerPolicy do recurso com as políticas de todos os respetivos antecessores. Isto dá-lhe uma vista completa de todos os serviços ativados, incluindo todos os serviços ativados diretamente no recurso e os herdados dos respetivos antecessores.

Projeto

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

Substitua o seguinte:

• PROJECT_ID: o seu Google Cloud ID do projeto. Em alternativa, omita a flag para usar o projeto atual como predefinição.
• VIEW: BASIC para obter um conjunto limitado de metadados ou FULL para obter o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. A predefinição é BASIC.

Pasta

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

Substitua o seguinte:

• FOLDER_ID: o seu Google Cloud ID da pasta.
• VIEW: BASIC para obter um conjunto limitado de metadados ou FULL para obter o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. A predefinição é BASIC.

Organização

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

Substitua o seguinte:

• ORGANIZATION_ID: o Google Cloud ID do recurso da sua organização.
• VIEW: BASIC para obter um conjunto limitado de metadados ou FULL para obter o conjunto completo de metadados, incluindo onde cada serviço foi ativado na hierarquia. A predefinição é BASIC.

Verifique se um serviço está ativado

Pode verificar se um serviço está ativado num recurso através do comando gcloud beta services policies test-enabled.

Ao verificar o estado de um serviço, este comando considera a política eficaz e a hierarquia de recursos completa. Google Cloud

Projeto

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

Substitua o seguinte:

• SERVICE: o nome do serviço que quer verificar.
• PROJECT_ID: o seu Google Cloud ID do projeto. Em alternativa, omita a flag para usar o projeto atual como predefinição.

Pasta

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

Substitua o seguinte:

• SERVICE: o nome do serviço que quer verificar.
• FOLDER_ID: o seu Google Cloud ID da pasta.

Organização

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

Substitua o seguinte:

• SERVICE: o nome do serviço que quer verificar.
• ORGANIZATION_ID: o Google Cloud ID do recurso da sua organização.

Exemplos

Obter política do consumidor

• A obter política de consumidor para o projeto atual:

  gcloud beta services policies get

  Saída:

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

A atualizar a política do consumidor

• A política do consumidor foi atualizada com êxito:

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

  Saída:

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

• Atualização da política do consumidor sem êxito:

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

  Mensagem de erro:

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

• Tentativa de atualização da política do consumidor quando o serviço foi usado ou ativado recentemente:

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

  Saída:

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

• Atualizar a política do consumidor quando o serviço foi usado ou ativado recentemente ignorando a verificação de utilização:

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

  Saída:

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

Obter política em vigor

• A obter a vista BASIC da política em vigor para o projeto atual:

  gcloud beta services policies get-effective

  Saída:

  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

• A obter a vista FULL da política em vigor para o projeto atual:

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

  Saída:

  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']
  ...

Verificar se um serviço está ativado

• Verificar o estado do serviço de chaves da API ativadas para o projeto atual:

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

  Saída:

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

• Verificar o estado do serviço App Hub desativado para o projeto atual:

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

  Saída:

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

O que se segue?

• Para ativar e desativar serviços, consulte o artigo Faça a gestão da ativação de serviços.
• Para inspecionar as dependências de serviços, consulte o artigo Liste as dependências de serviços.