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 IAM e confira informações sobre as permissões necessárias 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, você poderá ver todas as permissões aplicáveis a esse recurso. Por exemplo, quando você seleciona o papel Administrador da instância 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 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 código 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

    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 É preciso especificar {full_resource_name}
INVALID_ARGUMENT {full_resource_name}, não corresponde a //[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 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. Para visualizá-los, você pode usar o Console do Google Cloud Platform ou a API IAM.

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

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

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

    gcloud iam roles describe [ROLE-NAME]
    

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

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, determine primeiro se ele foi criado no nível do projeto ou da organização. Se o papel personalizado tiver sido criado no nível da organização, execute o seguinte 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 no nível do projeto, execute o seguinte 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.

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-NAME} ou organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}.

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} ou em branco.
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

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.

Os usuários que não são proprietários, incluindo administradores da organização, precisam receber o papel de "Administrador de papéis da organização" ou "Administrador de papel" do IAM.

Console

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

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

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

    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 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, você precisa especificar 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 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]
    

Veja abaixo a descrição de cada um dos valores de marcador:

  • [ROLE-TITLE] é um título amigável para o papel, como "Role Viewer".
  • [ROLE-DESCRIPTION] é uma breve descrição sobre o 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.
  • includedPermissions especifica a lista de uma ou mais permissões a incluir no papel personalizado, como - iam.roles.get.

Salve o arquivo YAML e, em seguida, execute o seguinte comando gcloud:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [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] \
    

Veja abaixo a descrição de cada um dos valores de marcador:

  • [ROLE-ID] é o nome do papel, como viewer.
  • [PROJECT-ID] é o nome do projeto, como my-project-id.
  • [ROLE-TITLE] é um título amigável para o papel, como "Role Viewer".
  • [ROLE-DESCRIPTION] é uma breve descrição sobre o 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
    

API REST

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

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

  • O role_id que você quer usar para o novo papel personalizado, como 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, 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 que não sã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 em que você está criando o papel personalizado, por exemplo organizations/0000000000000001, ou o código do projeto em que você está criando o papel personalizado, por exemplo projects/my-project.
  • [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.

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

Ao atualizar os metadados de um recurso como um papel personalizado, é comum 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 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 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:

Consiga a definição atual do papel executando o seguinte comando gcloud:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [ROLE-ID] é o nome do papel a ser atualizado, como viewer.
  • [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: [ROLE-ID]
    stage: [LAUNCH-STAGE]
    title: [ROLE-TITLE]
    

Veja abaixo a descrição de cada um dos valores de marcador:

  • [ROLE-DESCRIPTION] é uma breve descrição sobre o papel, como "My custom role description".
  • [ETAG-VALUE] é o identificador exclusivo da versão atual do papel, como BwVkBkbfr70=.
  • includedPermissions especifica a lista de uma ou mais permissões a incluir 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 amigável 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 etag gerado.

Considere o seguinte exemplo de arquivo YAML, que contém 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, em seguida, execute o seguinte comando gcloud:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [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 \
    

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 uma das partes da definição de papel pode ser atualizada usando uma sinalização correspondente. Consulte o tópico sobre gcloud iam roles update para ver uma lista de todas as 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 separada por vírgulas para substituir a lista atual de permissões.

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

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [ROLE-ID] é o nome do papel, como viewer.
  • [PROJECT-ID] é o nome do projeto, como my-project-id.
  • [ROLE-TITLE] é um título amigável para o papel, como "Role Viewer".
  • [ROLE-DESCRIPTION] é uma breve descrição sobre o 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 corretamente, 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
    

API REST

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

Se você souber o código do papel que quer editar, consiga o papel usando o método roles.get() e, em seguida, atualize o papel usando roles.patch().

Se você não souber o código 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 campo update_mask para especificar o(s) campo(s) 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. pode estar no formato roles/{ROLE-NAME}, organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME} ou projects/{PROJECT-ID}/roles/{ROLE-NAME}.

  • [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 espera exponencial.

Alguns papéis predefinidos têm permissões com uso suspenso ou que não sã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 um papel é desativado, as vinculações de política relacionadas a ele ficam inativas e as permissões se tornam inválidas, mesmo que esse papel seja 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 atual é usar a sinalização --stage e defini-la como DISABLED. Execute o seguinte comando gcloud:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [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] se o papel tiver 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
    

API REST

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

Se você sabe o código do papel personalizado que quer desativar, consiga-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 código 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 rolelaunchstage para DISABLED, e chame o método roles.patch() para atualizar o papel.

Para desativar o papel, configure os campos a seguir:

  • Defina o nome com o nome completo do papel, organizations/{organization-id}/roles/{role}.
  • No 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#

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

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

    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 uma organização.

Execute o comando gcloud a seguir para listar papéis personalizados, especificando papéis personalizados no 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 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 um projeto; ele também pode ser usado para listar os papéis predefinidos configurando o campo pai na solicitação para "".

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

  • O recurso pai a ser usado para conseguir todos os papéis personalizados, por exemplo
    • projects/{PROJECT-ID}
    • organizations/{ORGANIZATION-ID}

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

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

Caso queira listar todos os papéis selecionados, defina o recurso pai como "", uma 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 em branco.
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 gcloud

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

Execute o seguinte comando gcloud para excluir um papel personalizado:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [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] se o papel tiver 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 list, como:

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

API REST

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

name pode estar nos seguintes formatos

  • 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 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 cancelar a exclusão de um papel em até sete dias. Durante esse período, 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. 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 Cloud.

    Abrir a página "Papéis"

  2. Localize o papel para o qual 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 comando gcloud a seguir para cancelar a exclusão de um papel personalizado:

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

Veja abaixo a descrição de cada um dos valores de marcador:

  • [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] se o papel tiver 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
    

API REST

roles.undelete restaura o estado anterior de um papel.

name pode estar nos seguintes formatos

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