Como criar e gerenciar papéis personalizados

Nesta página, descrevemos como criar e gerenciar papéis personalizados de gerenciamento de identidade e acesso (IAM). O gerenciamento de papéis inclui modificar, desativar, listar, excluir e cancelar a exclusão de papéis.

Antes de começar

Funções exigidas

Para conseguir as permissões necessárias para criar e gerenciar papéis personalizados, peça ao administrador que conceda a você os seguintes papéis do IAM:

  • Para gerenciar papéis para um projeto: administrador de papéis (roles/iam.roleAdmin) no projeto onde você quer gerenciar os papéis
  • Para gerenciar papéis para uma organização: administrador de papéis da organização (roles/iam.organizationRoleAdmin) na organização onde você quer gerenciar os papéis

Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

Como ver as permissões disponíveis para projetos, pastas e organizações

É possível criar papéis personalizados para uma organização inteira ou para um projeto específico dessa organização.

É possível incluir várias, mas não todas, permissões de IAM em papéis personalizados. Cada permissão tem um dos seguintes níveis de suporte para uso em papéis personalizados:

Nível de suporte Descrição
SUPPORTED A permissão é totalmente compatível com papéis personalizados.
TESTING O Google está testando a permissão para verificar o suporte a papéis personalizados. É possível incluir a permissão em papéis personalizados, mas talvez você veja um comportamento inesperado. Isso não é recomendado para uso em produção.
NOT_SUPPORTED A permissão não é compatível com papéis personalizados.

Um papel personalizado no nível da organização pode incluir qualquer uma das permissões do IAM com suporte a papéis personalizados. Um papel personalizado para envolvidos no projeto pode conter qualquer permissão suportada, exceto as permissões relevantes apenas no nível da organização ou da pasta, como resourcemanager.organizations.get.

Para verificar quais permissões estão disponíveis para os papéis personalizados no nível da organização e do projeto, use a CLI gcloud ou a API de gerenciamento de identidade e acesso para listar as permissões disponíveis em uma organização ou projeto específico. Por exemplo, é possível conseguir todas as permissões disponíveis para papéis personalizados criados no projeto.

Algumas permissões podem não estar visíveis para você ou utilizáveis em um papel personalizado, mesmo que sejam suportadas por papéis personalizados. Por exemplo, uma permissão pode não estar disponível para uso em papéis personalizados se você não tiver ativado a API para o serviço.

gcloud

Use o comando gcloud iam list-testable-permissions para receber uma lista de permissões disponíveis para papéis personalizados em um projeto ou organização específicos. A resposta lista as permissões que podem ser usadas em papéis personalizados para esse projeto ou organização.

Para listar as permissões disponíveis em papéis personalizados de um projeto ou organização, execute este comando:

gcloud iam list-testable-permissions full-resource-name \
    --filter="customRolesSupportLevel!=NOT_SUPPORTED"

Substitua full-resource-name por um dos seguintes valores:

  • Projeto: //cloudresourcemanager.googleapis.com/projects/project-id (por exemplo, //cloudresourcemanager.googleapis.com/projects/my-project-id)
  • Organização: //cloudresourcemanager.googleapis.com/organizations/numeric-id (por exemplo, //cloudresourcemanager.googleapis.com/organizations/123456789012)

Os resultados indicam se cada permissão é compatível com papéis personalizados. As permissões que não têm um campo customRolesSupportLevel são totalmente compatíveis.

O comando list-testable-permissions pode retornar centenas de resultados. Este exemplo parcial mostra o formato de cada resultado:

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

REST

O método permissions.queryTestablePermissions lista as permissões disponíveis em uma organização ou um projeto.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • full-resource-name: um URI que consiste no nome do serviço e no caminho para o recurso. Veja exemplos em Nomes de recursos completos.
  • page-size: opcional. O número de permissões a serem incluídas na resposta. O valor padrão é 100, e o valor máximo é 1.000. Se o número de permissões for maior que o tamanho da página, a resposta conterá um token de paginação que é possível usar para recuperar a próxima página de resultados.
  • next-page-token: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de permissões testáveis começará onde a resposta anterior terminou.

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions

Corpo JSON da solicitação:

{
  "fullResourceName": "full-resource-name"
  "pageSize": page-size,
  "pageToken": "next-page-token"
}

Para enviar a solicitação, expanda uma destas opções:

A resposta contém a lista de permissões. 

{
  "permissions": [
    {
      "name": "iam.serviceAccountKeys.create",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.delete",
      "stage": "GA"
    },
    {
      "name": "iam.serviceAccountKeys.get",
      "stage": "GA"
    }
  ],
  "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q"
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::QueryTestablePermissionsRequest request;
  request.set_full_resource_name(resource);
  int count = 0;
  for (auto const& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::runtime_error(permission.status().message());
    std::cout << "Permission successfully retrieved: " << permission->name()
              << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No testable permissions found in resource: " << resource
              << "\n";
  }
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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. É possível visualizar os metadados usando o console ou a API do IAM.

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

Console

  1. No console, acesse a página Papéis.

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

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:

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:

  • 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 do marcador é descrito a seguir:

  • 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 saber mais, consulte a documentação de referência para gcloud iam roles describe.

REST

O método roles.get recebe a definição de um papel.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • full-role-id: o ID completo do papel, incluindo os prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

Método HTTP e URL: 

GET https://iam.googleapis.com/v1/full-role-id

Para enviar a solicitação, expanda uma destas opções:

A resposta contém a definição do papel. 

{
  "name": "projects/my-project/roles/customRole",
  "title": "My Custom Role",
  "description": "My custom role description.",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "etag": "BwWiPg2fmDE="
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::GetRoleRequest request;
  request.set_name(name);
  auto response = client.GetRole(request);
  if (!response) throw std::runtime_error(response.status().message());
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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 de administrador de papéis da organização ou de papéis de IAM.

Cada papel personalizado pode conter até 3.000 permissões. Além disso, o tamanho total máximo do título, da descrição e dos nomes de permissão de um papel personalizado é de 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).

Cada papel personalizado pode ter um estágio de lançamento. A maior parte dos estágios de lançamento é informativa e ajuda a monitorar se cada papel está pronto para uso geral. Além disso, a etapa de lançamento DISABLED permite desativar um papel personalizado. Para mais informações sobre as etapas de lançamento, consulte Como testar e implantar.

Console

Alguns papéis predefinidos têm permissões com uso suspenso ou não permitidas em papéis personalizados. Se você tentar criar um papel personalizado com base em um desses papéis predefinidos, esse papel omitirá as permissões obsoletas e restritas.

Para criar um papel personalizado do zero:

  1. No console, acesse a página Papéis.

    Acessar a página "Papéis"

  2. Usando a lista suspensa na parte superior da página, selecione a organização ou o projeto em que você quer criar um papel.

  3. Clique em Criar papel.

  4. Insira um Nome, Título, Descrição e Estágio de lançamento do papel para o papel. Após a criação do papel, não é possível alterar o nome dele.

  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 predefinido atual, siga estas etapas:

  1. No console, acesse a página Papéis.

    Acessar 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, Título, Descrição e Estágio de lançamento do papel para o papel. Após a criação do papel, não é possível alterar o nome dele.
  6. Desmarque as permissões que quer excluir do papel.
  7. Clique em Adicionar permissões para incluir permissões.
  8. Clique em Criar.

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.

Um papel personalizado pode conter apenas permissões compatíveis em papéis personalizados. Se o papel personalizado tiver outras permissões, o comando falhará.

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 do marcador é descrito a seguir:

  • 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. Não é possível usar caracteres curinga (*) em nomes de permissão.

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 do marcador é descrito a seguir:

  • 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 do marcador é descrito a seguir:

  • 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. Não é possível usar caracteres curinga (*) em nomes de permissão.
  • 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

REST

O método roles.create cria um papel personalizado em um projeto ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • resource-type: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valor projects ou organizations.
  • resource-id: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos da organização são numéricos, como 123456789012.
  • role-id: o nome do papel, como myCompanyAdmin.
  • role-title: o título legível do papel. Por exemplo, My Company Admin.
  • role-description: uma descrição para o papel. Por exemplo, "The company admin role allows company admins to access important resources".

  • permission-1 e permission-2: as permissões que você quer incluir no papel. Por exemplo, storage.objects.update. Não é possível usar caracteres curinga (*) em nomes de permissão.

    Um papel personalizado pode conter apenas permissões compatíveis com papéis personalizados. Se o papel personalizado tiver outras permissões, a solicitação falhará.

  • launch-stage: o estágio de lançamento atual do papel. Esse campo pode conter um dos seguintes valores: EAP, ALPHA, BETA, GA, DEPRECATED ou DISABLED.

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/resource-type/resource-id/roles

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

A resposta contém o papel que você criou. 

{
  "name": "projects/myProject/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWox/JbaZw="
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& parent, std::string const& role_id,
   std::vector<std::string> const& included_permissions) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::CreateRoleRequest request;
  request.set_parent("projects/" + parent);
  request.set_role_id(role_id);
  google::iam::admin::v1::Role role;
  role.set_stage(google::iam::admin::v1::Role::GA);
  for (auto const& permission : included_permissions) {
    *role.add_included_permissions() = permission;
  }
  *request.mutable_role() = role;
  auto response = client.CreateRole(request);
  if (!response) throw std::runtime_error(response.status().message());
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Um padrão comum para atualizar os metadados de um recurso, como um papel personalizado, é o padrão read-modify-write. Com esse padrão, você lê o estado atual do papel, atualiza os dados localmente e envia os dados modificados para gravação.

O padrão read-modify-write pode causar um conflito 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. O IAM resolve esse problema usando uma propriedade etag em 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 IAM com um valor ETag, o 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. No console, acesse a página Papéis.

    Acessar a página "Papéis"

  2. Na lista suspensa na parte superior da página, 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. Para atualizar os metadados do papel, edite o Título, a Descrição ou o Estágio de lançamento do papel.

  6. Para atualizar as permissões do papel, faça o seguinte:

    1. Clique em Adicionar permissões para adicionar novas permissões ao papel.
    2. Desmarque as permissões para removê-las do papel.

  7. Clique em Atualizar para salvar o papel editado.

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 do marcador é descrito a seguir:

  • role-id é o nome do papel a ser atualizado, como myCompanyAdmin.
  • 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 do marcador é descrito a seguir:

  • 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. Não é possível usar caracteres curinga (*) em nomes de permissão.
  • 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 do marcador é descrito a seguir:

  • role-id é o nome do papel a ser atualizado, 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 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 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. Não é possível usar caracteres curinga (*) em nomes de permissão.
  • --remove-permissions=permissions: remove do papel uma ou mais permissões separadas por vírgula. Não é possível usar caracteres curinga (*) em nomes de permissão.

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 do marcador é descrito a seguir:

  • 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.".
  • 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/myCompanyAdmin
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

REST

O método roles.patch atualiza um papel personalizado em um projeto ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

Obrigatório:

  • resource-type: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valor projects ou organizations.
  • resource-id: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos da organização são numéricos, como 123456789012.

  • full-role-id: o ID completo do papel, incluindo os prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

Recomendação:

  • etag: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.

Opcional (defina um ou mais dos seguintes valores):

  • role-title: o título legível do papel. Por exemplo, My Company Admin.
  • role-description: uma descrição para o papel. Por exemplo, "The company admin role allows company admins to access important resources".
  • permission-1 e permission-2: as permissões que você quer incluir no papel. Por exemplo, storage.objects.update. Não é possível usar caracteres curinga (*) em nomes de permissão.
  • launch-stage: o estágio de lançamento atual do papel. Esse campo pode conter um dos seguintes valores: EAP, ALPHA, BETA, GA, DEPRECATED ou DISABLED.

Método HTTP e URL: 

PATCH https://iam.googleapis.com/v1/resource-type/resource-id/roles

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

A resposta contém uma definição de papel abreviada que inclui o nome do papel, os campos que você atualizou e uma ETag que identifica a versão atual do papel. 

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "title": "My Updated Company Admin",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "stage": "BETA",
  "etag": "BwWoyDpAxBc="
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& name, std::string const& title) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UpdateRoleRequest request;
  request.set_name(name);
  google::iam::admin::v1::Role role;
  role.set_title(title);
  google::protobuf::FieldMask update_mask;
  *update_mask.add_paths() = "title";
  *request.mutable_role() = role;
  *request.mutable_update_mask() = update_mask;
  auto response = client.UpdateRole(request);
  if (!response) throw std::runtime_error(response.status().message());
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Desative um papel personalizado alterando o estágio de lançamento para DISABLED. Quando um papel é desativado, as vinculações de política relacionadas a ele ficam inativas e as permissões de atribuição não podem ser aplicadas a um usuário.

Console

  1. No console, acesse a página Papéis.

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

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 do marcador é descrito a seguir:

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

REST

O método roles.patch permite alterar o estágio de lançamento de um papel personalizado para DISABLED, o que desativa o papel.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • resource-type: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valor projects ou organizations.
  • resource-id: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos da organização são numéricos, como 123456789012.

  • full-role-id: o ID completo do papel, incluindo os prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  • etag: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.

Método HTTP e URL: 

PATCH https://iam.googleapis.com/v1/resource/resource-id/roles

Corpo JSON da solicitação:

{
  "roleId": "full-role-id",
  "stage": DISABLED,
  "etag": "etag"
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "stage": "DISABLED",
  "etag": "BwWoyDpAxBc="
}

C++

Atualize o campo stage do papel para DISABLED.

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 papéis

É possível listar todos os papéis personalizados criados no seu projeto ou organização.

Console

No console, acesse a página Papéis.

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

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 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 do marcador é descrito a seguir:

  • 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 para listar papéis predefinidos:

gcloud iam roles list

REST

O método roles.list lista todos os papéis personalizados em um projeto ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • resource-type: o tipo de recurso com os papéis personalizados que você quer gerenciar. Use o valor projects ou organizations.
  • resource-id: o ID do projeto ou da organização com os papéis personalizados que você quer gerenciar. Os IDs do projeto são strings alfanuméricas, como my-project. Os códigos da organização são numéricos, como 123456789012.
  • role-view: opcional. As informações a serem incluídas para os papéis retornados. Para incluir as permissões dos papéis, defina este campo como FULL. Para excluir as permissões dos papéis, defina este campo como BASIC. O valor padrão é BASIC.
  • page-size: opcional. O número de papéis a serem incluídos na resposta. O valor padrão é 300 e o valor máximo é 1.000. Se o número de papéis for maior que o tamanho da página, a resposta conterá um token de paginação que pode ser usado para recuperar a próxima página de resultados.
  • next-page-token: opcional. O token de paginação retornado em uma resposta anterior desse método. Se especificado, a lista de papéis começará onde a solicitação anterior foi finalizada.

Método HTTP e URL: 

GET https://iam.googleapis.com/v1/resource-type/resource-id/roles?view=role-view&pageSize=page-size&pageToken=next-page-token

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "roles": [
    {
      "name": "projects/my-project/roles/customRole1",
      "title": "First Custom Role",
      "description": "Created on: 2020-06-01",
      "etag": "BwWiPg2fmDE="
    },
    {
      "name": "projects/my-project/roles/customRole2",
      "title": "Second Custom Role",
      "description": "Created on: 2020-06-07",
      "etag": "BwWiuX53Wi0="
    }
  ]
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& project) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  google::iam::admin::v1::ListRolesRequest request;
  request.set_parent(project);
  for (auto const& role : client.ListRoles(request)) {
    if (!role) throw std::runtime_error(role.status().message());
    std::cout << "Roles successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No roles found in project: " << project << "\n";
  }
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

É possível excluir qualquer papel personalizado no seu projeto ou organização.

Console

  1. No console, acesse a página Papéis.

    Acessar a página "Papéis"

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

gcloud

Use o comando gcloud iam roles delete para excluir um papel personalizado.

  • 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 do marcador é descrito a seguir:

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

REST

O método roles.delete exclui um papel personalizado em um projeto ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • full-role-id: o ID completo do papel, incluindo os prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

Método HTTP e URL: 

DELETE https://iam.googleapis.com/v1/full-role-id

Para enviar a solicitação, expanda uma destas opções:

A resposta contém a definição do papel que foi excluído. 

{
  "name": "projects/my-project/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWiPg2fmDE=",
  "deleted": true
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::DeleteRoleRequest request;
  request.set_name(name);
  auto response = client.DeleteRole(request);
  if (!response) throw std::runtime_error(response.status().message());
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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, todas as vinculações de papel que se referem a ele permanecem nas políticas do IAM, mas não terão efeito. É possível recuperar um papel em até sete dias. Durante esse período de sete dias, o console mostra que o papel foi excluído. Também é possível listar papéis excluídos de maneira programática, mas eles são omitidos por padrão.

Após 7 a 14 dias, o papel é programado para exclusão permanente. 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, será possível criar um novo usando o mesmo ID até 44 dias após a solicitação de exclusão inicial.

Como cancelar a exclusão de um papel personalizado

Cancelar a exclusão de um papel faz com que ele retorne ao estado anterior.

Só é possível cancelar a exclusão de papéis em até sete dias após a exclusão. Após esse período, o papel pode ser permanentemente excluído a qualquer momento, e todas as vinculações de papel que se referem a ele são removidas.

Console

  1. No console, acesse a página Papéis.

    Acessar a página "Papéis"

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

gcloud

Use o comando gcloud iam roles undelete para cancelar a exclusão de um papel personalizado.

  • 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 do marcador é descrito a seguir:

  • 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

REST

O método roles.undelete cancela a exclusão de um papel personalizado em um projeto ou organização.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • full-role-id: o ID completo do papel, incluindo os prefixos organizations/, projects/ ou roles/. Exemplo: organizations/123456789012/roles/myCompanyAdmin.

  • etag: identificador de uma versão do papel. Inclua este campo para evitar a substituição de outras alterações de papéis.

Método HTTP e URL: 

POST https://iam.googleapis.com/v1/full-role-id:undelete

Corpo JSON da solicitação:

{
  "etag": "etag"
}

Para enviar a solicitação, expanda uma destas opções:

A resposta contém a definição do papel que teve a exclusão cancelada. 

{
  "name": "projects/my-project/roles/myCompanyAdmin",
  "title": "My Company Admin",
  "description": "My custom role description.",
  "includedPermissions": [
    "iam.roles.get",
    "iam.roles.list"
  ],
  "etag": "BwWiPg2fmDE="
}

C++

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API IAM para C++. 

namespace iam = ::google::cloud::iam;
[](std::string const& name) {
  iam::IAMClient client(iam::MakeIAMConnection());
  google::iam::admin::v1::UndeleteRoleRequest request;
  request.set_name(name);
  auto response = client.UndeleteRole(request);
  if (!response) throw std::runtime_error(response.status().message());
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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

Para saber como instalar e usar a biblioteca de cliente do IAM, consulte Bibliotecas de cliente do IAM. Para mais informações, consulte a documentação de referência da API 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