Criar e conceder papéis a agentes de serviço

No Google Cloud, os agentes de serviço nos níveis de projeto, pasta e organização são criados automaticamente à medida que você ativa e usa os serviços do Google Cloud. Às vezes, esses agentes de serviço também recebem automaticamente papéis que permitem criar e acessar recursos em seu nome.

Se necessário, também é possível pedir ao Google Cloud para criar agentes de serviço para envolvidos no projeto, no nível da pasta e da organização antes de usar o serviço. Pedir ao Google Cloud para criar agentes de serviço permite que você conceda papéis a eles antes de usar um serviço. Se um agente de serviço ainda não tiver sido criado, não será possível conceder papéis a ele.

Essa opção é útil se você usa uma das seguintes estratégias para gerenciar as políticas de permissão:

Um framework declarativo, como o Terraform. Se a configuração do Terraform não incluir os papéis dos agentes de serviço, eles serão revogados quando você aplicar a configuração. Ao criar agentes de serviço e conceder papéis a eles na configuração do Terraform, você garante que esses papéis não sejam revogados.
Um sistema de políticas como código que armazena cópias das políticas de permissão atuais em um repositório de código. Se você permitir que o Google Cloud conceda papéis automaticamente aos agentes de serviço, eles aparecerão na política de permissões real, mas não na cópia armazenada da política de permissão. Para resolver essa inconsistência, revogue esses papéis incorretamente. Ao criar agentes de serviço e conceder a eles papéis de maneira proativa, é possível evitar desvios entre o repositório de código e as políticas de permissão reais.

Depois de acionar a criação do agente de serviço, conceda a ele os papéis que normalmente são concedidos automaticamente. Se você não fizer isso, alguns serviços poderão não funcionar corretamente. Isso ocorre porque os agentes de serviço criados na solicitação de um usuário não recebem papéis automaticamente.

Antes de começar

Enable the Resource Manager API.
Enable the API
Entenda os agentes de serviço.

Funções exigidas

A ativação da criação do agente de serviço não requer permissões do IAM. No entanto, você precisa de permissões de IAM específicas para outras tarefas nesta página:

Para receber a permissão necessária para listar os serviços disponíveis e seus endpoints, peça ao administrador para conceder a você o papel do IAM Leitor do Service Usage (roles/serviceusage.serviceUsageViewer) no projeto, na pasta ou na organização em que você quer listar os serviços disponíveis. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém a permissão serviceusage.services.list, que é necessária para listar os serviços disponíveis e os endpoints.
Também é possível conseguir essa permissão com papéis personalizados ou outros papéis predefinidos.
Para receber as permissões necessárias para conceder acesso aos agentes de serviço, peça ao administrador os seguintes papéis do IAM no projeto, na pasta ou na organização a que você está concedendo acesso:
- conceder aos agentes de serviço acesso a um projeto: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin)
- conceder aos agentes de serviço acesso a uma pasta: Administrador de pastas (roles/resourcemanager.folderAdmin)
- conceder aos agentes de serviço acesso a projetos, pastas e organizações: Administrador da organização (roles/resourcemanager.organizationAdmin)
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esses papéis predefinidos contêm as permissões necessárias para conceder aos agentes de serviço acesso. Para conferir 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 conceder acesso aos agentes de serviço:
- Conceda aos agentes de serviço acesso a um projeto:
  - resourcemanager.projects.getIamPolicy
  - resourcemanager.projects.setIamPolicy
- Conceda aos agentes de serviço acesso a uma pasta:
  - resourcemanager.folders.getIamPolicy
  - resourcemanager.folders.setIamPolicy
- Conceda aos agentes de serviço acesso a uma organização:
  - resourcemanager.organizations.getIamPolicy
  - resourcemanager.organizations.setIamPolicy
Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Identificar os agentes de serviço a serem criados

Para identificar os agentes de serviço nos níveis de projeto, pasta e organização que você precisa pedir ao Google Cloud para criar, faça o seguinte:

Faça uma lista dos serviços que você usa e dos endpoints de API correspondentes. Para ver todos os serviços disponíveis e os endpoints, use um dos seguintes métodos:
Console

Acesse a página Biblioteca de APIs no console do Google Cloud.

Acessar a biblioteca de APIs

O endpoint da API é o Nome do serviço listado na seção Detalhes adicionais.
gcloud

O comando gcloud services list lista todos os serviços disponíveis para um projeto.

Antes de usar os dados do comando abaixo, faça estas substituições:
- EXPRESSION: opcional. Uma expressão para filtrar os resultados. Por exemplo, a expressão a seguir filtra todos os serviços com nomes que contenham googleapis.com, mas não sandbox:
```
name ~ googleapis.com AND name !~ sandbox
```
  Para uma lista de expressões de filtro, consulte gcloud topic filters.
- LIMIT: opcional. O número máximo de resultados a serem listados. O padrão é unlimited.
Execute o este comando:
Linux, macOS ou Cloud Shell
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
Windows (PowerShell)
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
Windows (cmd.exe)

Observação: se esse comando usar ' para citar conteúdo, substitua essas aspas simples por aspas duplas. Se as aspas estiverem aninhadas, use \" para escapar das aspas internas.
```
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
```
A resposta contém os nomes e os títulos de todos os serviços disponíveis. O endpoint da API é o valor no campo NAME.
REST

O método services.list da API Service Usage lista todos os serviços disponíveis para um projeto.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- RESOURCE_TYPE: o tipo de recurso para listar os serviços disponíveis. Use projects, folders ou organizations.
- RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para listar os serviços disponíveis. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
- PAGE_SIZE: opcional. O número de serviços a serem incluídos na resposta. O valor padrão é 50, e o valor máximo é 200. Se o número de serviços for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.
- NEXT_PAGE_TOKEN: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de serviços começará onde a solicitação anterior foi finalizada.
Método HTTP e URL:
```
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
```
Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
A resposta contém os nomes e títulos de todos os serviços disponíveis para o recurso. Se o número de serviços disponíveis for maior que o tamanho da página, a resposta também conterá um token de paginação.

O endpoint da API é o valor no campo name.
Na página de referência do agente de serviço, pesquise cada endpoint da API.

Se o endpoint estiver listado na tabela, encontre todos os agentes de serviço dele. Ignore todos os agentes de serviço com um endereço de e-mail que contenha o marcador IDENTIFIER. Esses agentes de serviço são destinados a recursos específicos do serviço, e não a projetos, pastas ou organizações.

Para cada agente de serviço no nível do projeto, da pasta e da organização, registre o seguinte:
- O formato do endereço de e-mail do agente de serviço.
- O papel concedido ao agente de serviço, se houver.

Acionar a criação do agente de serviço

Depois de saber quais agentes de serviço você precisa criar, peça ao Google Cloud para criá-los.

Ao solicitar que o Google Cloud crie agentes de serviço, você fornece a ele um serviço e um recurso. Em seguida, o Google Cloud cria todos os agentes de serviço para esse serviço e esse recurso.

gcloud

Para cada serviço em que você precisa criar agentes, faça o seguinte:

Revise os endereços de e-mail do agente de serviço. Use os marcadores nos endereços de e-mail para determinar para quais recursos você precisa criar agentes de serviço:

Marcador	Onde criar agentes de serviço
`PROJECT_NUMBER`	Cada projeto em que você usará o serviço
`FOLDER_NUMBER`	Cada pasta em que você usará o serviço
`ORGANIZATION_NUMBER`	Cada organização em que você usará o serviço

Crie agentes de serviço para cada recurso.

O comando gcloud beta services identity create cria todos os agentes de serviço para a API e o recurso especificados.

Antes de usar os dados do comando abaixo, faça estas substituições:
- ENDPOINT: o endpoint da API em que você quer criar um agente de serviço, por exemplo, aiplatform.googleapis.com.
- RESOURCE_TYPE: o tipo de recurso em que você quer criar um agente de serviço. Use project, folder ou organization.
- RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para o qual você quer criar um agente de serviço. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
  
  É possível criar agentes de serviço para um recurso por vez. Se você precisar criar agentes de serviço para vários recursos, execute o comando uma vez para cada recurso.
Execute o este comando:
Linux, macOS ou Cloud Shell
```
gcloud beta services identity create --service=ENDPOINT \
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (PowerShell)
```
gcloud beta services identity create --service=ENDPOINT `
    --RESOURCE_TYPE=RESOURCE_ID
```
Windows (cmd.exe)
```
gcloud beta services identity create --service=ENDPOINT ^
    --RESOURCE_TYPE=RESOURCE_ID
```
A resposta contém o endereço de e-mail do agente de serviço principal do serviço. Esse endereço de e-mail inclui o código numérico do projeto, da pasta ou da organização para a qual você criou agentes de serviço.

Se o serviço não tiver um agente de serviço principal, a resposta não conterá um endereço de e-mail.

Veja a seguir um exemplo de resposta para um serviço que tem um agente de serviço principal.
```
Service identity created: service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com
```
Opcional: registre o endereço de e-mail do agente de serviço na resposta, se houver. Esse endereço de e-mail identifica o agente de serviço principal do serviço. É possível usar esse identificador para conceder papéis ao agente de serviço principal.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Para cada serviço em que você precisa criar agentes, faça o seguinte:

Revise os endereços de e-mail do agente de serviço. Use os marcadores nos endereços de e-mail para determinar para quais recursos você precisa criar agentes de serviço:

Marcador	Onde criar agentes de serviço
`PROJECT_NUMBER`	Cada projeto em que você usará o serviço
`FOLDER_NUMBER`	Cada pasta em que você usará o serviço
`ORGANIZATION_NUMBER`	Cada organização em que você usará o serviço

Crie agentes de serviço para cada recurso. Por exemplo, o código a seguir cria todos os agentes de serviço para envolvidos no projeto para o AI Platform:

Observação: o Terraform só é compatível com o acionamento da criação de agentes de serviço para envolvidos no projeto. Para acionar a criação de agentes de serviços no nível da pasta e da organização, use a Google Cloud CLI ou a API REST.

data "google_project" "default" {
}

# Create all project-level aiplatform.googleapis.com service agents
resource "google_project_service_identity" "default" {
  provider = google-beta

  project = data.google_project.default.project_id
  service = "aiplatform.googleapis.com"
}

REST

Para cada serviço em que você precisa criar agentes, faça o seguinte:

Revise os endereços de e-mail do agente de serviço. Use os marcadores nos endereços de e-mail para determinar para quais recursos você precisa criar agentes de serviço:

Marcador	Onde criar agentes de serviço
`PROJECT_NUMBER`	Cada projeto em que você usará o serviço
`FOLDER_NUMBER`	Cada pasta em que você usará o serviço
`ORGANIZATION_NUMBER`	Cada organização em que você usará o serviço

Crie agentes de serviço para cada recurso.

O método services.generateServiceIdentity da API Service Usage cria todos os agentes de serviço para a API e o recurso especificados.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- RESOURCE_TYPE: o tipo de recurso em que você quer criar um agente de serviço. Use projects, folders ou organizations.
- RESOURCE_ID: o ID do projeto, da pasta ou da organização do Google Cloud para o qual você quer criar agentes de serviço. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
  
  É possível criar agentes de serviço para um recurso por vez. Se você precisar criar agentes de serviço para vários recursos, envie uma solicitação para cada recurso.
- ENDPOINT: o endpoint da API em que você quer criar um agente de serviço, por exemplo, aiplatform.googleapis.com.
Método HTTP e URL:
```
POST https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity
```
Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity"
```
PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://serviceusage.googleapis.com/v1beta1/RESOURCE_TYPE/RESOURCE_ID/services/ENDPOINT:generateServiceIdentity" | Select-Object -Expand Content
```
A resposta contém um Operation que indica o status da solicitação. Para acompanhar o status da operação, use o método operations.get:

As operações concluídas contêm o endereço de e-mail do agente de serviço principal do serviço. Esse endereço de e-mail inclui o código numérico do projeto, da pasta ou da organização para a qual você criou agentes de serviço.

Se o serviço não tiver um agente de serviço principal, a resposta não conterá um endereço de e-mail.

Veja a seguir um exemplo de operação concluída de um serviço que tem um agente de serviço principal.
```
{
  "name": "operations/finished.DONE_OPERATION",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.serviceusage.v1beta1.ServiceIdentity",
    "email": "service-232332569935@gcp-sa-aiplatform.iam.gserviceaccount.com",
    "uniqueId": "112245693826560101651"
  }
}
```
Opcional: registre o endereço de e-mail do agente de serviço na resposta, se houver. Esse endereço de e-mail identifica o agente de serviço principal do serviço. É possível usar esse identificador para conceder papéis ao agente de serviço principal.

Conceder papéis a agentes de serviço

Depois que o Google Cloud criar os agentes de serviço necessários para projetos, pastas e organizações, use os endereços de e-mail deles para conceder papéis.

Se você pediu ao Google Cloud para criar agentes de serviço, conceda a eles os papéis que normalmente são concedidos automaticamente. Se você não fizer isso, alguns serviços poderão não funcionar corretamente. Isso ocorre porque os agentes de serviço criados na solicitação de um usuário não recebem papéis automaticamente.

Para saber como identificar papéis concedidos automaticamente, consulte Identificar agentes de serviço a serem criados.

Encontrar o endereço de e-mail do agente de serviço

Para encontrar o endereço de e-mail de um agente de serviço, faça o seguinte:

gcloud

Encontre o formato de endereço de e-mail do agente de serviço, caso ainda não tenha feito isso. Esse formato está documentado na referência do agente de serviço.
Substitua os marcadores no endereço de e-mail pelo projeto, pasta ou número da organização correspondente.

Como alternativa, se o agente de serviço for um agente de serviço principal, é possível conseguir o endereço de e-mail dele acionando a criação do agente de serviço para o serviço. O comando para acionar a criação do agente de serviço retorna o endereço de e-mail do agente de serviço principal.

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

Encontre o formato de endereço de e-mail do agente de serviço, caso ainda não tenha feito isso. Esse formato está documentado na referência do agente de serviço.
Substitua os marcadores no endereço de e-mail por expressões que façam referência ao projeto, pasta ou número da organização apropriado.

Por exemplo, considere a seguinte situação:
- O formato do endereço de e-mail é service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
- O agente de serviço é de um projeto rotulado como default
Nesse caso, o endereço de e-mail do agente de serviço é o seguinte:
```
service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com
```

Como alternativa, se um agente de serviço for o principal para um serviço, você poderá conseguir o endereço de e-mail dele no atributo email do recurso google_project_service_identity.

Por exemplo, se você tiver um bloco google_project_service_identity rotulado como default, poderá conseguir o endereço de e-mail do agente de serviço principal do serviço usando a seguinte expressão:

${google_project_service_identity.default.email}

REST

Encontre o formato de endereço de e-mail do agente de serviço, caso ainda não tenha feito isso. Esse formato está documentado na referência do agente de serviço.
Substitua os marcadores no endereço de e-mail pelo projeto, pasta ou número da organização correspondente.

Conceder um papel ao agente de serviço

Depois de encontrar o endereço de e-mail do agente de serviço, é possível conceder um papel a ele da mesma forma que faria com qualquer outro principal.

Console

No console do Google Cloud, abra a página IAM.

Acesse IAM
Selecione um projeto, pasta ou organização.
Clique em Conceder acesso e insira o endereço de e-mail do agente de serviço.
Na lista suspensa, selecione um papel a ser concedido.
Opcional: adicione uma condição ao papel.
Clique em Save. O agente de serviço recebe o papel no recurso.

gcloud

O comando add-iam-policy-binding permite que você conceda rapidamente um papel a um principal.

Antes de usar os dados do comando abaixo, faça estas substituições:

RESOURCE_TYPE: o tipo de recurso ao qual você quer gerenciar o acesso. Use projects, resource-manager folders ou organizations.
RESOURCE_ID: o projeto, a pasta ou o ID da organização do Google Cloud. Os IDs de projeto são alfanuméricos, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
PRINCIPAL: um identificador do principal ou membro, que geralmente tem o seguinte formato: PRINCIPAL_TYPE:ID. Por exemplo, user:my-user@example.com. Para conferir uma lista completa dos valores que PRINCIPAL pode ter, consulte a referência de vinculação de políticas.

Para o tipo de principal user, o nome de domínio no identificador precisa ser do Google Workspace ou do Cloud Identity. Para saber como configurar um domínio do Cloud Identity, consulte a Visão geral do Cloud Identity.
ROLE_NAME: o nome do papel que você quer revogar. Use um dos seguintes formatos:
- Papéis predefinidos: roles/SERVICE.IDENTIFIER
- Papéis personalizados para envolvidos no projeto: projects/PROJECT_ID/roles/IDENTIFIER
- Papéis personalizados no nível da organização: organizations/ORG_ID/roles/IDENTIFIER
Para uma lista de papéis predefinidos, consulte Noções básicas sobre papéis.
CONDITION: a condição a ser adicionada à vinculação de papel. Se você não quiser adicionar uma condição, use o valor None. Para mais informações sobre as condições, consulte a visão geral das condições.

Execute o este comando:

Linux, macOS ou Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

A resposta contém a política da IAM atualizada:

Terraform

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform. Para mais informações, consulte a documentação de referência do provedor Terraform.

# Grant the AI Platform Custom Code Service Account the Vertex AI Custom
# Code Service Agent role (roles/aiplatform.customCodeServiceAgent)
resource "google_project_iam_member" "custom_code" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.customCodeServiceAgent"
  member  = "serviceAccount:service-${data.google_project.default.number}@gcp-sa-aiplatform-cc.iam.gserviceaccount.com"
}

# Grant the primary aiplatform.googleapis.com service agent (AI Platform
# Service Agent) the Vertex AI Service Agent role
# (roles/aiplatform.serviceAgent)
resource "google_project_iam_member" "primary" {
  project = data.google_project.default.project_id
  role    = "roles/aiplatform.serviceAgent"
  member  = "serviceAccount:${google_project_service_identity.default.email}"
}

REST

Para conceder um papel com a API REST, use o padrão read-modify-write:

Leia a política de permissão atual chamando getIamPolicy().

O método getIamPolicy da API Resource Manager recebe a política de permissão de um projeto, pasta ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- API_VERSION: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
- RESOURCE_TYPE: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
- RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
- POLICY_VERSION: a versão da política a ser retornada. As solicitações precisam especificar a versão mais recente da política, que é a versão 3 da política. Para saber mais detalhes, consulte Como especificar uma versão da política ao receber uma política.
Método HTTP e URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
Corpo JSON da solicitação:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a política de permissão do projeto. Exemplo:
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:owner@example.com"
      ]
    }
  ]
}
```
Edite a política de permissões do recurso, usando um editor de texto ou programaticamente, para adicionar ou remover principais ou vinculações de papéis. Por exemplo, é possível adicionar uma nova vinculação de papel, remover uma vinculação de papel ou adicionar/remover participantes de uma vinculação de papel.
Escreva a política de permissão atualizada chamando setIamPolicy().

O método setIamPolicy da API Resource Manager define a política na solicitação como a nova política de permissão para o projeto, a pasta ou a organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- API_VERSION: a versão da API a ser usada. Para projetos e organizações, use v1. Para pastas, use v2.
- RESOURCE_TYPE: o tipo de recurso com a política que você quer gerenciar. Use o valor projects, folders ou organizations.
- RESOURCE_ID: seu projeto do Google Cloud, a organização ou o ID da pasta. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos de pastas e organizações são numéricos, como 123456789012.
- POLICY: uma representação JSON da política que você quer definir. Para mais informações sobre o formato de uma política, consulte a referência da política.
Método HTTP e URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
Corpo JSON da solicitação:
```
{
  "policy": POLICY
}
```
Para enviar a solicitação, expanda uma destas opções:
curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a política de permissão atualizada.

Observação: se você tratar as políticas do IAM como código e armazená-las em um sistema de controle de versões, armazene a política retornada, não a política que você enviou na solicitação.

A seguir

Veja uma lista de todos os agentes de serviço.
Conheça outras maneiras de atribuir papéis a principais.
Saiba como criar contas de serviço gerenciadas pelo usuário, que podem agir como identidades para suas cargas de trabalho.
Saiba mais sobre as práticas recomendadas para usar o Terraform no Google Cloud.
Conheça todos os exemplos do Google Cloud Terraform.

Criar e conceder papéis a agentes de serviço

Antes de começar

Funções exigidas

Permissões necessárias

Identificar os agentes de serviço a serem criados

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Acionar a criação do agente de serviço

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Conceder papéis a agentes de serviço

Encontrar o endereço de e-mail do agente de serviço

gcloud

Terraform

REST

Conceder um papel ao agente de serviço

Console

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

APIs Explorer (navegador)

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

APIs Explorer (navegador)

A seguir