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 exigidas para criar papéis personalizados e práticas recomendadas.
  • Se você estiver usando o utilitário de linha de comando gcloud, verifique se sua versão é 188.0.0 ou posterior. Para atualizar o gcloud para a versão 188.0.0, 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 os recursos abaixo 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 se pode aplicar em uma organização e em projetos nessa organização.

Console

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

    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 da gcloud

Use o comando gcloud iam list-testable-permissions para ver uma lista de permissões que podem ser aplicadas a 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 ID do projeto no formato de um nome de recurso completo: //cloudresourcemanager.googleapis.com/projects/project-id, como //cloudresourcemanager.googleapis.com/projects/my-project-id.

O comando list-testable-permissions pode retornar centenas de resultados. Para limitar os resultados, especifique uma expressão de filtro. Veja abaixo um exemplo truncado de resultados possíveis:

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

API REST

QueryTestablePermissions retorna todas as permissões que podem ser aplicadas a um recurso. 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. A única entrada obrigatória para esta solicitação é o nome completo do recurso, como //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

{
  "fullResourceName": "//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 É necessário especificar o campo full_resource_name.
INVALID_ARGUMENT O campo full_resource_name (full-resource-name) é inválido. Ele não corresponde a //[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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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

    Abrir a página "Papéis"

  2. Selecione a organização ou o projeto na lista suspensa na parte superior da página.

  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 na coluna Tipo indicam se é um papel personalizado ou predefinido

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 da gcloud

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

Para visualizar os metadados de um papel predefinido, execute o seguinte comando da gcloud:

gcloud iam roles describe role-id

role-id é o ID do papel. Os papéis predefinidos incluem o prefixo role nos IDs. Por exemplo, roles/iam.roleViewer.

O exemplo a seguir demonstra 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, execute um dos seguintes comandos gcloud:

  • Para visualizar os metadados de um papel personalizado criado no nível da organização, execute o seguinte comando:

    gcloud iam roles describe --organization=organization-id role-id
    
  • Para visualizar os metadados de um papel personalizado criado no nível do projeto, execute o seguinte comando:

    gcloud iam roles describe --project=project-id role-id
    

Cada valor de marcador é descrito abaixo:

  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.
  • role-id é o ID do papel, excluindo quaisquer prefixos como projects/, organizations/ ou roles/. Por exemplo, myCompanyAdmin.

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

API REST

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 GetRole(),, defina o seguinte campo em GetRoleRequest:

  • Nome do papel, como roles/role-id ou organizations/organization-id/roles/role-id.

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

  • O pai de que você quer receber todos os papéis personalizados, como 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 receber 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}", "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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

// getRole gets role metadata.
func getRole(w io.Writer, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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

É possível criar um papel personalizado no nível do projeto ou da organização.

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 "Administrador de papéis da organização" ou "Administrador de papéis do IAM".

O tamanho total do título, da descrição e dos nomes de permissão de um papel personalizado é limitado a 64 KB. Caso precise criar um maior, é possível dividir as permissões em vários papéis personalizados. Escolha títulos que mostrem a relação entre os papéis personalizados, como Custom Admin (1 of 2) e Custom Admin (2 of 2).

Console

Para criar um papel personalizado do zero:

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

    Abrir a página "Papéis"

  2. Selecione a organização ou o projeto em que você quer criar um papel.

  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 selecionado:

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

    Abrir a página "Papéis"

  2. Selecione a organização ou o projeto em que você quer criar um papel.
  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 da gcloud

Use o comando gcloud iam roles create para criar novos 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.

Ao criar um papel personalizado, é necessário determinar se ele se aplica ao nível da organização ou do projeto usando os sinalizadores --organization=organization-id ou --project=project-id. Nos exemplos abaixo, são criados papéis personalizados no nível do projeto.

Para criar um papel personalizado usando um arquivo YAML:

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

title: role-title
description: role-description
stage: launch-stage
includedPermissions:
- permission-1
- permission-2

Cada valor de marcador é descrito abaixo:

  • role-title é um título intuitivo para o papel, como "My Company Admin".
  • 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.
  • permission-1 e permission-2 são permissões a serem incluídas no papel personalizado, como iam.roles.get.

Salve o arquivo YAML e execute um dos seguintes comandos:

  • Para criar um papel personalizado no nível da organização, execute o seguinte comando:

    gcloud iam roles create role-id --organization=organization-id \
      --file=yaml-file-path
    
  • Para criar um papel personalizado no nível do projeto, execute o seguinte comando:

    gcloud iam roles create role-id --project=project-id \
      --file=yaml-file-path
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como myCompanyAdmin.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.
  • yaml-file-path é o caminho do local do arquivo YAML que contém a definição do papel personalizado.

Exemplos

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

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

O exemplo a seguir demonstra como criar um papel no nível da organização usando o arquivo YAML:

gcloud iam roles create myCompanyAdmin --organization=123456789012 \
  --file=my-role-definition.yaml

Se o papel for criado, a saída do comando será semelhante a esta:

Created role [myCompanyAdmin].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organizations/123456789012/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

O exemplo a seguir demonstra como criar um papel no nível do projeto usando o arquivo YAML:

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

Se o papel for criado, a saída do comando será semelhante a esta:

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

Para criar um papel personalizado usando sinalizações:

Execute um dos seguintes comandos:

  • Para criar um papel personalizado no nível da organização, execute o seguinte comando:

    gcloud iam roles create role-id --organization=organization-id \
      --title=role-title --description=role-description \
      --permissions=permissions-list --stage=launch-stage
    
  • Para criar um papel personalizado no nível do projeto, execute o seguinte comando:

    gcloud iam roles create role-id --project=project-id \
      --title=role-title --description=role-description \
      --permissions=permissions-list --stage=launch-stage
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como myCompanyAdmin.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.
  • role-title é um título intuitivo para o papel, como "My Company Admin".
  • 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.

Exemplos

O exemplo a seguir demonstra como criar um papel no nível da organização usando sinalizações:

gcloud iam roles create myCompanyAdmin --organization=123456789012\
  --title="My Company Admin" --description="My custom role description." \
  --permissions=iam.roles.get,iam.roles.list --stage=ALPHA

Se o papel for criado, a saída do comando será semelhante a esta:

Created role [myCompanyAdmin].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organizations/123456789012/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

O exemplo a seguir demonstra como criar um papel no nível do projeto usando sinalizações:

gcloud iam roles create myCompanyAdmin --project=my-project-id \
  --title="My Company Admin" --description="My custom role description." \
  --permissions=iam.roles.get,iam.roles.list --stage=ALPHA

Se o papel for criado, a saída do comando será semelhante a esta:

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

API REST

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

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

  • O ID do papel que você quer usar para o novo papel personalizado, como 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:

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

stage assume os seguintes valores: ALPHA, BETA, GA, DEPRECATED ou 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

{
  "roleId": "full-role-id",
  "role": {
    "title": "role-title",
    "description": "role-description",
    "includedPermissions": [
      "permission-1",
      "permission-2"
    ]
  }
}

Em que:

  • full-role-id é o ID completo do papel, incluindo qualquer prefixo organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.
  • role-title é o título do papel. Por exemplo, Storage Auditor.
  • role-description é a descrição desse papel.
  • permission-1 e permission-2 são as permissões que você quer incluir no papel personalizado.

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 denominado role-id em parent.
INVALID_ARGUMENT Pai path inválido. O pai precisa estar no formato "organizations/{organization_id}", "projects/{project_id}" ou vazio.
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 role.stage 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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

	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) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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. Essa propriedade é usada para verificar se o papel personalizado foi alterado desde a última solicitação. Quando você faz uma solicitação ao Cloud IAM com um valor etag, o Cloud IAM compara o valor etag na solicitação com o valor etag existente associado ao papel personalizado. A alteração só é gravada quando esses valores são correspondentes.

Ao atualizar um papel, primeiro consiga o papel usando roles.get(), atualize o papel e, em seguida, grave o papel atualizado usando roles.patch(). Ao configurar o papel, use o valor etag somente quando o papel correspondente em roles.get() também contiver um valor etag.

Console

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

    Abrir a página "Papéis"

  2. Selecione o projeto ou a organização que contém o papel que você quer editar.

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

Ao atualizar um papel personalizado, especifique se ele se aplica ao nível da organização ou do projeto usando as sinalizações --organization=organization-id ou --project=project-id. Nos exemplos abaixo, são criados papéis personalizados no nível do projeto.

Para atualizar um papel personalizado usando um arquivo YAML:

Veja a definição atual do papel executando um dos seguintes comandos:

  • Para ver a definição de um papel personalizado no nível da organização, execute o seguinte comando:

    gcloud iam roles describe role-id --organization=organization-id
    
  • Para ver a definição de um papel personalizado no nível do projeto, execute o seguinte comando:

    gcloud iam roles describe role-id --project=project-id
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel a ser atualizado, como viewer.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.

O comando describe retorna a definição do papel e inclui um valor etag que identifica exclusivamente a versão atual do papel. O valor etag precisa ser incluído na definição atualizada do papel para impedir a substituição de alterações de papel simultâneas.

O comando describe retorna a seguinte saída:

description: role-description
etag: etag-value
includedPermissions:
- permission-1
- permission-2
name: full-role-id
stage: launch-stage
title: role-title

Cada valor de marcador é 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=.
  • permission-1 e permission-2 são permissões a serem incluídas no papel personalizado, como iam.roles.get.
  • full-role-id é o ID completo do papel, incluindo qualquer prefixo organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.
  • 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 intuitivo para o papel, como "My Company Admin".

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

Considere o seguinte arquivo YAML de exemplo, que contém a saída do comando describe para um papel no nível do projeto 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/myCompanyAdmin
stage: ALPHA
title: My Company Admin

Salve o arquivo YAML e execute um dos seguintes comandos:

  • Para atualizar um papel no nível da organização, execute o seguinte comando:

    gcloud iam roles update role-id --organization=organization-id \
      --file=yaml-file-path
    
  • Para atualizar um papel no nível do projeto, execute o seguinte comando:

    gcloud iam roles update role-id --project=project-id \
      --file=yaml-file-path
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel a ser atualizado, como viewer.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.
  • yaml-file-path é o caminho do local do arquivo YAML que contém a definição atualizada do papel personalizado.

Exemplos

O exemplo a seguir demonstra como atualizar um papel no nível da organização usando um arquivo YAML:

gcloud iam roles update myCompanyAdmin --organization=123456789012 \
  --file=my-role-definition.yaml

Se o papel for atualizado, a saída do comando será semelhante a esta:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: organizations/123456789012/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

O exemplo a seguir demonstra como atualizar um papel no nível do projeto usando um arquivo YAML:

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

Se o papel for atualizado, a saída do comando será semelhante a esta:

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/myCompanyAdmin
stage: ALPHA
title: My Company Admin

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 sinalizações a seguir para adicionar ou remover permissões:

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

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

Para atualizar outras partes da definição do papel, execute um dos seguintes comandos:

  • Para atualizar um papel no nível da organização, execute o seguinte comando:

    gcloud iam roles update role-id --organization=organization-id \
      --title=role-title --description=role-description \
      --stage=launch-stage
    
  • Para atualizar um papel no nível do projeto, execute o seguinte comando:

    gcloud iam roles update role-id --project=project-id \
      --title=role-title --description=role-description \
      --stage=launch-stage
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como viewer.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.
  • role-title é um título intuitivo para o papel, como "My Company Admin".
  • 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.

Exemplos

O exemplo a seguir demonstra como adicionar permissões a um papel no nível da organização usando sinalizações:

gcloud iam roles update myCompanyAdmin --organization=123456789012 \
  --add-permissions=storage.buckets.get,storage.buckets.list

Se o papel for atualizado, a saída do comando será semelhante a esta:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: organization/123456789012/roles/viewer
stage: ALPHA
title: My Company Admin

O exemplo a seguir demonstra como adicionar permissões a um papel no nível do projeto usando sinalizações:

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

Se o papel for atualizado, a saída do comando será semelhante a esta:

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/myCompanyAdmin
stage: ALPHA
title: My Company Admin

API REST

Se você souber o ID do papel personalizado que quer editar, veja o papel usando o método roles.get() e, em seguida, atualize-o usando roles.patch().

Se você não souber o ID do papel personalizado que quer editar, liste todos os papéis usando ListRoles() para identificá-lo. roles.list() retorna uma lista de todos os papéis que fazem referência ao recurso. Em seguida, atualize o papel usando roles.patch().

Defina o seguinte parâmetro obrigatório em roles.patch():

  • Nome do papel, como organizations/organization-id/roles/role-id.

Opcionalmente, defina o parâmetro de consulta updateMask para especificar quais campos você atualizou. Inclua o papel atualizado no corpo da solicitação.

Exemplo

{
  "name": "full-role-id",
  "title": "role-title",
  "description": "role-description",
  "includedPermissions": [
    "permission-1",
    "permission-2"
  ]
}

Em que:

  • full-role-id é o ID completo do papel, incluindo qualquer prefixo organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.

  • role-title é o título do papel. Por exemplo, New custom editor.

  • role-description é uma descrição do papel. Por exemplo, "My new long description of editor".

  • permission-1 e permission-2 são as permissões 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 (url-role-id) precisa ser igual ao nome do papel (full-role-id).
INVALID_ARGUMENT Permissão permission inválida.
ABORTED Houve alterações simultâneas na política porque os valores etag não correspondem. Tente refazer a sequência de leitura-modificação-gravação com espera 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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

	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) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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

    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 da gcloud

Use o comando gcloud iam roles update para desativar um papel personalizado definindo seu estágio de inicialização como DISABLED. Conforme descrito na guia gcloud da seção Como editar um papel personalizado, é 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-la como DISABLED. Execute um dos seguintes comandos:

  • Para desativar um papel no nível da organização, execute o seguinte comando:

    gcloud iam roles update role-id --organization=organization-id \
      --stage=DISABLED
    
  • Para desativar um papel no nível do projeto, execute o seguinte comando:

    gcloud iam roles update role-id --project=project-id \
      --stage=DISABLED
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como viewer.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.

Exemplos

O exemplo a seguir demonstra como desativar um papel no nível da organização:

gcloud iam roles update myCompanyAdmin --organization=123456789012 \
  --stage=DISABLED

Se o papel for atualizado, a saída do comando será semelhante a esta:

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organization/123456789012/roles/myCompanyAdmin
stage: DISABLED
title: My Company Admin

O exemplo a seguir demonstra como desativar um papel no nível do projeto:

gcloud iam roles update myCompanyAdmin --project=my-project-id \
  --stage=DISABLED

Se o papel for atualizado, a saída do comando será semelhante a esta:

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

API REST

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

Se você souber o ID do papel personalizado que quer desativar, veja-o usando o método roles.get(). Altere a propriedade stage do papel para DISABLED e, em seguida, chame o método roles.patch() para atualizar o papel.

Se você não souber o ID do papel personalizado que quer desativar, liste todos os papéis usando roles.list() para identificá-lo. roles.list() retorna uma lista de todos os papéis que fazem referência ao recurso. Identifique o papel que quer desativar, altere a propriedade stage para DISABLED, e chame o método roles.patch() para atualizar o papel.

Para desativar o papel, configure estes campos:

  • Defina o campo stage como DISABLED.
  • Defina o parâmetro de consulta updateMask como stage.

Para reativar o papel, siga o mesmo processo, mas defina o campo stage do papel como ALPHA, BETA ou GA.

Exemplo

{
  "name": "organizations/123456/roles/myCompanyCustomAdmin",
  "stage": "DISABLED"
}

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 (url-role-id) precisa ser igual ao nome do papel (full-role-id).
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#

Atualize o campo stage do papel para DISABLED.

Go

Atualize o campo stage do papel para DISABLED.

Python

Atualize o campo stage do papel para DISABLED.

Como listar os papéis

Console

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

Abrir a página "Papéis"

Todos os papéis personalizados da organização ou do projeto que você selecionou são listados na página.

Comando da gcloud

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

Para listar papéis personalizados, execute um dos seguintes comandos:

  • Para listar papéis personalizados no nível da organização, execute o seguinte comando:

    gcloud iam roles list --organization=organization-id
    
  • Para listar papéis personalizados no nível do projeto, execute o seguinte comando:

    gcloud iam roles list --project=project-id
    

Cada valor de marcador é descrito abaixo:

  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.

Para listar os papéis excluídos, também é possível especificar a sinalização --show-deleted.

Execute o seguinte comando gcloud para listar papéis predefinidos:

gcloud iam roles list

API REST

O método roles.list() pode ser usado para listar todos os papéis personalizados definidos em uma organização ou projeto. Ele também pode ser usado para listar os papéis predefinidos configurando o campo pai na solicitação como "".

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

  • o recurso pai usado para chamar os papéis personalizados, por exemplo:

    • projects/project-id
    • organizations/organization-id

Se quiser que o resultado contenha as permissões de cada papel, defina o campo view como FULL.

Se quiser que o resultado contenha papéis excluídos recentemente, defina o campo showDeleted como true.

Se quiser listar todos os papéis selecionados, defina o recurso 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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID string) ([]*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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

    Abrir a página "Papéis"

  2. Selecione o papel que você quer excluir e clique em Excluir na parte superior da página.

Comando da 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.

Para excluir um papel personalizado, execute um dos seguintes comandos:

  • Para excluir um papel personalizado no nível da organização, execute o seguinte comando:

    gcloud iam roles delete role-id --organization=organization-id
    
  • Para excluir um papel personalizado no nível do projeto, execute o seguinte comando:

    gcloud iam roles delete role-id --project=project-id
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como myCompanyAdmin.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.

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 list, como:

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/myCompanyAdmin
title: My Company Admin
---

API REST

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

name pode estar nos seguintes formatos:

  • organizations/organization-id
  • projects/project-id

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-id, ele já foi excluído.
FAILED_PRECONDITION Não é possível excluir um papel role-id reservado.
INVALID_ARGUMENT Os papéis selecionados não podem estar no estado 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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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 de sete dias, o papel será mostrado como Excluído no Console do Cloud e não aparecerá nos comandos list programáticos (a menos que showDeleted esteja definido na solicitação).

Após sete dias, o papel será excluído permanentemente. Até aqui, o papel não conta mais para o limite de 300 papéis personalizados por organização ou 300 papéis personalizados por projeto.

O processo de exclusão permanente dura 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 papel novo com o mesmo ID.

Depois que o papel for excluído permanentemente, 37 dias após a solicitação de exclusão inicial, será possível criar um novo usando o mesmo ID.

Como cancelar a exclusão de um papel personalizado

Console

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

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

Para cancelar a exclusão de um papel personalizado, execute um dos seguintes comandos:

  • Para cancelar a exclusão de um papel personalizado no nível da organização, execute o seguinte comando:

    gcloud iam roles undelete role-id --organization=organization-id
    
  • Para cancelar a exclusão de um papel personalizado no nível do projeto, execute o seguinte comando:

    gcloud iam roles undelete role-id --project=project-id
    

Cada valor de marcador é descrito abaixo:

  • role-id é o nome do papel, como myCompanyAdmin.
  • organization-id é o ID numérico da organização, como 123456789012.
  • project-id é o nome do projeto, como my-project-id.

Exemplos

O exemplo a seguir demonstra como cancelar a exclusão de um papel personalizado no nível da organização:

gcloud iam roles undelete myCompanyAdmin --organization=123456789012

Se a exclusão do papel for cancelada, a saída do comando será semelhante a esta:

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: organization/123456789012/roles/myCompanyAdmin
stage: ALPHA
title: My Company Admin

O exemplo a seguir demonstra como cancelar a exclusão de um papel personalizado no nível do projeto:

gcloud iam roles undelete myCompanyAdmin --project=my-project-id

Se a exclusão do papel for cancelada, a saída do comando será semelhante a esta:

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

API REST

roles.undelete restaura o papel ao estado anterior.

name pode estar nos seguintes formatos:

  • organizations/organization-id/roles/role-id
  • projects/project-id/roles/role-id

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-id 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 saber mais informações, consulte a documentação de referência da API Cloud IAM para C#.


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 Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name string) (*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %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 Cloud IAM para Python.

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

A seguir