Esta página explica como listar e editar contas de serviço através da API
Identity and Access Management (IAM), da Google Cloud consola e da ferramenta de linha de comandos gcloud
.
Antes de começar
Enable the IAM API.
Configurar autenticação.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
C#
Para usar os .NET exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
C++
Para usar os C++ exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
Ir
Para usar os Go exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
Java
Para usar os Java exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
Python
Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.
REST
Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.
Instale a CLI Google Cloud.
Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.
Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.
Compreenda as contas de serviço do IAM
Funções necessárias
Para receber as autorizações de que precisa para gerir contas de serviço, peça ao seu administrador que lhe conceda as seguintes funções do IAM no projeto:
-
Para ver contas de serviço:
Ver contas de serviço (
roles/iam.serviceAccountViewer
) -
Para editar contas de serviço:
Administrador da conta de serviço (
roles/iam.serviceAccountAdmin
)
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.
Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.
Para saber mais sobre estas funções, consulte o artigo Funções das contas de serviço.
As funções básicas do IAM também contêm autorizações para gerir contas de serviço. Não deve conceder funções básicas num ambiente de produção, mas pode concedê-las num ambiente de desenvolvimento ou teste.
Indicar contas de serviço
Pode listar as contas de serviço geridas pelo utilizador num projeto para ajudar a auditar contas de serviço e chaves, ou como parte de uma ferramenta personalizada para gerir contas de serviço.
Não pode listar os agentes de serviço que podem aparecer na política de autorização e nos registos de auditoria do seu projeto. Os agentes de serviço não estão localizados no seu projeto e não pode aceder diretamente a eles.
Consola
Na Google Cloud consola, aceda à página Contas de serviço.
Selecione um projeto.
A página Contas de serviço apresenta todas as contas de serviço geridas pelo utilizador no projeto que selecionou.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Execute o comando
gcloud iam service-accounts list
para listar todas as contas de serviço num projeto.Comando:
gcloud iam service-accounts list
O resultado é a lista de todas as contas de serviço geridas pelo utilizador no projeto:
NAME EMAIL SA_DISPLAY_NAME_1 SA_NAME_1@PROJECT_ID.iam.gserviceaccount.com SA_DISPLAY_NAME_2 SA_NAME_2@PROJECT_ID.iam.gserviceaccount.com
PROJECT_ID
: O ID do seu Google Cloud projeto. Os IDs dos projetos são strings alfanuméricas, comomy-project
.
C++
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C++ IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
C#
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C# IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Go
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Java
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Java IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Python
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Python IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
REST
O método
serviceAccounts.list
apresenta todas as contas de serviço geridas pelo utilizador no seu projeto.Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
Método HTTP e URL:
GET https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts
Para enviar o seu pedido, expanda uma destas opções:
Deve receber uma resposta JSON semelhante à seguinte:
{ "accounts": [ { "name": "projects/my-project/serviceAccounts/sa-1@my-project.iam.gserviceaccount.com", "projectId": "my-project", "uniqueId": "123456789012345678901", "email": "sa-1@my-project.iam.gserviceaccount.com", "description": "My first service account", "displayName": "Service account 1", "etag": "BwUpTsLVUkQ=", "oauth2ClientId": "987654321098765432109" }, { "name": "projects/my-project/serviceAccounts/sa-2@my-project.iam.gserviceaccount.com", "projectId": "my-project", "uniqueId": "234567890123456789012", "email": "sa-2@my-project.iam.gserviceaccount.com", "description": "My second service account", "displayName": "Service account 2", "etag": "UkQpTwBVUsL=", "oauth2ClientId": "876543210987654321098" } ] }
Edite uma conta de serviço
O nome a apresentar (nome amigável) e a descrição de uma conta de serviço são usados normalmente para captar informações adicionais sobre a conta de serviço, como a finalidade da conta de serviço ou uma pessoa de contacto para a conta.
Consola
Na Google Cloud consola, aceda à página Contas de serviço.
Selecione um projeto.
Clique no endereço de email da conta de serviço que quer mudar de nome.
Introduza o novo nome na caixa Nome e, de seguida, clique em Guardar.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Execute o comando
gcloud iam service-accounts update
para atualizar uma conta de serviço.Comando:
gcloud iam service-accounts update
SA_NAME@PROJECT_ID.iam.gserviceaccount.com
--description="UPDATED_SA_DESCRIPTION"
--display-name="UPDATED_DISPLAY_NAME"O resultado é a conta de serviço com o novo nome:
description: UPDATED_SA_DESCRIPTION displayName: UPDATED_DISPLAY_NAME name: projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com
PROJECT_ID
: O ID do seu Google Cloud projeto. Os IDs dos projetos são strings alfanuméricas, comomy-project
.SA_ID
: o ID da sua conta de serviço. Este pode ser o endereço de email da conta de serviço no formatoSA_NAME@PROJECT_ID.iam.gserviceaccount.com
ou o ID numérico exclusivo da conta de serviço.SA_NAME
: o ID alfanumérico da sua conta de serviço. Este nome tem de ter entre 6 e 30 carateres e pode conter carateres alfanuméricos em minúsculas e travessões.- Substitua, pelo menos, um dos seguintes elementos:
UPDATED_DISPLAY_NAME
: um novo nome a apresentar para a sua conta de serviço.UPDATED_DESCRIPTION
: uma nova descrição para a sua conta de serviço.
C++
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C++ IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
C#
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C# IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Go
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Java
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Java IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
Python
Para saber como instalar e usar a biblioteca cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Python IAM.
Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.
REST
O método
serviceAccounts.patch
atualiza uma conta de serviço.Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:
Método HTTP e URL:
PATCH https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID
Corpo JSON do pedido:
{ "serviceAccount": { "email": "SA_NAME@PROJECT_ID.iam.gserviceaccount.com", "displayName": "UPDATED_DISPLAY_NAME", "description": "UPDATED_DESCRIPTION" }, "updateMask": "displayName,description" }
Para enviar o seu pedido, expanda uma destas opções:
Deve receber uma resposta JSON semelhante à seguinte:
{ "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com", "displayName": "My updated service account", "description": "An updated description of my service account" }
O que se segue?
- Saiba como desativar e ativar contas de serviço.
- Reveja o processo de concessão de funções do IAM a todos os tipos de responsáveis, incluindo contas de serviço.
- Explore como pode usar recomendações de funções para restringir as autorizações de todos os responsáveis, incluindo as contas de serviço.
- Compreenda como anexar contas de serviço a recursos.
Experimente
Se for um novo utilizador do Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Os novos clientes também recebem 300 USD em créditos gratuitos para executar, testar e implementar cargas de trabalho.
Comece gratuitamenteExceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-20 UTC.