Como criar e gerenciar papéis personalizados

Nesta página, descrevemos como criar e gerenciar um papel personalizado.

Antes de começar

• Leia Como entender papéis personalizados do IAM e confira informações sobre as permissões obrigatórias para criar papéis personalizados e práticas recomendadas.
• Se você quiser usar o utilitário de linha de comando gcloud, a versão precisará ser 188.0.0 ou posterior. Para atualizar o gcloud para essa versão, execute o seguinte comando: gcloud components update --version 188.0.0.

Como ver as permissões disponíveis para um recurso

Antes de criar um papel personalizado, é recomendável saber quais permissões podem ser aplicadas a um recurso. Para receber todas as permissões que podem ser aplicadas a um recurso e aos que estão abaixo dele na hierarquia, use a ferramenta de linha de comando gcloud, o console do Cloud ou a API IAM. Por exemplo, é possível receber todas as permissões que podem ser aplicadas a uma organização e aos respectivos projetos.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Na parte superior da página, selecione o projeto na lista suspensa.
3. Marque a caixa de seleção do papel de administrador do recurso. Assim, será possível ver todas as permissões aplicáveis a esse recurso. Por exemplo, quando você seleciona o papel Administrador de instâncias do Compute, o painel à direita exibe todas as permissões aplicáveis a uma instância do Compute Engine.

COMANDO GCLOUD

Use o comando gcloud iam list-testable-permissions para ver uma lista de permissões que podem ser aplicadas em um recurso de destino. As permissões retornadas são aquelas que podem ser usadas para a criação de um papel personalizado nesse recurso e em qualquer outro abaixo dele na hierarquia.

No exemplo a seguir, demonstramos como listar permissões testáveis para um recurso de projeto:

gcloud iam list-testable-permissions [PROJECT-ID]

[PROJECT-ID] é o código do projeto na forma de um nome de recurso completo: //cloudresourcemanager.googleapis.com/projects/PROJECT-ID, como //cloudresourcemanager.googleapis.com/projects/my-project-id.

Centenas de resultados podem ser retornados pelo comando list-testable-permissions. Para limitar os resultados, especifique uma expressão de filtro. Abaixo está um exemplo truncado de possíveis resultados:

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---

Observe que a compatibilidade com um papel personalizado está indicada em cada permissão. Para uma lista completa de permissões compatíveis e não compatíveis, acesse Suporte a permissões de papéis personalizados.

REST API

Com QueryTestablePermissions, todas as permissões aplicáveis a um recurso são retornadas. Com elas, você cria um papel personalizado nesse recurso e em qualquer outro subordinado a ele na hierarquia. A única entrada obrigatória para essa solicitação é o nome completo do recurso, por exemplo, //cloudresourcemanager.googleapis.com/projects/my-project.

Se preferir, pode haver compatibilidade com a paginação no autor da chamada caso a lista de permissões do recurso seja longa.

Exemplo

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'`

Códigos de erro

Código de erro	Mensagem de status
INVALID_ARGUMENT	O valor precisa ser entre 0 e 100
INVALID_ARGUMENT	Codificação de token de paginação inválida
INVALID_ARGUMENT	Token de paginação inválido
INVALID_ARGUMENT	Token de paginação incorreto para o contêiner especificado
INVALID_ARGUMENT	Ponto de partida inválido no token de paginação
INVALID_ARGUMENT	Cookie do token de paginação inválido
INVALID_ARGUMENT	Token de paginação expirado
INVALID_ARGUMENT	{full_resource_name} precisa ser especificado
INVALID_ARGUMENT	{full_resource_name} não atende aos critérios: //[a-z0-9.-]/.a-z0-9.-]/

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Permission> QueryTestablePermissions(
        string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	request := &iam.QueryTestablePermissionsRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Permissions.QueryTestablePermissions(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Permissions.QueryTestablePermissions: %v", err)
	}
	for _, p := range response.Permissions {
		fmt.Fprintf(w, "Found permissions: %v", p.Name)
	}
	return response.Permissions, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

Como consultar os metadados do papel

Antes de criar um papel personalizado, consulte os metadados dos papéis predefinidos e personalizados. Esses metadados incluem o código e as permissões do papel. Visualize os metadados usando o Console do Google Cloud Platform ou a IAM API.

Para visualizar os metadados do papel, use um dos métodos abaixo:

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Na parte superior da página, selecione a organização ou o projeto na lista suspensa.
3. Marque a caixa de seleção de um ou mais papéis para visualizar as permissões. O painel do lado direito exibirá as permissões deles, se houver.

Os ícones ao lado do papel indicam se ele é personalizado (ícone de "fábrica") ou predefinido (ícone de hexágono).

Para procurar todos os papéis com uma permissão específica, na parte superior da lista "Papéis", digite o nome da permissão na caixa Filtro.

COMANDO GCLOUD

Use o comando gcloud iam roles describe para visualizar metadados de papéis predefinidos e personalizados.

Para ver os metadados de um papel predefinido, execute o comando gcloud a seguir:

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] é o nome do papel, como roles/viewer.

No exemplo a seguir, demonstramos a saída do comando describe quando executado no papel predefinido roles/iam.roleViewer:

gcloud iam roles describe roles/iam.roleViewer

description: Read access to all custom roles in the project.
etag: AA==
includedPermissions:
- iam.roles.get
- iam.roles.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
name: roles/iam.roleViewer
stage: GA
title: Role Viewer

Para visualizar os metadados de um papel personalizado, determine primeiro se ele foi criado no nível do projeto ou da organização. Em caso afirmativo, execute este comando gcloud:

gcloud iam roles describe --organization [ORGANIZATION-ID] [ROLE-NAME]

[ORGANIZATION-ID] é o código da organização no formato 1234567. [ROLE-NAME] é o nome do papel personalizado, como myCustomRole.

Para visualizar os metadados de um papel personalizado criado no nível do projeto, execute este comando gcloud:

gcloud iam roles describe --project [PROJECT-ID] [ROLE-NAME]

[PROJECT-ID] é o código do projeto, como my-project-id. [ROLE-NAME] é o nome do papel personalizado, como myCustomRole.

Para mais informações, acesse a documentação de referência para descrição de papéis no gcloud iam.

REST API

Se você sabe o nome do papel que quer ver, use o método roles.get para consultar um papel personalizado. Caso contrário, use o método roles.list para listar todos os papéis personalizados de uma organização ou um projeto.

Para chamar o GetRole(), defina o seguinte campo no GetRoleRequest:

• Nome do papel, por exemplo, roles/{ROLE-NAME} ou organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}.

Para chamar o ListRoles(), defina o seguinte campo no ListRolesRequest:

• Recurso pai dos papéis personalizados que você quer receber, por exemplo, organizations/{ORGANIZATION-ID} ou projects/{PROJECT-ID}.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para chamar o papel em {path}
NOT_FOUND	O papel {role} não foi encontrado.
INVALID_ARGUMENT	O nome do papel precisa estar no formato roles/{role} ou organizations/{organization-id}/roles/{role}.
PERMISSION_DENIED	Você não tem permissão para listar papéis em {path}.
INVALID_ARGUMENT	Pai {path} inválido. O pai precisa estar no formato organizations/{organization-id} ou vazio.
INVALID_ARGUMENT	Visualização de papel inválida.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role GetRole(string name)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %v", err)
	}
	fmt.Fprintf(w, "Got role: %v\n", role.Name)
	for _, permission := range role.IncludedPermissions {
		fmt.Fprintf(w, "Got permission: %v\n", permission)
	}
	return role, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def get_role(name):
    """Gets a role."""

    # pylint: disable=no-member
    role = service.roles().get(name=name).execute()
    print(role['name'])
    for permission in role['includedPermissions']:
        print(permission)

Como criar um papel personalizado

Para criar um papel personalizado, o autor da chamada precisa ter a permissão iam.roles.create. Por padrão, o proprietário do projeto ou da organização tem essa permissão e pode criar e gerenciar papéis personalizados.

Usuários não proprietários, incluindo administradores da organização, precisam receber o papel de administrador de papéis da organização ou de papéis de IAM.

Console

Para criar um papel personalizado do zero, siga estas etapas:

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione sua organização na lista suspensa Organização.
3. Clique em Criar papel.
4. Insira um Nome, um Título e uma Descrição para o papel.
5. Clique em Adicionar permissões.
6. Selecione as permissões que você quer incluir no papel e clique em Adicionar permissões. Use as listas suspensas Todos os serviços e Todos os tipos para filtrar e selecionar permissões por serviço e tipo.

Para criar um papel personalizado com base em um papel atual, siga estas etapas:

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione sua organização na lista suspensa Organização.
3. Selecione os papéis em que você quer basear o novo papel personalizado.
4. Clique em Criar papel a partir da seleção.
5. Insira um Nome, um Título e uma Descrição para o papel.
6. Desmarque as permissões que quer excluir do papel.
7. Clique em Adicionar permissões para incluir permissões.
8. Clique em Criar.

COMANDO GCLOUD

Use o comando gcloud iam roles create para criar papéis personalizados. Ele pode ser usado de duas maneiras:

• Com o fornecimento de um arquivo YAML que tenha a definição do papel.
• Com o uso de sinalizações para especificar a definição do papel.

Durante a criação de um papel personalizado, é preciso usar as sinalizações --organization [ORGANIZATION-ID] e --project [PROJECT-ID] para indicar se ele se aplica à organização ou ao projeto. Nos exemplos abaixo, são criados papéis personalizados para o projeto.

Para criar um papel personalizado usando um arquivo YAML:

Crie um arquivo YAML que tenha a definição do papel personalizado. E preciso que o arquivo seja estruturado da seguinte maneira:

title: [ROLE-TITLE]
description: [ROLE-DESCRIPTION]
stage: [LAUNCH-STAGE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-TITLE] é um título simples para o papel, como "Role Viewer".
• [ROLE-DESCRIPTION] é uma breve descrição do papel, como "My custom role description".
• [LAUNCH-STAGE] indica o estágio de um papel no ciclo de vida do lançamento, como ALPHA, BETA ou GA.
• Em includedPermissions, está especificada a lista de uma ou mais permissões a serem incluídas no papel personalizado, como - iam.roles.get.

Salve o arquivo YAML e execute o comando gcloud abaixo:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id.
• [YAML_FILE-PATH] é o caminho para o local do arquivo YAML em que está a definição do papel personalizado.

No exemplo de arquivo YAML a seguir, demonstramos como criar uma definição de papel:

title: "Role Viewer"
description: "My custom role description."
stage: "ALPHA"
includedPermissions:
- iam.roles.get
- iam.roles.list

No exemplo a seguir, demonstramos como criar um papel usando o arquivo YAML:

gcloud iam roles create viewer --project my-project-id \
--file my-role-definition.yaml

Se o papel for criado com sucesso, a resposta a seguir será retornada:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Para criar um papel personalizado usando sinalizações:

Execute o seguinte comando gcloud:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--permissions [PERMISSIONS-LIST] --stage [LAUNCH-STAGE]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id.
• [ROLE-TITLE] é um título simples para o papel, como "Role Viewer".
• [ROLE-DESCRIPTION] é uma breve descrição do papel, como "My custom role description.".
• [PERMISSIONS-LIST] contém uma lista de permissões separadas por vírgula que você quer incluir no papel personalizado. Por exemplo, iam.roles.get,iam.roles.list.
• [LAUNCH-STAGE] indica o estágio de um papel no ciclo de vida do lançamento, como ALPHA, BETA ou GA.

No seguinte exemplo, demonstramos como criar um papel usando sinalizações:

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

Se o papel for criado com sucesso, a resposta a seguir será retornada:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

Use o método create para criar um papel personalizado.

Configure os seguintes parâmetros obrigatórios na solicitação:

• O role_id do novo papel personalizado, por exemplo, appengine.myCustomStorageAuditor.
• A descrição do papel personalizado, por exemplo, "Com este papel, você lista os recursos de armazenamento, a capacidade deles e as políticas de acesso".
• Uma lista das permissões que você quer associar ao papel.
• Observe que a configuração do campo do name no papel resultará em um erro.

Configure também os seguintes parâmetros opcionais:

• título do papel personalizado, por exemplo, "Editor de papéis personalizados".
• um valor para stage, por exemplo, GA

Em stage, os seguintes valores são aceitos: ALPHA, BETA, GA, DEPRECATED e DISABLED.

Alguns papéis predefinidos têm permissões com uso suspenso ou não permitidas em papéis personalizados. Uma falha ocorre quando você tenta criar um papel personalizado com base em um predefinido com essas características.

Exemplo

parent: '[PARENT-NAME]'
role_id: '[ROLE-ID]'
role {
    name: ''
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

Em que:

• [PARENT-NAME] é o nome da organização, por exemplo, organizations/0000000000000001, ou o código do projeto, por exemplo, projects/my-project, em que você quer criar o papel personalizado;
• [ROLE-ID] é o código do papel personalizado. Por exemplo, appengine.myCustomStorageAuditor.
• [ROLE-TITLE] é o título do papel. Por exemplo, Storage Auditor.
• [ROLE-DESCRIPTION] é a descrição desse papel;
• [PERMISSION] é a permissão que você quer incluir no papel personalizado.

Observação: ao chamar create, não configure o campo "nome" do papel na solicitação. Assim que for criado, esse nome será definido como organizations/{ORGANIZATION-ID}/roles/{ROLE-ID} ou projects/{PROJECT-ID}/roles/{ROLE-ID}.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para criar um papel em {parent}.
ALREADY_EXISTS	Já existe um papel chamado {role-id} em {parent}.
INVALID_ARGUMENT	Pai {parent} inválido. O pai precisa estar no formato organizations/{organization-id}.
INVALID_ARGUMENT	role_id {role-id} inválido. Ele não corresponde ao padrão {pattern}.
INVALID_ARGUMENT	O número de permissões no papel é maior que o máximo {max}.
INVALID_ARGUMENT	Cenário de papel {stage} inválido.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role CreateRole(string name, string projectId, string title,
        string description, IList<string> permissions, string stage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = new Role
        {
            Title = title,
            Description = description,
            IncludedPermissions = permissions,
            Stage = stage
        };
        var request = new CreateRoleRequest
        {
            Role = role,
            RoleId = name
        };
        role = service.Projects.Roles.Create(request,
            "projects/" + projectId).Execute();
        Console.WriteLine("Created role: " + role.Name);
        return role;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// createRole creates a custom role.
func createRole(w io.Writer, projectID, name, title, description, stage string, permissions []string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	request := &iam.CreateRoleRequest{
		Role: &iam.Role{
			Title:               title,
			Description:         description,
			IncludedPermissions: permissions,
			Stage:               stage,
		},
		RoleId: name,
	}
	role, err := service.Projects.Roles.Create("projects/"+projectID, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Create: %v", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

Como editar um papel personalizado

Leitura-modificação-gravação

Um padrão comum na atualização dos metadados de um recurso, por exemplo, um papel personalizado, é ler o estado atual, atualizar os dados localmente e enviá-los para gravação. Com esse padrão, um conflito pode ocorrer se dois ou mais processos independentes tentarem executar a sequência simultaneamente. Por exemplo, quando dois proprietários de um projeto fazem alterações conflitantes em um papel ao mesmo tempo, pode haver uma falha. Esse problema é solucionado no Cloud IAM com a propriedade etag dos papéis personalizados. Com essa propriedade, você verifica se o papel personalizado foi alterado desde a última solicitação. Quando a solicitação é enviada ao Cloud IAM com um valor de etag, ele é comparado com o valor de etag associado ao papel. A alteração é gravada somente se esses valores forem correspondentes.

Para atualizar um papel, leia-o com roles.get(), atualize-o e grave-o com roles.patch(). Ao configurar o papel, use o valor de etag somente quando o papel correspondente em roles.get() também contiver um valor de etag.

Observação: quando você modifica um papel personalizado adicionando ou removendo qualquer uma das permissões a seguir: resourcemanager.organizations.get, resourcemanager.folders.get e resourcemanager.projects.get, é necessário aguardar até 24 horas para que a alteração do papel personalizado entre em vigor nas APIs organizations.search e folders.search do Cloud Resource Manager. A API projects.list também está sujeita a esse atraso em chamadas de API que não fornecem um filtro com detalhes de tipo pai e ID. Esse atraso ocorre porque essas permissões envolvem funcionalidade de pesquisa e pode levar até 24 horas entre as recompilações do índice de pesquisa.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione sua organização na lista suspensa Organização.
3. Clique em um papel personalizado.
4. Clique em Editar papel.
5. Clique em Adicionar permissões para adicionar novas permissões ao papel.
6. Desmarque as permissões para removê-las do papel.
7. Clique em Atualizar para salvar o papel editado.

COMANDO GCLOUD

Use o comando gcloud iam roles update para atualizar papéis personalizados. Ele pode ser usado de duas maneiras:

• Por meio de um arquivo YAML contendo a definição atualizada do papel.
• Com sinalizações para especificar a definição atualizada do papel.

Durante a atualização de um papel personalizado, é preciso usar as sinalizações --organization [ORGANIZATION-ID] e --project [PROJECT-ID] para indicar se ele se aplica à organização ou ao projeto. Nos exemplos abaixo, são criados papéis personalizados para o projeto.

Para atualizar um papel personalizado usando um arquivo YAML:

Execute o seguinte comando gcloud para buscar a definição atual do papel:

gcloud iam roles describe [ROLE-ID] --project [PROJECT-ID]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel a ser atualizado, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id.

Usando o comando describe, a definição do papel é retornada e um valor de etag que identifique a versão atual do papel é incluído. O valor de etag será fornecido na definição atualizada do papel para impedir a substituição de alterações de papel simultâneas.

Usando-se o comando describe, a seguinte saída é retornada:

description: [ROLE-DESCRIPTION]
etag: [ETAG-VALUE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]
name: [ROLE-ID]
stage: [LAUNCH-STAGE]
title: [ROLE-TITLE]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-DESCRIPTION] é uma breve descrição do papel, como "My custom role description".
• [ETAG-VALUE] é o identificador exclusivo da versão atual do papel, como BwVkBkbfr70=.
• Em includedPermissions, está especificada a lista de uma ou mais permissões a serem incluídas no papel personalizado, como - iam.roles.get.
• [ROLE-ID] é o código hierárquico do papel e depende do nível em que ele foi criado. Por exemplo: projects/my-project-id/roles/viewer.
• [LAUNCH-STAGE] indica o estágio de um papel no ciclo de vida do lançamento, como ALPHA, BETA ou GA.
• [ROLE-TITLE] é um título simples para o papel, como "Role Viewer".

Para atualizar o papel, inclua a definição gerada em um arquivo YAML ou atualize o arquivo YAML original com o valor de etag emitido.

Pense no seguinte arquivo YAML de exemplo, que tem a saída do comando describe e adiciona duas permissões do Cloud Storage:

description: My custom role description.
etag: BwVkBkbfr70=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Salve o arquivo YAML e execute o comando gcloud abaixo:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel a ser atualizado, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id.
• [YAML_FILE-PATH] é o caminho para o local do arquivo YAML em que está a definição atualizada do papel personalizado.

No seguinte exemplo, demonstramos como atualizar um papel usando o arquivo YAML:

gcloud iam roles update viewer --project my-project-id \
--file my-role-definition.yaml

Se o papel for atualizado com sucesso, a resposta abaixo será retornada:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Para atualizar um papel personalizado usando sinalizações:

Cada parte de uma definição de papel pode ser atualizada usando uma sinalização. Consulte o tópico atualização de funções do gcloud iam para ver uma lista de todas sinalizações possíveis.

Use as seguintes sinalizações para adicionar ou remover permissões:

• --add-permissions [PERMISSIONS]: adiciona uma ou mais permissões separadas por vírgulas ao papel.
• --remove-permissions [PERMISSIONS]: remove uma ou mais permissões separadas por vírgula do papel.

Como alternativa, basta especificar as novas permissões usando a sinalização --permissions [PERMISSIONS] e fazer uma lista de permissões separadas por vírgulas para substituir a lista atual.

Para atualizar outros aspectos da definição do papel, execute o seguinte comando gcloud:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--stage [LAUNCH-STAGE]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id.
• [ROLE-TITLE] é um título simples para o papel, como "Role Viewer".
• [ROLE-DESCRIPTION] é uma breve descrição do papel, como "My custom role description.".
• [LAUNCH-STAGE] indica o estágio de um papel no ciclo de vida do lançamento, como ALPHA, BETA ou GA.

No exemplo a seguir, demonstramos como adicionar permissões a um papel usando sinalizações:

gcloud iam roles update viewer --project my-project-id \
--add-permissions storage.buckets.get,storage.buckets.list

Se o papel for atualizado com sucesso, a resposta abaixo será retornada:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

Use o método Role UpdateRole(UpdateRoleRequest) para editar um papel personalizado.

Caso saiba o código do papel personalizado que você quer editar, leia o papel usando o método roles.get() e atualize-o com roles.patch().

Caso contrário, liste todos os papéis com ListRoles() para identificá-lo. O roles.list() retorna uma lista dos papéis que fazem referência ao recurso. Em seguida, atualize-o com roles.patch().

Configure o parâmetro obrigatório a seguir no roles.patch():

• nome do papel, por exemplo, organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}.

Opcionalmente, configure o update_mask para especificar os campos que podem ser atualizados no futuro.

Exemplo

name: '[ROLE-NAME]'
role {
    name: '[ROLE-NAME]'
    title: '[ROLE-TITLE]'`
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})"

Em que:

• [ROLE-NAME] é o nome do papel. Por exemplo, organizations/123456/roles/appengine.customRoleEditor. Formatos possíveis: roles/{ROLE-NAME}, organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME} ou projects/{PROJECT-ID}/roles/{ROLE-NAME}

  Observação: é recomendável deixar o [ROLE_NAME] do papel vazio. Um erro é retornado no método quando os dois nomes não são idênticos e o nome no papel não está vazio.

• [ROLE-TITLE] é o título do papel. Por exemplo, New custom editor.

• [ROLE-DESCRIPTION] é uma descrição do papel. Por exemplo, "Minha nova descrição longa do editor".

• [PERMISSION] é a permissão que você quer incluir no papel. Por exemplo, storage.objects.update.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para atualizar o papel.
INVALID_ARGUMENT	Não é possível atualizar papéis predefinidos.
INVALID_ARGUMENT	O nome na solicitação ([ROLE-NAME]) precisa ser igual ao nome do papel ([ROLE-NAME]).
INVALID_ARGUMENT	Permissão [PERMISSION] inválida.
ABORTED	Houve alterações simultâneas na política porque os valores de etag não coincidem. Tente refazer a sequência de leitura-modificação-gravação com retirada exponencial.

Alguns papéis predefinidos têm permissões com uso suspenso ou não permitidas em papéis personalizados. Uma falha ocorre quando você tenta criar um papel personalizado com base em um predefinido com essas características.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// editRole modifies a custom role.
func editRole(w io.Writer, projectID, name, newTitle, newDescription, newStage string, newPermissions []string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %v", err)
	}
	role.Title = newTitle
	role.Description = newDescription
	role.IncludedPermissions = newPermissions
	role.Stage = newStage
	role, err = service.Projects.Roles.Patch(resource, role).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Patch: %v", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

Como desativar um papel personalizado

É possível desativar um papel personalizado. Quando isso é feito, as vinculações de política relacionadas a ele ficam inativas, o que significa que as permissões desse papel não são válidas, mesmo quando ele é concedido a um usuário.

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Clique na lista suspensa "Selecionar um projeto" na parte superior da página.
3. Selecione a organização ou o projeto.
4. Selecione um papel personalizado e clique em Desativar.

COMANDO GCLOUD

Use o comando gcloud iam roles update para desativar um papel personalizado. Para isso, defina o estágio de lançamento dele como DISABLED. Conforme descrito na guia gcloud da seção Como editar um papel personalizado atual, é possível atualizar um papel personalizado das seguintes maneiras:

• Por meio de um arquivo YAML contendo a definição atualizada do papel.
• Com sinalizações para especificar a definição atualizada do papel.

A maneira mais fácil de desativar um papel personalizado existente é usar a sinalização --stage e defini-lo como DISABLED. Execute o seguinte comando gcloud:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--stage DISABLED

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id. Também é possível usar a sinalização --organization [ORGANIZATION-ID] caso o papel tenha sido criado no nível da organização, como 1234567.

No exemplo a seguir, demonstramos como desativar um papel:

gcloud iam roles update viewer --project my-project-id \
--stage DISABLED

Se o papel for atualizado com sucesso, a resposta abaixo será retornada:

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: DISABLED
title: Role Viewer

REST API

Use o método roles.patch() para desativar um papel personalizado.

Se você sabe o código do papel personalizado que quer desativar, leia-o com o método roles.get(). Altere a propriedade stage dele para DISABLED e chame o método roles.patch() para atualizar o papel.

Se não souber o ID do papel personalizado que você quer desativar, use roles.list() para listar todos os papéis. roles.list() é usado para retornar uma lista de todos os papéis que se referem ao recurso. Identifique o papel que você quer desativar, altere a propriedade rolelaunchstage dele para DISABLED, e chame o método roles.patch() para atualizá-lo.

Para desativar o papel, configure os campos a seguir:

• Defina o nome do papel com a forma completa, organizations/{organization-id}/roles/{role}.
• Em Role, defina stage como DISABLED.
• Defina update_mask como "paths: stage".

Para reativar o papel, siga o mesmo processo descrito acima para desativá-lo. Entretanto, defina a propriedade stage como ALPHA, BETA ou GA.

Exemplo

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
    name: 'organizations/123456/roles/appengine.customRoleEditor'`
    stage: 'DISABLED'
}
update_mask {
    paths:  stage
}

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para atualizar o papel.
INVALID_ARGUMENT	Não é possível atualizar os papéis selecionados.
INVALID_ARGUMENT	O nome na solicitação ([ROLE-NAME]) precisa ser igual ao nome do papel ([ROLE-NAME]).
INVALID_ARGUMENT	Permissão [PERMISSION] inválida.
ABORTED	Houve alterações simultâneas na política. Tente refazer a sequência de leitura-modificação-gravação com retirada exponencial.

C#

Faça a atualização do campo stage do papel para DISABLED.

Go

Faça a atualização do campo stage do papel para DISABLED.

Python

Faça a atualização do campo stage do papel para DISABLED.

Como listar os papéis

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

   
   Todos os papéis personalizados do projeto são listados na página.

COMANDO GCLOUD

Use o comando gcloud iam roles list para listar papéis personalizados e predefinidos de um projeto ou de uma organização.

Execute o comando gcloud a seguir para listar os papéis personalizados, especificando o nível do projeto ou da organização:

gcloud iam roles list --project [PROJECT-ID]

[PROJECT-ID] é o nome do projeto, como my-project-id. Também é possível usar a sinalização --organization [ORGANIZATION-ID] se o papel tiver sido criado no nível da organização, como 1234567.

Para listar papéis excluídos, especifique a sinalização --show-deleted.

Execute o comando gcloud a seguir para listar os papéis predefinidos:

gcloud iam roles list

REST API

Use o método roles.list() para listar todos os papéis personalizados definidos em uma organização ou um projeto. Esse método também pode ser usado para listar os papéis predefinidos. Para isso, configure o campo pai na solicitação como "".

Para chamar roles.list(), configure o seguinte campo na solicitação:

• o recurso pai usado para chamar os papéis personalizados, por exemplo:
  • projects/{PROJECT-ID}
  • organizations/{ORGANIZATION-ID}

Para que o resultado contenha as permissões de cada papel, configure o campo view como RoleView::FULL.

Caso queira ver os papéis recentemente excluídos no resultado, defina o valor do campo showDeleted como true.

Se você quiser listar todos os papéis selecionados, defina o pai como "" (string vazia).

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para listar papéis em {path}.
INVALID_ARGUMENT	Pai {path} inválido. O pai precisa estar no formato organizations/{organization-id}, projects/{project-id} ou vazio.
INVALID_ARGUMENT	Visualização de papel inválida.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Role> ListRoles(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.Roles.List("projects/" + projectId)
            .Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine(role.Name);
        }
        return response.Roles;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID string) ([]*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	response, err := service.Projects.Roles.List("projects/" + projectID).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.List: %v", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Listing role: %v\n", role.Name)
	}
	return response.Roles, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def list_roles(project_id):
    """Lists roles."""

    # pylint: disable=no-member
    roles = service.roles().list(
        parent='projects/' + project_id).execute()['roles']
    for role in roles:
        print(role['name'])

Como excluir um papel personalizado

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Selecione o papel que você quer excluir e clique no ícone de lixeira, na parte superior da página.

COMANDO GCLOUD

Use o comando gcloud iam roles delete para excluir um papel personalizado. O papel é suspenso e não pode ser usado para criar vinculações de política do IAM.

Execute o seguinte comando gcloud para excluir papéis personalizados:

gcloud iam roles delete [ROLE-ID] --project [PROJECT-ID]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id. Também é possível usar a sinalização --organization [ORGANIZATION-ID] caso o papel tenha sido criado no nível da organização, como 1234567.

O papel não será incluído em gcloud iam roles list, a menos que a sinalização --show-deleted seja incluída. Os papéis excluídos são indicados pelo bloco deleted: true em uma resposta de list, como:

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

REST API

Com roles.delete, você exclui um papel. O papel é suspenso e não pode ser usado para criar vinculações de política do IAM.

Use um destes formatos para name:

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para excluir o papel em {path}.
FAILED_PRECONDITION	Não é possível excluir o papel {ROLE-NAME}, ele já foi excluído.
FAILED_PRECONDITION	Não é possível excluir um papel {ROLE-NAME} reservado.
INVALID_ARGUMENT	O estado dos papéis selecionados não pode ser excluído.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return fmt.Errorf("iam.New: %v", err)
	}

	_, err = service.Projects.Roles.Delete("projects/" + projectID + "/roles/" + name).Do()
	if err != nil {
		return fmt.Errorf("Projects.Roles.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted role: %v", name)
	return nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def delete_role(name, project):
    """Deletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().delete(
        name='projects/' + project + '/roles/' + name).execute()

    print('Deleted role: ' + name)
    return role

Quando um papel é excluído, as vinculações associadas a ele permanecem, mas estão inativas. É possível recuperar um papel em até sete dias. Durante esse período, o papel será mostrado como Excluído no Console do GCP e não aparecerá nos comandos da list programática, a menos que showDeleted esteja definido na solicitação.

Após sete dias, o papel está programado para exclusão permanente. Esse processo leva 30 dias. Durante esse período, o papel e todas as vinculações associadas são permanentemente removidos e não é possível criar um novo com o mesmo código do papel.

Depois que o papel for excluído permanentemente, 37 dias após a solicitação de exclusão inicial, você poderá criar um novo usando o mesmo código de função.

Como cancelar a exclusão de um papel personalizado

Console

1. Acesse a página "Papéis" no Console do GCP.

   Abrir a página "Papéis"

2. Localize o papel para que você quer cancelar a exclusão e clique no ícone "Mais" no final da linha. Em seguida, clique em Cancelar exclusão.

A exclusão do papel só pode ser cancelada em até sete dias. Após esse período, o papel é permanentemente excluído e todas as vinculações associadas a ele são removidas.

COMANDO GCLOUD

Use o comando gcloud iam roles undelete para cancelar a exclusão de um papel personalizado. Quando a exclusão do papel é cancelada, ele retorna para o estado anterior.

A exclusão do papel só pode ser cancelada em até sete dias. Após esse período, o papel é permanentemente excluído e todas as vinculações associadas a ele são removidas.

Execute o seguinte comando gcloud para cancelar a exclusão de um papel personalizado:

gcloud iam roles undelete [ROLE-ID] --project [PROJECT-ID]

Cada um dos valores dos marcadores está descrito abaixo:

• [ROLE-ID] é o nome do papel, como viewer.
• [PROJECT-ID] é o nome do projeto, como my-project-id. Também é possível usar a sinalização --organization [ORGANIZATION-ID] caso o papel tenha sido criado no nível da organização, como 1234567.

No exemplo a seguir, demonstramos como cancelar a exclusão de um papel personalizado:

gcloud iam roles undelete viewer --project my-project-id

Se o cancelamento da exclusão for bem-sucedido, a resposta a seguir será retornada:

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

Com roles.undelete, o papel volta ao estado anterior.

Use um destes formatos para name:

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

A exclusão do papel só pode ser cancelada em até sete dias. Após esse período, o papel é permanentemente excluído e todas as vinculações associadas a ele são removidas.

Códigos de erro

Código de erro	Mensagem de status
PERMISSION_DENIED	Você não tem permissão para cancelar a exclusão do papel em {path}.
FAILED_PRECONDITION	Não é possível cancelar a exclusão de um papel que não foi excluído.
FAILED_PRECONDITION	Não é possível cancelar a exclusão de um papel {ROLE-NAME} reservado.
INVALID_ARGUMENT	Não é possível cancelar a exclusão de papéis predefinidos.

C#

Antes de testar este exemplo, siga as instruções de configuração do C# no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para C#.

Ver no GitHub Feedback

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static Role UndeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

Go

Antes de testar este exemplo, siga as instruções de configuração do Go no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Go.

Ver no GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name string) (*iam.Role, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	request := &iam.UndeleteRoleRequest{}
	role, err := service.Projects.Roles.Undelete(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Undelete: %v", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Cloud IAM: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API do Cloud IAM para Python.

Ver no GitHub Feedback

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role