Gerenciar a ativação de serviços

Pré-lançamento — Hierarchical service activation

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Com a ativação hierárquica de serviços, é possível gerenciar a ativação de serviços que são herdados pela hierarquia de recursos Google Cloud . Para mais informações, consulte a visão geral.

Este documento mostra como usar a Google Cloud CLI para gerenciar a ativação de serviços em 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.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, 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 este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissõ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.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, 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 este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissõ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 você não indicar o recurso Google Cloud que quer gerenciar, os comandos neste documento vão usar o projeto atual por padrão. Por exemplo, gcloud beta services list --enabled retorna uma lista de serviços ativados para o projeto atual.

   Você pode recuperar o ID do projeto atual:

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

Funções exigidas

Para receber as permissões necessárias para gerenciar a ativação de serviços, peça ao administrador para conceder a você o papel do IAM de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin) no recurso de destino. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para gerenciar a ativação de serviços. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para gerenciar a ativação de serviços:

• Listar serviços:
  • serviceusage.effectivepolicy.get
  • serviceusage.services.list
  • serviceusage.services.get
• Ative os serviços:
  • serviceusage.consumerpolicy.get
  • serviceusage.consumerpolicy.update
  • serviceusage.groups.listExpandedMembers
• Desative os serviços:
  • serviceusage.consumerpolicy.get
  • serviceusage.consumerpolicy.update
  • serviceusage.consumerpolicy.analyze

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Listar serviços

É possível listar as APIs e os serviços do Google ativados ou disponíveis para um projeto, uma pasta ou uma organização usando o comando gcloud beta services list.

A ativação e a disponibilidade do serviço podem ser herdadas dos ancestrais do recurso. Os serviços ativados de um recurso incluem os serviços ativados no próprio recurso e em todos os ancestrais dele.

Observação: os serviços ocultos na versão anterior do Service Usage agora podem aparecer na lista de serviços ativados ao usar a ativação hierárquica de serviços. Isso não significa necessariamente que eles foram ativados recentemente. Se necessário, é possível desativá-los.

Projeto

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

Substitua PROJECT_ID pelo Google Cloud ID do projeto. Ou omita a flag para usar o projeto atual como padrão.

Pasta

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

Substitua FOLDER_ID pelo ID da pastaGoogle Cloud .

Organização

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

Substitua ORGANIZATION_ID pelo ID do recurso da organizaçãoGoogle Cloud .

Observe o seguinte:

• É necessário especificar uma das seguintes flags:

  • --available para listar os serviços que podem ser ativados para consumo.
  • --enabled para listar os serviços que estão ativados para consumo.

• É possível usar outras flags para filtrar e limitar os serviços listados.

Ativar serviços

É possível ativar um ou mais serviços para um projeto, uma pasta ou uma organização usando o comando gcloud beta services enable.

Esse comando atualiza o ConsumerPolicy no recurso de destino. Para mais informações, consulte Gerenciar políticas de consumo.

Projeto

gcloud beta services enable SERVICE \
    --project=PROJECT_ID

Substitua:

• SERVICE: o nome do serviço que você quer ativar. Para ativar vários serviços, use nomes de serviços delimitados por espaços. Por exemplo, o comando a seguir ativa os serviços de chaves de API e do BigQuery: gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com.
• PROJECT_ID: o ID do projetoGoogle Cloud . Ou omita a flag para usar o projeto atual como padrão.

Pasta

gcloud beta services enable SERVICE \
    --folder=FOLDER_ID

Substitua:

• SERVICE: o nome do serviço que você quer ativar. Para ativar vários serviços, use nomes de serviços separados por espaços. Por exemplo: gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com.
• FOLDER_ID: o ID da pastaGoogle Cloud .

Organização

gcloud beta services enable SERVICE \
    --organization=ORGANIZATION_ID

Substitua:

• SERVICE: o nome do serviço que você quer ativar. Para ativar vários serviços, use nomes de serviços separados por espaços. Por exemplo: gcloud beta services enable apikeys.googleapis.com bigquery.googleapis.com.
• ORGANIZATION_ID: o ID do recurso da organizaçãoGoogle Cloud .

Flags compatíveis:

• --async para retornar imediatamente, sem aguardar a conclusão da operação em andamento.

• --skip-dependency para pular a ativação de dependências de serviço. Caso contrário, todas as dependências de serviço serão ativadas por padrão.

  Você pode inspecionar as dependências do serviço. Para mais informações, consulte Listar dependências de serviço.

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

Observe o seguinte:

• Se você tentar ativar um serviço que já está ativado, vai receber um erro informando que o serviço já está ativado e presente na política do consumidor. Se o serviço já estiver ativado, mas as dependências não, o comando será executado.

• Se você ativar um serviço no nível da pasta ou da organização, a restrição de política da organização constraints/serviceuser.services poderá não funcionar como esperado. Recomendamos que você use a restrição "Restringir o uso do serviço de recurso". Para mais informações, consulte Restringir o uso de recursos.

• OGoogle Cloud cria e gerencia contas de serviço para muitos serviços do Google Cloud . Essas contas de serviço são conhecidas como agentes de serviço. Se você encontrar um erro service account not found, talvez seja necessário criar um agente de serviço usando o comando gcloud beta services identity create.

Desativar serviços

É possível desativar um ou mais serviços para um projeto, uma pasta ou uma organização usando o comando gcloud beta services disable.

Esse comando atualiza o ConsumerPolicy no recurso de destino. Para mais informações, consulte Gerenciar políticas de consumo.

Observação: recursos atuais podem impedir que você desative um serviço. Você pode excluir esses recursos e tentar desativar o serviço novamente. Como alternativa, você pode restringir o uso de recursos usando uma restrição de política da organização.

Projeto

gcloud beta services disable SERVICE \
    --project=PROJECT_ID

Substitua:

• SERVICE: o nome do serviço que você quer desativar. Para desativar vários serviços, use nomes de serviços delimitados por espaços, por exemplo, gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com.
• PROJECT_ID: o ID do projetoGoogle Cloud . Ou omita a flag para usar o projeto atual como padrão.

Pasta

gcloud beta services disable SERVICE \
    --folder=FOLDER_ID

Substitua:

• SERVICE: o nome do serviço que você quer desativar. Para desativar vários serviços, use nomes de serviços delimitados por espaços, por exemplo, gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com.
• FOLDER_ID: o ID da pastaGoogle Cloud .

Organização

gcloud beta services disable SERVICE \
    --organization=ORGANIZATION_ID

Substitua:

• SERVICE: o nome do serviço que você quer desativar. Para desativar vários serviços, use nomes de serviços delimitados por espaços, por exemplo, gcloud beta services disable apikeys.googleapis.com bigquery.googleapis.com.
• ORGANIZATION_ID: o ID do recurso da organizaçãoGoogle Cloud .

Flags aceitas:

• --async para retornar imediatamente, sem aguardar a conclusão da operação em andamento.

• --bypass-api-usage-check para ignorar as verificações de uso. Caso contrário, o sistema retornará um erro se o serviço que você quer desativar foi usado nos últimos 30 dias ou ativado nos últimos 3 dias.

• É possível especificar uma das seguintes flags:

  • --bypass-dependency-service-check para ignorar a verificação de dependências. Todos os serviços ativados que dependem do serviço que você está desativando permanecem ativados.
  • --disable-dependency-services para continuar desativando o serviço e todos os serviços ativados que dependem dele.

  Você pode inspecionar as dependências do serviço. Para mais informações, consulte Listar dependências de serviço.

• --force para continuar mesmo que haja serviços ativados que dependam do serviço, ou que ele tenha sido usado nos últimos 30 dias ou ativado nos últimos 3 dias. Todos os serviços dependentes também são desativados.

  As flags --bypass-api-usage-check, --bypass-dependency-service-check e --disable-dependency-services têm precedência sobre a flag --force.

  Usar as flags --disable-dependency-services e --bypass-api-usage-check é equivalente a usar a flag --force. O serviço e as dependências dele são desativados sem verificar o uso.

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

Exemplos

Como ativar um serviço

• Ativar o serviço do BigQuery sem as dependências:

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

  Saída:

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

• Ativar o serviço do BigQuery com as dependências dele:

  gcloud beta services enable bigquery.googleapis.com

  Saída:

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

Desativar um serviço

• Tentativa de desativar o serviço do BigQuery com dependências ativas:

  gcloud beta services disable bigquery.googleapis.com

  Mensagem de erro:

  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.

• Tentativa de desativar o serviço do BigQuery com uso recente:

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

  Mensagem de erro:

  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.

• Desativar o serviço do BigQuery e as dependências dele e ignorar a verificação de uso:

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

  Saída:

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

A seguir

• Para gerenciar políticas, consulte Gerenciar políticas do consumidor.
• Para inspecionar as dependências do serviço, consulte Listar dependências do serviço.