Crie e faça a gestão de funções personalizadas

Esta página descreve como criar e gerir funções personalizadas da gestão de identidade e de acesso (IAM). A gestão de funções inclui a modificação, a desativação, a listagem, a eliminação e a recuperação de funções.

Antes de começar

• Enable the IAM API.

  Enable the API

• Configurar autenticação.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  C#

  Para usar os .NET exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud auth application-default login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

  C++

  Para usar os C++ exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud auth application-default login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

  Ir

  Para usar os Go exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud auth application-default login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

  Java

  Para usar os Java exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud auth application-default login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

  Python

  Para usar os Python exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud auth application-default login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação.

  REST

  Para usar os exemplos da API REST nesta página num ambiente de desenvolvimento local, usa as credenciais que fornece à CLI gcloud.

  Instale a CLI Google Cloud.

  Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  Para mais informações, consulte o artigo Autenticar para usar REST na Google Cloud documentação de autenticação.

  Compreenda a Google Cloud hierarquia de recursos.

  Leia o artigo Compreender as funções personalizadas do IAM.

Funções necessárias

Para receber as autorizações de que precisa para criar e gerir funções personalizadas, peça ao seu administrador que lhe conceda as seguintes funções de IAM:

• Para gerir funções de um projeto: Administrador de funções (roles/iam.roleAdmin) no projeto para o qual quer gerir funções
• Para gerir funções de uma organização: Administrador da função na organização (roles/iam.organizationRoleAdmin) na organização para a qual quer gerir funções

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Veja as autorizações disponíveis para projetos, pastas e organizações

Pode criar funções personalizadas para uma organização inteira ou para um projeto específico nessa organização. As autorizações disponíveis para funções personalizadas dependem do local onde cria a função. Por exemplo, se uma autorização só puder ser usada ao nível da organização, não pode incluir essa autorização numa função personalizada ao nível do projeto.

Para verificar que autorizações estão disponíveis para funções personalizadas ao nível da organização e ao nível do projeto, pode usar a CLI gcloud ou a API Identity and Access Management para listar as autorizações disponíveis numa organização ou num projeto específico. Por exemplo, pode obter todas as autorizações disponíveis para funções personalizadas criadas no seu projeto.

Algumas autorizações podem não estar visíveis ou não ser utilizáveis numa função personalizada, mesmo que sejam suportadas em funções personalizadas. Por exemplo, uma autorização pode não estar disponível para utilização em funções personalizadas se não tiver ativado a API para o serviço.

Para saber mais sobre as autorizações que pode adicionar a funções personalizadas, consulte o artigo Autorizações suportadas.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam list-testable-permissions para obter uma lista de autorizações disponíveis para funções personalizadas num projeto ou numa organização específicos. A resposta indica as autorizações que pode usar em funções personalizadas para esse projeto ou organização.

   Para listar as autorizações disponíveis em funções personalizadas para um projeto ou uma 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)

   • Organização: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID (por exemplo, //cloudresourcemanager.googleapis.com/organizations/123456789012)

   Os resultados indicam se cada autorização é suportada em funções personalizadas. As autorizações que não têm um campo customRolesSupportLevel são totalmente suportadas.

   O comando list-testable-permissions pode devolver 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
   ---
   

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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& permission : client.QueryTestablePermissions(request)) {
    if (!permission) throw std::move(permission).status();
    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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C# IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", err)
	}

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

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;
import com.google.iam.admin.v1.QueryTestablePermissionsRequest;
import java.io.IOException;

/** View available permissions in a project. */
public class QueryTestablePermissions {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    // Full resource names can take one of the following forms:
    // cloudresourcemanager.googleapis.com/projects/PROJECT_ID
    // cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID
    String fullResourceName = "your-full-resource-name";

    queryTestablePermissions(fullResourceName);
  }

  public static void queryTestablePermissions(String fullResourceName) throws IOException {
    QueryTestablePermissionsRequest queryTestablePermissionsRequest =
        QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();

    try (IAMClient iamClient = IAMClient.create()) {
      QueryTestablePermissionsPagedResponse queryTestablePermissionsPagedResponse =
          iamClient.queryTestablePermissions(queryTestablePermissionsRequest);
      queryTestablePermissionsPagedResponse
          .iterateAll()
          .forEach(permission -> System.out.println(permission.getName()));
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import os
from typing import List

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2, policy_pb2


def query_testable_permissions(
    project_id: str, permissions: List[str]
) -> policy_pb2.Policy:
    """Tests IAM permissions of the caller.

    project_id: ID or number of the Google Cloud project you want to use.
    permissions: List of permissions to get.
    """

    client = resourcemanager_v3.ProjectsClient()
    request = iam_policy_pb2.TestIamPermissionsRequest()
    request.resource = f"projects/{project_id}"
    request.permissions.extend(permissions)

    permissions_reponse = client.test_iam_permissions(request)
    print(permissions_reponse)
    return permissions_reponse.permissions

REST

O método permissions.queryTestablePermissions lista as autorizações disponíveis numa organização ou num projeto.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• FULL_RESOURCE_NAME: um URI composto pelo nome do serviço e o caminho para o recurso. Para ver exemplos, consulte o artigo Nomes de recursos completos.
• PAGE_SIZE: opcional. O número de autorizações a incluir na resposta. O valor predefinido é 100 e o valor máximo é 1000. Se o número de autorizações for superior ao tamanho da página, a resposta contém um token de paginação que pode usar para obter a página seguinte de resultados.
• NEXT_PAGE_TOKEN: opcional. O token de paginação devolvido numa resposta anterior deste método. Se especificado, a lista de autorizações testáveis começa onde a resposta anterior terminou.

Método HTTP e URL:

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

Corpo JSON do pedido:

{
  "fullResourceName": "FULL_RESOURCE_NAME"
  "pageSize": PAGE_SIZE,
  "pageToken": "NEXT_PAGE_TOKEN"
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/permissions:queryTestablePermissions"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/permissions:queryTestablePermissions" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a lista de autorizações.

Nota: as autorizações que não têm um campo customRolesSupportLevel são totalmente suportadas em funções personalizadas.

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

Obtenha os metadados da função

Antes de criar uma função personalizada, recomendamos que obtenha os metadados das funções predefinidas e personalizadas. Os metadados da função incluem o ID da função e as autorizações contidas na função. Pode ver os metadados através da Google Cloud consola ou da API IAM.

Para ver os metadados da função, use um dos métodos abaixo:

Consola

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

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

3. Selecione a caixa de verificação de uma ou mais funções para ver as autorizações da função. O painel lateral direito apresenta as autorizações contidas nas funções, se existirem.

Os ícones na coluna Tipo indicam se se trata de uma função personalizada >(ícone de "fábrica") ou de uma função predefinida >(ícone de hexágono).

Se quiser encontrar todas as funções que incluem uma autorização específica, escreva o nome da autorização na caixa Filtro na parte superior da lista de funções.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles describe para ver os metadados das funções predefinidas e das funções personalizadas.

   Para ver os metadados de uma função predefinida, execute o seguinte comando:

   gcloud iam roles describe ROLE_ID

   ROLE_ID é o ID da função. As funções predefinidas incluem o prefixo role nos respetivos IDs, por exemplo, roles/iam.roleViewer.

   O exemplo seguinte demonstra o resultado do comando describe quando executado na função predefinida 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 ver os metadados de uma função personalizada, execute um dos seguintes comandos:

   • Para ver os metadados de uma função personalizada criada ao nível da organização, execute o seguinte comando:

     gcloud iam roles describe --organization=ORGANIZATION_ID ROLE_ID

   • Para ver os metadados de uma função personalizada criada ao nível do projeto, execute o seguinte comando:

     gcloud iam roles describe --project=PROJECT_ID ROLE_ID

   Cada valor do marcador de posição é descrito abaixo:

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   • ROLE_ID é o ID da função, excluindo prefixos como projects/, organizations/ ou roles/. Por exemplo, myCompanyAdmin.

   Para mais informações, consulte a documentação de referência para gcloud iam roles describe.

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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::move(response).status();
  std::cout << "Role successfully retrieved: " << response->DebugString()
            << "\n";
}

C#

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", err)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %w", 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
}

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.GetRoleRequest;
import com.google.iam.admin.v1.Role;
import java.io.IOException;

/** Get role metadata. Specifically, printing out role permissions. */
public class GetRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String roleId = "a unique identifier (e.g. testViewer)";

    getRole(roleId);
  }

  public static void getRole(String roleId) throws IOException {
    GetRoleRequest getRoleRequest = GetRoleRequest.newBuilder().setName(roleId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role role = iamClient.getRole(getRoleRequest);
      role.getIncludedPermissionsList().forEach(permission -> System.out.println(permission));
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role


def get_role(project_id: str, role_id: str) -> Role:
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = GetRoleRequest(name=name)
    try:
        role = client.get_role(request)
        print(f"Retrieved role: {role_id}: {role}")
        return role
    except NotFound as exc:
        raise NotFound(f"Role with id [{role_id}] not found, take some actions") from exc

REST

O método roles.get obtém a definição de uma função.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• ROLE_NAME: O nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.

Método HTTP e URL:

GET https://iam.googleapis.com/v1/ROLE_NAME

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/ROLE_NAME"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/ROLE_NAME" | Select-Object -Expand Content

Explorador de APIs (navegador)

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

A resposta contém a definição da função.

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

Crie uma função personalizada

Pode criar uma função personalizada ao nível do projeto ou da organização.

Nota: não pode definir funções personalizadas ao nível da pasta. Se precisar de usar uma função personalizada numa pasta, defina a função personalizada ao nível da organização.

Uma função personalizada ao nível da organização pode incluir qualquer uma das autorizações de IAM suportadas em funções personalizadas. Uma função personalizada ao nível do projeto pode conter qualquer autorização suportada, exceto autorizações que só podem ser usadas ao nível da organização ou da pasta, como resourcemanager.organizations.get. Se tentar adicionar estas autorizações a uma função personalizada ao nível do projeto, é apresentada uma mensagem de erro:

Consola

É apresentada a seguinte mensagem de aviso: "Não aplicável a funções personalizadas ao nível do projeto". A autorização é automaticamente desmarcada na lista de autorizações incluídas, e pode continuar a criar a função.

gcloud

É devolvida a seguinte mensagem de erro: INVALID_ARGUMENT: Permission PERMISSION is not valid. A função personalizada não é criada até remover primeiro a autorização da definição da função e tentar novamente a operação.

API REST

É devolvida a seguinte mensagem de erro: Permission PERMISSION is not valid, juntamente com um código de erro HTTP 400 e um estado de INVALID_ARGUMENT. A função personalizada não é criada até remover primeiro a autorização da definição da função e tentar novamente a operação.

Cada função personalizada pode conter até 3000 autorizações. Além disso, o tamanho total máximo dos nomes do título, da descrição e das autorizações para uma função personalizada é de 64 KB. Se precisar de criar uma função personalizada maior, pode dividir as autorizações por várias funções personalizadas. Escolha títulos de funções que mostrem a relação entre as funções personalizadas, como Custom Admin (1 of 2) e Custom Admin (2 of 2).

Cada função personalizada pode ter uma fase de lançamento. A maioria das fases de lançamento são informativas e ajudam a monitorizar se cada função está pronta para utilização generalizada. Além disso, a fase de lançamento DISABLED permite-lhe desativar uma função personalizada. Para mais informações sobre as fases de lançamento, consulte o artigo Testar e implementar.

Consola

Algumas funções predefinidas contêm autorizações descontinuadas ou autorizações que, de outra forma, não são permitidas em funções personalizadas. Se tentar criar uma função personalizada com base numa destas funções predefinidas, a função personalizada omite as autorizações descontinuadas e restritas.

Para criar uma nova função personalizada de raiz:

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Use a lista pendente na parte superior da página para selecionar a organização ou o projeto no qual quer criar uma função.

3. Clique em Criar função.

4. Introduza um título, uma descrição, um ID e um estágio de lançamento da função para a função. Não é possível alterar o ID da função após a criação da função.

5. Clique em Adicionar autorizações.

6. Selecione as autorizações que quer incluir na função e clique em Adicionar autorizações. Use as listas pendentes Todos os serviços e Todos os tipos para filtrar e selecionar autorizações por serviços e tipos.

Criar uma função personalizada com base numa função predefinida existente:

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Selecione a organização ou o projeto no qual quer criar uma função.
3. Selecione as funções nas quais quer basear a nova função personalizada.
4. Clique em Criar função a partir da seleção.
5. Introduza um título, uma descrição, um ID e um estágio de lançamento da função para a função. Não é possível alterar o ID da função após a criação da função.
6. Desmarque as autorizações que quer excluir da função.
7. Clique em Adicionar autorizações para incluir autorizações.
8. Clique em Criar.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles create para criar novas funções personalizadas. Pode usar este comando de duas formas:

   • Ao fornecer um ficheiro YAML que contém a definição da função

   • Usando flags para especificar a definição de função

   Quando cria uma função personalizada, tem de especificar se se aplica ao nível da organização ou ao nível do projeto através das flags --organization=ORGANIZATION_ID ou --project=PROJECT_ID. Cada exemplo abaixo cria uma função personalizada ao nível do projeto.

   Uma função personalizada só pode conter autorizações suportadas em funções personalizadas. Se a função personalizada contiver outras autorizações, o comando falha.

   Para criar uma função personalizada com um ficheiro YAML:

   Crie um ficheiro YAML que contenha a definição da sua função personalizada. O ficheiro tem de ser estruturado da seguinte forma:

   title: ROLE_TITLE
   description: ROLE_DESCRIPTION
   stage: LAUNCH_STAGE
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_TITLE é um título intuitivo para a função, como "My Company Admin".

   • ROLE_DESCRIPTION é uma breve descrição da função, como "My custom role description".

   • LAUNCH_STAGE indica a fase de uma função no ciclo de vida de lançamento, como ALPHA, BETA ou GA.

   • PERMISSION_1 e PERMISSION_2 são autorizações a incluir na função personalizada, como iam.roles.get. Não pode usar carateres universais (*) nos nomes das autorizações.

   Guarde o ficheiro YAML e, em seguida, execute um dos seguintes comandos:

   • Para criar uma função personalizada ao nível da organização, execute o seguinte comando:

     gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

   • Para criar uma função personalizada ao 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 de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   • YAML_FILE_PATH é o caminho para a localização do ficheiro YAML que contém a definição de função personalizada.

   Exemplos

   O ficheiro YAML de exemplo seguinte demonstra como criar uma definição de função:

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

   O exemplo seguinte demonstra como criar uma função ao nível da organização usando o ficheiro YAML:

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

   Se a função tiver sido criada com êxito, o resultado do comando é semelhante ao seguinte:

   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 seguinte demonstra como criar uma função ao nível do projeto usando o ficheiro YAML:

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

   Se a função tiver sido criada com êxito, o resultado do comando é semelhante ao seguinte:

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

   Para criar uma função personalizada com flags:

   Execute um dos seguintes comandos:

   • Para criar uma função personalizada ao 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 uma função personalizada ao 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 de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   • ROLE_TITLE é um título intuitivo para a função, como "My Company Admin".

   • ROLE_DESCRIPTION é uma breve descrição da função, como "My custom role description.".

   • PERMISSIONS_LIST contém uma lista separada por vírgulas das autorizações que quer incluir na função personalizada. Por exemplo: iam.roles.get,iam.roles.list. Não pode usar carateres universais (*) em nomes de autorizações.

   • LAUNCH_STAGE indica a fase de uma função no ciclo de vida de lançamento, como ALPHA, BETA ou GA.

   Exemplos

   O exemplo seguinte demonstra como criar uma função ao nível da organização através de flags:

   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 a função tiver sido criada com êxito, o resultado do comando é semelhante ao seguinte:

   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 seguinte demonstra como criar uma função ao nível do projeto usando flags:

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

   Se a função tiver sido criada com êxito, o resultado do comando é semelhante ao seguinte:

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

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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::move(response).status();
  std::cout << "Role successfully created: " << response->DebugString()
            << "\n";
}

C#

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.CreateRoleRequest;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import java.io.IOException;
import java.util.Arrays;

/** Create role. */
public class CreateRole {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String title = "a title for your role (e.g. IAM Role Viewer)";
    String description = "a description of the role";
    Iterable<String> includedPermissions =
        Arrays.asList("roles/iam.roleViewer", "roles/logging.viewer");

    createRole(projectId, title, description, includedPermissions, roleId);
  }

  public static void createRole(
      String projectId,
      String title,
      String description,
      Iterable<String> includedPermissions,
      String roleId)
      throws IOException {
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setTitle(title)
            .setDescription(description)
            .addAllIncludedPermissions(includedPermissions)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.BETA);
    CreateRoleRequest createRoleRequest =
        CreateRoleRequest.newBuilder()
            .setParent("projects/" + projectId)
            .setRoleId(roleId)
            .setRole(roleBuilder)
            .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.createRole(createRoleRequest);
      System.out.println("Created role: " + result.getName());
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from typing import List, Optional

from google.api_core.exceptions import AlreadyExists, FailedPrecondition
from google.cloud.iam_admin_v1 import CreateRoleRequest, IAMClient, Role


def create_role(
    project_id: str, role_id: str, permissions: List[str], title: Optional[str] = None
) -> Role:
    """Creates iam role with given parameters.

    Args:
        project_id: GCP project id
        role_id: id of GCP iam role
        permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"]
        title: title for iam role. role_id will be used in case of None

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()

    parent = f"projects/{project_id}"

    request = CreateRoleRequest(
        parent=parent,
        role_id=role_id,
        role=Role(title=title, included_permissions=permissions),
    )
    try:
        role = client.create_role(request)
        print(f"Created iam role: {role_id}: {role}")
        return role
    except AlreadyExists:
        print(f"Role with id [{role_id}] already exists, take some actions")
    except FailedPrecondition:
        print(
            f"Role with id [{role_id}] already exists and in deleted state, take some actions"
        )

REST

O método roles.create cria uma função personalizada num projeto ou numa organização.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• RESOURCE_TYPE: o tipo de recurso cujas funções personalizadas quer gerir. Use o valor projects ou organizations.
• RESOURCE_ID: o ID do projeto ou o ID da organização cujas funções personalizadas quer gerir. Os IDs dos projetos são strings alfanuméricas, como my-project. Os IDs das organizações são numéricos, como 123456789012.
• ROLE_ID: o nome da função, como myCompanyAdmin.
• ROLE_TITLE: o título legível por humanos da função. Por exemplo, My Company Admin.
• ROLE_DESCRIPTION: uma descrição da função. Por exemplo, "The company admin role allows company admins to access important resources".

• PERMISSION_1 e PERMISSION_2: as autorizações que quer incluir na função. Por exemplo, storage.objects.update. Não pode usar carateres universais (*) nos nomes das autorizações.

  Uma função personalizada só pode conter autorizações suportadas em funções personalizadas. Se a função personalizada contiver outras autorizações, o pedido falha.

• LAUNCH_STAGE: a fase de lançamento atual da função. Este 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 do pedido:

{
  "roleId": "ROLE_ID",
  "role": {
    "title": "ROLE_TITLE",
    "description": "ROLE_DESCRIPTION",
    "includedPermissions": [
      "PERMISSION_1",
      "PERMISSION_2"
    ],
    "stage": "LAUNCH_STAGE"
  }
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a função que 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="
}

Edite uma função personalizada existente

Um padrão comum para atualizar os metadados de um recurso, como uma função personalizada, é o padrão ler-modificar-gravar. Com este padrão, lê o estado atual da função, atualiza os dados localmente e, em seguida, envia os dados modificados para escrita.

O padrão de leitura-modificação-gravação pode causar um conflito se dois ou mais processos independentes tentarem a sequência em simultâneo. Por exemplo, se dois proprietários de um projeto tentarem fazer alterações conflituosas a uma função ao mesmo tempo, algumas alterações podem falhar. A IAM resolve este problema através de uma propriedade etag nas funções personalizadas. Esta propriedade é usada para verificar se a função personalizada foi alterada desde o último pedido. Quando faz um pedido ao IAM com um valor de etag, o IAM compara o valor de etag no pedido com o valor de etag existente associado à função personalizada. Escreve a alteração apenas se os valores etag corresponderem.

Quando atualiza uma função, primeiro, recebe a função através de roles.get(), atualiza a função e, de seguida, escreve a função atualizada através de roles.patch(). Use o valor etag ao definir a função apenas se a função correspondente em roles.get() contiver um valor etag.

Nota: quando modifica uma função personalizada adicionando ou removendo qualquer uma das seguintes autorizações: resourcemanager.organizations.get, resourcemanager.folders.get e resourcemanager.projects.get, a alteração à função personalizada pode demorar até 24 horas a entrar em vigor para as APIs organizations.search e folders.search Cloud Resource Manager. A API projects.list também está sujeita a este atraso para chamadas API que não fornecem um filtro que especifique um tipo principal e um ID. Este atraso ocorre porque estas autorizações envolvem a funcionalidade de pesquisa e pode demorar até 24 horas entre as reconstruções do índice de pesquisa.

Consola

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Use a lista pendente na parte superior da página para selecionar o projeto ou a organização que contém a função que quer editar.

3. Clique numa função personalizada.

4. Clique em Editar função.

5. Para atualizar os metadados da função, edite o Título, a Descrição ou a Fase de lançamento da função.

6. Para atualizar as autorizações da função, faça o seguinte:

   1. Clique em Adicionar autorizações para adicionar novas autorizações à função.
   2. Desmarque as autorizações para as remover da função.

7. Clique em Atualizar para guardar a função editada.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles update para atualizar funções personalizadas. Pode usar este comando de duas formas:

   • Ao fornecer um ficheiro YAML que contenha a definição de função atualizada

   • Usando flags para especificar a definição de função atualizada

   Quando atualiza uma função personalizada, tem de especificar se se aplica ao nível da organização ou ao nível do projeto através das flags --organization=ORGANIZATION_ID ou --project=PROJECT_ID. Cada exemplo abaixo cria uma função personalizada ao nível do projeto.

   Para atualizar uma função personalizada através de um ficheiro YAML:

   Obtenha a definição atual da função executando um dos seguintes comandos:

   • Para obter a definição de função de uma função personalizada ao nível da organização, execute o seguinte comando:

     gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID

   • Para obter a definição de função de uma função personalizada ao nível do projeto, execute o seguinte comando:

     gcloud iam roles describe ROLE_ID --project=PROJECT_ID

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_ID é o nome da função a atualizar, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   O comando describe devolve a definição da função e inclui um valor etag que identifica exclusivamente a versão atual da função. O valor etag deve ser facultado na definição de função atualizada para garantir que as alterações de funções simultâneas não são substituídas.

   O comando describe devolve o seguinte resultado:

   description: ROLE_DESCRIPTION
   etag: ETAG
   includedPermissions:
   - PERMISSION_1
   - PERMISSION_2
   name: ROLE_NAME
   stage: LAUNCH_STAGE
   title: ROLE_TITLE

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_DESCRIPTION é uma breve descrição da função, como "My custom role description".

   • ETAG é o identificador exclusivo da versão atual da função, como BwVkBkbfr70=.

   • PERMISSION_1 e PERMISSION_2 são autorizações a incluir na função personalizada, como iam.roles.get. Não pode usar carateres universais (*) nos nomes das autorizações.

   • ROLE_NAME é o nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.

   • LAUNCH_STAGE indica a fase de uma função no ciclo de vida de lançamento, como ALPHA, BETA ou GA.

   • ROLE_TITLE é um título amigável para a função, como "My Company Admin".

   Para atualizar a função, inclua a definição da função gerada num ficheiro YAML ou atualize o ficheiro YAML original com o valor etag gerado.

   Considere o seguinte ficheiro YAML de exemplo, que contém o resultado do comando describe para uma função ao nível do projeto e adiciona duas autorizaçõ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/roles/myCompanyAdmin
   stage: ALPHA
   title: My Company Admin

   Guarde o ficheiro YAML e, em seguida, execute um dos seguintes comandos:

   • Para atualizar uma função ao nível da organização, execute o seguinte comando:

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --file=YAML_FILE_PATH

   • Para atualizar uma função ao 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 de posição é descrito abaixo:

   • ROLE_ID é o nome da função a atualizar, 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 para a localização do ficheiro YAML que contém a definição de função personalizada atualizada.

   Exemplos

   O exemplo seguinte demonstra como atualizar uma função ao nível da organização através de um ficheiro YAML:

   gcloud iam roles update ROLE_ID --organization=ORGANIZATION_ID \
       --file=YAML_FILE_PATH

   • Para atualizar uma função ao 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 de posição é descrito abaixo:

   • ROLE_ID é o nome da função a atualizar, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   • YAML_FILE_PATH é o caminho para a localização do seu ficheiro YAML que contém a definição de função personalizada atualizada.

   Exemplos

   O exemplo seguinte demonstra como atualizar uma função ao nível da organização através de um ficheiro YAML:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

   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 seguinte demonstra como atualizar uma função ao nível do projeto através de um ficheiro YAML:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

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

   Para atualizar uma função personalizada através de flags:

   Cada parte de uma definição de função pode ser atualizada através de uma flag correspondente. Consulte o tópico gcloud iam roles update para ver uma lista de todas as flags possíveis.

   Pode usar as seguintes flags para adicionar ou remover autorizações:

   • --add-permissions=PERMISSIONS: adiciona uma ou mais autorizações separadas por vírgulas à função. Não pode usar carateres universais (*) nos nomes das autorizações.

   • --remove-permissions=PERMISSIONS: remove uma ou mais autorizações separadas por vírgulas da função. Não pode usar carateres universais (*) nos nomes das autorizações.

   Em alternativa, pode simplesmente especificar as novas autorizações através da flag --permissions=PERMISSIONS e fornecer uma lista de autorizações separada por vírgulas para substituir a lista de autorizações existente.

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

   • Para atualizar uma função ao 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 uma função ao 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 de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   • ROLE_TITLE é um título amigável para a função, como "My Company Admin".

   • ROLE_DESCRIPTION é uma breve descrição da função, como "My custom role description.".

   • LAUNCH_STAGE indica a fase de uma função no ciclo de vida de lançamento, como ALPHA, BETA ou GA.

   Exemplos

   O exemplo seguinte demonstra como adicionar autorizações a uma função ao nível da organização através de flags:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

   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 seguinte demonstra como adicionar autorizações a uma função ao nível do projeto através de flags:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

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

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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::move(response).status();
  std::cout << "Role successfully updated: " << response->DebugString()
            << "\n";
}

C#

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", err)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.Role.RoleLaunchStage;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

/** Edit role metadata. Specifically, update description and launch stage. */
public class EditRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";
    String description = "a new description of the role";

    editRole(projectId, roleId, description);
  }

  public static void editRole(String projectId, String roleId, String description)
      throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role.Builder roleBuilder =
        Role.newBuilder()
            .setName(roleName)
            .setDescription(description)
            // See launch stage enums at
            // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage
            .setStage(RoleLaunchStage.GA);
    FieldMask fieldMask = FieldMask.newBuilder().addPaths("description").addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
        UpdateRoleRequest.newBuilder()
            .setName(roleName)
            .setRole(roleBuilder)
            .setUpdateMask(fieldMask)
            .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.updateRole(updateRoleRequest);
      System.out.println("Edited role:\n" + result);
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import IAMClient, Role, UpdateRoleRequest

from snippets.get_role import get_role


def edit_role(role: Role) -> Role:
    """Edits an existing IAM role in a GCP project.

    Args:
        role: google.cloud.iam_admin_v1.Role object to be updated

    Returns: Updated google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    request = UpdateRoleRequest(name=role.name, role=role)
    try:
        role = client.update_role(request)
        print(f"Edited role: {role.name}: {role}")
        return role
    except NotFound:
        print(f"Role [{role.name}] not found, take some actions")

REST

O método roles.patch atualiza uma função personalizada num projeto ou numa organização.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

Obrigatório:

• RESOURCE_TYPE: o tipo de recurso cujas funções personalizadas quer gerir. Use o valor projects ou organizations.
• RESOURCE_ID: o ID do projeto ou o ID da organização cujas funções personalizadas quer gerir. Os IDs dos projetos são strings alfanuméricas, como my-project. Os IDs das organizações são numéricos, como 123456789012.
• ROLE_NAME: O nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.

Recomendado:

• ETAG: um identificador de uma versão da função. Inclua este campo para evitar a substituição de outras alterações de funções.

Opcional (defina um ou mais dos seguintes valores):

• ROLE_TITLE: o título legível por humanos da função. Por exemplo, My Company Admin.
• ROLE_DESCRIPTION: uma descrição da função. Por exemplo, "The company admin role allows company admins to access important resources".
• PERMISSION_1 e PERMISSION_2: as autorizações que quer incluir na função. Por exemplo, storage.objects.update. Não pode usar carateres universais (*) nos nomes das autorizações.
• LAUNCH_STAGE: a fase de lançamento atual da função. Este 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 do pedido:

{
  "roleId": "ROLE_NAME",
  "title": "ROLE_TITLE",
  "description": "ROLE_DESCRIPTION",
  "includedPermissions": [
    "PERMISSION_1",
    "PERMISSION_2"
  ],
  "stage": "LAUNCH-STAGE",
  "etag": "ETAG"
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém uma definição de função abreviada que inclui o nome da função, os campos que atualizou e um etag que identifica a versão atual da função.

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

Desative uma função personalizada

Pode desativar uma função personalizada alterando a respetiva fase de lançamento para DISABLED. Quando uma função é desativada, todas as associações de funções relacionadas com a função são inativadas, o que significa que a concessão da função a um utilizador não tem qualquer efeito.

Consola

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Clique na lista pendente "Selecionar um projeto" na parte superior da página.

3. Selecione a sua organização ou projeto.

4. Selecione uma função personalizada e clique em Desativar.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles update para desativar uma função personalizada definindo a respetiva fase de lançamento como DISABLED.

   Conforme descrito no separador gcloud da secção Editar uma função personalizada existente, pode atualizar uma função personalizada existente das seguintes duas formas:

   • Ao fornecer um ficheiro YAML que contenha a definição de função atualizada

   • Usando flags para especificar a definição de função atualizada

   A forma mais fácil de desativar uma função personalizada existente é usar a flag --stage e defini-la como DISABLED. Execute um dos seguintes comandos:

   • Para desativar uma função ao nível da organização, execute o seguinte comando:

     gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
         --stage=DISABLED

   • Para desativar uma função ao nível do projeto, execute o seguinte comando:

     gcloud iam roles update ROLE_ID --project=PROJECT_ID \
         --stage=DISABLED

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   Exemplos

   O exemplo seguinte demonstra como desativar uma função ao nível da organização:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

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

   O exemplo seguinte demonstra como desativar uma função ao nível do projeto:

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

   Se a função tiver sido atualizada com êxito, o resultado do comando é semelhante ao seguinte:

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

C++

Atualize o campo stage da função para DISABLED.

C#

Atualize o campo stage da função para DISABLED.

Go

Atualize o campo stage da função para DISABLED.

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UpdateRoleRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class DisableRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "testRole";

    Role role = disableRole(projectId, roleId);
    System.out.println("Role name: " + role.getName());
    System.out.println("Role stage: " + role.getStage());
  }

  public static Role disableRole(String projectId, String roleId)
          throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    Role role = Role.newBuilder()
                    .setName(roleName)
                    .setStage(Role.RoleLaunchStage.DISABLED)
                    .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("stage").build();
    UpdateRoleRequest updateRoleRequest =
              UpdateRoleRequest.newBuilder()
                      .setName(roleName)
                      .setRole(role)
                      .setUpdateMask(fieldMask)
                      .build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      return iamClient.updateRole(updateRoleRequest);
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.api_core.exceptions import NotFound
from google.cloud.iam_admin_v1 import GetRoleRequest, IAMClient, Role, UpdateRoleRequest


def disable_role(project_id: str, role_id: str) -> Role:
    """Disables an IAM role in a GCP project.

    Args:
        project_id: GCP project ID
        role_id: ID of GCP IAM role

    Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    get_request = GetRoleRequest(name=name)
    try:
        role = client.get_role(get_request)
        role.stage = Role.RoleLaunchStage.DISABLED
        update_request = UpdateRoleRequest(name=role.name, role=role)
        client.update_role(update_request)
        print(f"Disabled role: {role_id}: {role}")
        return role
    except NotFound as exc:
        raise NotFound(f'Role with id [{role_id}] not found, take some actions') from exc

REST

O método roles.patch permite-lhe alterar a fase de lançamento de uma função personalizada para DISABLED, o que desativa a função.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• RESOURCE_TYPE: o tipo de recurso cujas funções personalizadas quer gerir. Use o valor projects ou organizations.
• RESOURCE_ID: o ID do projeto ou o ID da organização cujas funções personalizadas quer gerir. Os IDs dos projetos são strings alfanuméricas, como my-project. Os IDs das organizações são numéricos, como 123456789012.
• ROLE_NAME: O nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.
• ETAG: um identificador de uma versão da função. Inclua este campo para evitar a substituição de outras alterações de funções.

Método HTTP e URL:

PATCH https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles

Corpo JSON do pedido:

{
  "roleId": "ROLE_NAME",
  "stage": DISABLED,
  "etag": "ETAG"
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Deve receber uma resposta JSON semelhante à seguinte:

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

Liste funções

Pode listar todas as funções personalizadas criadas no seu projeto ou organização.

Consola

Na Google Cloud consola, aceda à página Funções.

Aceda à página Funções

Todas as funções personalizadas para a organização ou o projeto que selecionou são apresentadas na página.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles list para listar as funções personalizadas e as funções predefinidas de um projeto ou uma organização:

   • Para apresentar uma lista de funções personalizadas ao nível da organização, execute o seguinte comando:

     gcloud iam roles list --organization=ORGANIZATION_ID

   • Para apresentar uma lista de funções personalizadas ao nível do projeto, execute o seguinte comando:

     gcloud iam roles list --project=PROJECT_ID

   Cada valor do marcador de posição é descrito abaixo:

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   Para listar as funções eliminadas, também pode especificar a flag --show-deleted.

   Execute o seguinte comando para listar as funções predefinidas:

   gcloud iam roles list

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& project) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  google::iam::admin::v1::ListRolesRequest request;
  request.set_parent(project);
  for (auto& role : client.ListRoles(request)) {
    if (!role) throw std::move(role).status();
    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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API C# IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", err)
	}

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

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.cloud.iam.admin.v1.IAMClient.ListRolesPagedResponse;
import com.google.iam.admin.v1.ListRolesRequest;
import java.io.IOException;

/** List roles in a project. */
public class ListRoles {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variable before running the sample.
    String projectId = "your-project-id";

    listRoles(projectId);
  }

  public static void listRoles(String projectId) throws IOException {
    ListRolesRequest listRolesRequest =
        ListRolesRequest.newBuilder().setParent("projects/" + projectId).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      ListRolesPagedResponse listRolesResponse = iamClient.listRoles(listRolesRequest);
      listRolesResponse.iterateAll().forEach(role -> System.out.println(role));
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.cloud.iam_admin_v1 import IAMClient, ListRolesRequest, RoleView
from google.cloud.iam_admin_v1.services.iam.pagers import ListRolesPager


def list_roles(
    project_id: str, show_deleted: bool = True, role_view: RoleView = RoleView.BASIC
) -> ListRolesPager:
    """Lists IAM roles in a GCP project.

    Args:
        project_id: GCP project ID
        show_deleted: Whether to include deleted roles in the results
        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)

    Returns: A pager for traversing through the roles
    """

    client = IAMClient()
    parent = f"projects/{project_id}"
    request = ListRolesRequest(parent=parent, show_deleted=show_deleted, view=role_view)
    roles = client.list_roles(request)
    for page in roles.pages:
        for role in page.roles:
            print(role)
    print("Listed all iam roles")
    return roles

REST

O método roles.list lista todas as funções personalizadas num projeto ou numa organização.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• RESOURCE_TYPE: o tipo de recurso cujas funções personalizadas quer gerir. Use o valor projects ou organizations.
• RESOURCE_ID: o ID do projeto ou o ID da organização cujas funções personalizadas quer gerir. Os IDs dos projetos são strings alfanuméricas, como my-project. Os IDs das organizações são numéricos, como 123456789012.
• ROLE_VIEW: opcional. As informações a incluir para as funções devolvidas. Para incluir as autorizações das funções, defina este campo como FULL. Para excluir as autorizações das funções, defina este campo como BASIC. O valor predefinido é BASIC.
• PAGE_SIZE: opcional. O número de funções a incluir na resposta. O valor predefinido é 300 e o valor máximo é 1000. Se o número de funções for superior ao tamanho da página, a resposta contém um token de paginação que pode usar para obter a página seguinte de resultados.
• NEXT_PAGE_TOKEN: opcional. O token de paginação devolvido numa resposta anterior deste método. Se for especificado, a lista de funções começa onde o pedido anterior terminou.

Nota: para listar todas as funções de IAM predefinidas, omita os campos RESOURCE_TYPE e RESOURCE_ID. Por exemplo: GET https://iam.googleapis.com/v1/roles.

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 o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

Explorador de APIs (navegador)

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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="
    }
  ]
}

Elimine uma função personalizada

Pode eliminar qualquer função personalizada no seu projeto ou organização.

Importante: as funções eliminadas são suspensas e não podem ser usadas para criar novas associações de funções em políticas de autorização. As associações de funções existentes que incluem a função eliminada não têm efeito.

Consola

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Selecione a função que quer eliminar e clique em Eliminar na parte superior da página.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles delete para eliminar uma função personalizada:

   • Para eliminar uma função personalizada ao nível da organização, execute o seguinte comando:

     gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID

   • Para eliminar uma função personalizada ao nível do projeto, execute o seguinte comando:

     gcloud iam roles delete ROLE_ID --project=PROJECT_ID

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   A função não é incluída em gcloud iam roles list, a menos que a flag --show-deleted seja incluída. As funções eliminadas são indicadas pelo bloco deleted: true numa resposta list, como:

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

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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::move(response).status();
  std::cout << "Role successfully deleted: " << response->DebugString()
            << "\n";
}

C#

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", err)
	}

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

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.DeleteRoleRequest;
import java.io.IOException;

/** Delete role. */
public class DeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to an existing role.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    deleteRole(projectId, roleId);
  }

  public static void deleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    DeleteRoleRequest deleteRoleRequest = DeleteRoleRequest.newBuilder().setName(roleName).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      iamClient.deleteRole(deleteRoleRequest);
      System.out.println("Role deleted.");
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)
def delete_role(project_id: str, role_id: str) -> Role:
    """Deletes iam role in GCP project. Can be undeleted later.
    Args:
        project_id: GCP project id
        role_id: id of GCP iam role

    Returns: google.cloud.iam_admin_v1.Role object
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = DeleteRoleRequest(name=name)
    try:
        role = client.delete_role(request)
        print(f"Deleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] already deleted, take some actions)", err)

REST

O método roles.delete elimina uma função personalizada num projeto ou numa organização.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• ROLE_NAME: O nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.

Método HTTP e URL:

DELETE https://iam.googleapis.com/v1/ROLE_NAME

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/ROLE_NAME"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/ROLE_NAME" | Select-Object -Expand Content

Explorador de APIs (navegador)

Abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Preencha todos os campos obrigatórios e clique em Executar.

A resposta contém a definição da função que foi eliminada.

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

Quando uma função é eliminada, todas as associações de funções que fazem referência à função permanecem nas suas políticas de autorização, mas não têm efeito. Pode anular a eliminação de uma função no prazo de 7 dias. Durante este período de 7 dias, a Google Cloud consola mostra que a função foi eliminada. Também pode listar funções eliminadas através de programação, mas estas são omitidas por predefinição.

A eliminação permanente da função está agendada para 7 a 14 dias após o pedido inicial de eliminação da função. Neste momento, a função deixa de contar para o limite de 300 funções personalizadas por organização ou 300 funções personalizadas por projeto.

Nota: as funções personalizadas criadas num projeto não contam para o limite de funções personalizadas da sua organização.

Depois de a função ser agendada para eliminação permanente, Google Cloud inicia o processo para eliminar permanentemente a função. Este processo demora 30 dias. Durante este período de 30 dias, a função e todas as associações relacionadas são removidas permanentemente, e não pode criar uma nova função com o mesmo ID de função.

Após a eliminação permanente da função, até 44 dias após o pedido de eliminação inicial, pode criar uma nova função com o mesmo ID da função.

Anule a eliminação de uma função personalizada

A anulação da eliminação de uma função devolve-a ao estado anterior.

Só é possível anular a eliminação de funções no prazo de 7 dias. Após 7 dias, Google Cloud inicia o processo para eliminar permanentemente a função. Este processo de eliminação permanente pode demorar até 30 dias. Depois de uma função ser eliminada permanentemente, todas as associações de funções que fazem referência à função são removidas, e pode criar uma nova função com o mesmo ID da função.

Consola

1. Na Google Cloud consola, aceda à página Funções.

   Aceda à página Funções

2. Localize a função que quer restaurar, clique no ícone Mais no final da linha e clique em Restaurar.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud iam roles undelete para anular a eliminação de uma função personalizada:

   • Para anular a eliminação de uma função personalizada ao nível da organização, execute o seguinte comando:

     gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID

   • Para anular a eliminação de uma função personalizada ao nível do projeto, execute o seguinte comando:

     gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

   Cada valor do marcador de posição é descrito abaixo:

   • ROLE_ID é o nome da função, como myCompanyAdmin.

   • ORGANIZATION_ID é o ID numérico da organização, como 123456789012.

   • PROJECT_ID é o nome do projeto, como my-project.

   Exemplos

   O exemplo seguinte demonstra como anular a eliminação de uma função personalizada ao nível da organização:

   gcloud iam roles undelete myCompanyAdmin --organization=123456789012

   Se a função tiver sido anulada com êxito, o resultado do comando é semelhante ao seguinte:

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

   O exemplo seguinte demonstra como anular a eliminação de uma função personalizada ao nível do projeto:

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

   Se a função tiver sido anulada com êxito, o resultado do comando é semelhante ao seguinte:

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

C++

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

namespace iam = ::google::cloud::iam_admin_v1;
[](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::move(response).status();
  std::cout << "Role successfully undeleted: " << response->DebugString()
            << "\n";
}

C#

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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 cliente para a IAM, consulte o artigo Bibliotecas cliente da IAM. Para mais informações, consulte a documentação de referência da API Go IAM.

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

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: %w", 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: %w", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

Java

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

import com.google.cloud.iam.admin.v1.IAMClient;
import com.google.iam.admin.v1.Role;
import com.google.iam.admin.v1.UndeleteRoleRequest;
import java.io.IOException;

/**
 * Undelete a role to return it to its previous state. Undeleting only works on roles that were
 * deleted in the past 7 days.
 */
public class UndeleteRole {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace the variables before running the sample.
    // Role ID must point to a role that was deleted in the past 7 days.
    String projectId = "your-project-id";
    String roleId = "a unique identifier (e.g. testViewer)";

    undeleteRole(projectId, roleId);
  }

  public static void undeleteRole(String projectId, String roleId) throws IOException {
    String roleName = "projects/" + projectId + "/roles/" + roleId;
    UndeleteRoleRequest undeleteRoleRequest =
        UndeleteRoleRequest.newBuilder().setName(roleName).build();

    // Initialize client for sending requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (IAMClient iamClient = IAMClient.create()) {
      Role result = iamClient.undeleteRole(undeleteRoleRequest);
      System.out.println("Undeleted role:\n" + result);
    }
  }
}

Python

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

Para se autenticar no IAM, configure as Credenciais padrão da aplicação. Para mais informações, consulte a secção Antes de começar.

from google.api_core.exceptions import FailedPrecondition, NotFound
from google.cloud.iam_admin_v1 import (
    DeleteRoleRequest,
    IAMClient,
    Role,
    UndeleteRoleRequest,
)
def undelete_role(project_id: str, role_id: str) -> Role:
    """Undeleted deleted iam role in GCP project.

    Args:
        project_id: GCP project id
        role_id: id of GCP iam role
    """
    client = IAMClient()
    name = f"projects/{project_id}/roles/{role_id}"
    request = UndeleteRoleRequest(name=name)
    try:
        role = client.undelete_role(request)
        print(f"Undeleted role: {role_id}: {role}")
        return role
    except NotFound:
        print(f"Role with id [{role_id}] not found, take some actions")
    except FailedPrecondition as err:
        print(f"Role with id [{role_id}] is not deleted, take some actions)", err)

REST

O método roles.undelete anula a eliminação de uma função personalizada num projeto ou numa organização.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

• ROLE_NAME: O nome completo da função, incluindo todos os prefixos organizations/, projects/ ou roles/. Por exemplo, organizations/123456789012/roles/myCompanyAdmin.
• ETAG: um identificador de uma versão da função. Inclua este campo para evitar a substituição de outras alterações de funções.

Método HTTP e URL:

POST https://iam.googleapis.com/v1/ROLE_NAME:undelete

Corpo JSON do pedido:

{
  "etag": "ETAG"
}

Para enviar o seu pedido, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/ROLE_NAME:undelete"

PowerShell (Windows)

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/ROLE_NAME:undelete" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

A resposta contém a definição da função que foi restaurada.

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

O que se segue?

• Saiba como conceder funções a principais.
• Explore como pode usar as recomendações de funções para restringir as autorizações dos principais.
• Saiba mais sobre as concessões de funções condicionais, que concedem uma função apenas se forem cumpridas condições específicas.