Crea y administra funciones personalizadas

En esta página, se describe cómo crear y administrar una función personalizada.

Antes de comenzar

  • Lee Comprende las funciones personalizadas de IAM, que contiene información sobre los permisos necesarios para crear funciones personalizadas y prácticas recomendadas.
  • Si usas la utilidad de la línea de comandos de gcloud, asegúrate de usar la versión 188.0.0 o posterior. Para actualizar gcloud a la versión 188.0.0, ejecuta el siguiente comando: gcloud components update --version 188.0.0

Mira los permisos disponibles para un recurso

Antes de crear una función personalizada, es posible que desees saber qué permisos se pueden aplicar a un recurso. Puedes obtener todos los permisos que se pueden aplicar a un recurso y los recursos inferiores en esa jerarquía mediante la herramienta de línea de comandos de gcloud, Cloud Console o la API de IAM. Por ejemplo, puedes obtener todos los permisos que puedes aplicar en una organización y en los proyectos de esa organización.

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona tu proyecto en el menú desplegable de la parte superior de la página.
  3. Selecciona la casilla de verificación de la función de administrador de un recurso para ver todos los permisos que puedes aplicar a ese recurso. Por ejemplo, cuando seleccionas la función de administrador de instancias de procesamiento, el panel lateral derecho muestra todos los permisos que puedes aplicar en una instancia de Compute Engine.

Comando de gcloud

Usa el comando gcloud iam list-testable-permissions para obtener una lista de los permisos que se pueden aplicar a un recurso de destino. Los permisos que se muestran son los que se pueden usar para crear una función personalizada en este recurso y en cualquier otro inferior en la jerarquía.

En el siguiente ejemplo, se muestra cómo enumerar los permisos comprobables para un recurso de proyecto:

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

[PROJECT-ID] es el ID del proyecto en forma de un nombre de recurso completo: //cloudresourcemanager.googleapis.com/projects/PROJECT-ID, como //cloudresourcemanager.googleapis.com/projects/my-project-id.

El comando list-testable-permissions puede mostrar cientos de resultados. Para limitar la cantidad, también puedes especificar una expresión de filtros. A continuación, se muestra un ejemplo truncado de los posibles resultados:

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

Ten en cuenta que cada permiso indica si se admite en una función personalizada. Para obtener una lista completa de los permisos compatibles y no compatibles, consulta [Compatibilidad de permisos en funciones personalizadas](/iam/docs/custom-roles-permissions-support).

API de REST

QueryTestablePermissions muestra todos los permisos que se pueden aplicar a un recurso. Los permisos que se muestran son los que se pueden usar para crear una función personalizada en este recurso y en cualquier otro inferior en la jerarquía. La única entrada obligatoria para esta solicitud es el nombre completo del recurso, como //cloudresourcemanager.googleapis.com/projects/my-project`.

De forma opcional, el emisor puede proporcionar asistencia para la paginación si el recurso tiene una lista larga de permisos.

Ejemplo

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

Códigos de error

Código de error Mensaje de estado
INVALID_ARGUMENT debe estar entre 0 y 100
INVALID_ARGUMENT Codificación de token de paginación no válida
INVALID_ARGUMENT Token de paginación no válido
INVALID_ARGUMENT El token de paginación no es para el contenedor especificado
INVALID_ARGUMENT Punto de partida no válido en el token de paginación
INVALID_ARGUMENT Cookie de token de paginación no válida
INVALID_ARGUMENT Token de paginación vencido
INVALID_ARGUMENT {full_resource_name} debe estar especificado.
INVALID_ARGUMENT {full_resource_name} no coincide con //[a-z0-9.-]/.a-z0-9.-]/.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

Obtén los metadatos de la función

Antes de crear una función personalizada, es posible que desees obtener los metadatos para las funciones predefinidas y personalizadas. Los metadatos de función incluyen el ID de función y los permisos contenidos en la función. Puedes ver los metadatos con Google Cloud Platform Console o la API de IAM.

Para ver los metadatos de función, usa uno de los siguientes métodos:

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona tu organización o proyecto de la lista desplegable en la parte superior de la página.
  3. Selecciona la casilla de verificación de una o más funciones para ver los permisos de la función. En el panel lateral derecho, se muestran los permisos que contienen las funciones, si los hay.

Los íconos junto a la función indican si es una función personalizada (ícono de “fábrica”) o una función predefinida (ícono de hexágono).

Íconos de funciones

Si deseas buscar todas las funciones que incluyen un permiso específico, escribe el nombre del permiso en el cuadro Filtro que está en la parte superior de la lista de funciones.

Comando de gcloud

Usa el comando gcloud iam roles describe para ver los metadatos de las funciones predefinidas y personalizadas.

Para ver los metadatos de una función predefinida, ejecuta el siguiente comando de gcloud:

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] es el nombre de la función, como roles/viewer.

En el siguiente ejemplo, se demuestra el resultado del comando describe cuando se ejecuta en la función 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 los metadatos de una función personalizada, primero determina si esta se creó a nivel de la organización o del proyecto. Si la función personalizada se creó a nivel de la organización, ejecuta el siguiente comando de gcloud:

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

[ORGANIZATION-ID] es el ID de la organización en la forma: 1234567. [ROLE-NAME] es el nombre de la función personalizada, como myCustomRole.

Para ver los metadatos de una función personalizada a nivel del proyecto, ejecuta el siguiente comando de gcloud:

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

[PROJECT-ID] es el ID del proyecto, como my-project-id. [ROLE-NAME] es el nombre de la función personalizada, como myCustomRole.

Si quieres obtener más información, consulta la documentación de referencia para gcloud iam roles describe.

API de REST

Si conoces el nombre de la función que deseas ver, usa el método roles.get para obtener una función personalizada. Si no conoces el nombre de la función, usa el método roles.list para enumerar todas las funciones personalizadas en una organización o en un proyecto.

Para llamar al método GetRole(),, configura el siguiente campo en la GetRoleRequest, como se muestra a continuación:

  • Nombre de la función, como roles/{ROLE-NAME} o organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}.

Para llamar a ListRoles(), configura el siguiente campo en la ListRolesRequest, como se muestra a continuación:

  • El superior para el que deseas obtener todas las funciones personalizadas, como organizations/{ORGANIZATION-ID} o projects/{PROJECT-ID}.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para obtener la función en {path}.
NOT_FOUND No se encontró la función llamada {role}.
INVALID_ARGUMENT El nombre de la función debe tener el formato roles/{role} o organizations/{organization-id}/roles/{role}.
PERMISSION_DENIED No tienes permiso para enumerar funciones en {path}.
INVALID_ARGUMENT La {path} superior no es válida. El superior debe tener el formato organizations/{organization-id} o estar vacío.
INVALID_ARGUMENT La vista de funciones no es válida.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

Crea una función personalizada

Para crear una función personalizada, el emisor debe tener el permiso iam.roles.create. De forma predeterminada, el propietario de un proyecto o una organización tiene este permiso y puede crear y administrar funciones personalizadas.

A los usuarios que no son propietarios, incluidos los administradores de la organización, se les debe asignar la función de administrador de funciones organizativas o la función de administrador de funciones IAM.

Console

Para crear una nueva función personalizada desde cero, sigue estos pasos:

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Haz clic en Crear función.
  4. Ingresa un Nombre, un Título y una Descripción para la función.
  5. Haz clic en Agregar permisos.
  6. Selecciona los permisos que desees incluir en la función y haz clic en Agregar permisos. Usa los menús desplegables Todos los servicios y Todos los tipos para filtrar y seleccionar permisos por servicios y tipos.

Crea una función personalizada basada en una función predefinida existente:

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Selecciona las funciones en las que deseas basar la nueva función personalizada.
  4. Haz clic en Crear función de selección.
  5. Ingresa un Nombre, un Título y una Descripción para la función.
  6. Desmarca los permisos que deseas excluir de la función.
  7. Haz clic en Agregar permisos para incluir cualquier permiso.
  8. Haz clic en Crear.

Comando de gcloud

Usa el comando gcloud iam roles create para crear nuevas funciones personalizadas. Puedes usar este comando de las dos maneras que se mencionan a continuación:

  • Con un archivo YAML que contiene la definición de la función
  • Con marcas para especificar la definición de la función

Cuando crees una función personalizada, debes especificar si se aplica a nivel de la organización o a nivel del proyecto mediante las marcas --organization [ORGANIZATION-ID] o --project [PROJECT-ID]. En cada uno de los siguientes ejemplos, se crea una función personalizada a nivel del proyecto.

Para crear una función personalizada con un archivo YAML, haz lo siguiente:

Crea un archivo YAML que contenga la definición de tu función personalizada. El archivo se debe estructurar de la siguiente manera:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description".
  • [LAUNCH-STAGE] indica la etapa en la que se encuentra una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.
  • includedPermissions especifica la lista de uno o más permisos para incluir en la función personalizada, como - iam.roles.get.

Guarda el archivo YAML y, luego, ejecuta el siguiente comando de gcloud:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [YAML_FILE-PATH] es la ruta a la ubicación de tu archivo YAML que contiene la definición de la función personalizada.

En el siguiente archivo YAML de ejemplo, se muestra cómo crear una definición de función:

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

En el siguiente ejemplo, se muestra cómo crear una función mediante el archivo YAML:

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

Si la función se creó con éxito, se muestra la siguiente respuesta:

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

Para crear una función personalizada mediante marcas, haz lo siguiente:

Ejecuta el siguiente comando de gcloud:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description.".
  • [PERMISSIONS-LIST] contiene una lista de permisos separada por comas que deseas incluir en la función personalizada. Por ejemplo: iam.roles.get,iam.roles.list.
  • [LAUNCH-STAGE] indica la etapa en la que se encuentra una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

En el siguiente ejemplo, se muestra cómo crear una función con marcas:

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

Si la función se creó con éxito, se muestra la siguiente respuesta:

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

API de REST

Usa el método create para crear una nueva función personalizada.

Establece los siguientes parámetros requeridos en la solicitud:

  • El role_id que deseas usar para la nueva función personalizada, como appengine.myCustomStorageAuditor.
  • Una descripción de la función personalizada, como “Esta función otorga acceso a los recursos de almacenamiento de la lista, su capacidad y las políticas de acceso”.
  • Una lista de los permisos que deseas asociar a esta función.
  • Ten en cuenta que establecer el campo de nombre en la función dará como resultado un error.

Recomendamos que también establezcas los siguientes parámetros opcionales:

  • Título para la función personalizada, como "Ejemplo de editor de funciones personalizadas".
  • Establece un valor para stage, como GA.

stage acepta los siguientes valores: ALPHA, BETA, GA, DEPRECATED o DISABLED.

Algunas funciones predefinidas contienen permisos obsoletos o permisos que no están permitidos en las funciones personalizadas. La creación de una función personalizada basada en una función predefinida que contenga permisos obsoletos o restringidos fallará.

Ejemplo

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

En el ejemplo anterior, se ilustra lo siguiente:

  • [PARENT-NAME] es el nombre de la organización en la que creas la función personalizada, por ejemplo organizations/0000000000000001, o el ID del proyecto en el que creas la función personalizada, por ejemplo projects/my-project.
  • [ROLE-ID] es el ID de la función personalizada. Por ejemplo: appengine.myCustomStorageAuditor..
  • [ROLE-TITLE] es el título de la función. Por ejemplo, Storage Auditor.
  • [ROLE-DESCRIPTION] es la descripción de lo que hace la función.
  • [PERMISSION] es el permiso que deseas incluir en la función personalizada.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para crear una función en {parent}.
ALREADY_EXISTS Ya existe una función llamada {role-id} en {parent}.
INVALID_ARGUMENT El superior {parent} no es válido. El superior debe tener el formato organizations/{organization-id}.
INVALID_ARGUMENT El role_id {role-id} no es válido. No coincide con {pattern}.
INVALID_ARGUMENT La cantidad de permisos en la función es mayor que el máximo de {max}.
INVALID_ARGUMENT Role.stage {stage} no es válida.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

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

Edita una función personalizada existente

Leer, modificar, escribir

Un patrón común para actualizar los metadatos de un recurso, como una función personalizada, es leer su estado actual, actualizar los datos de forma local y, luego, enviar los datos modificados para su escritura. Este patrón podría causar un conflicto si dos o más procesos independientes intentan la secuencia en simultáneo. Por ejemplo, si dos propietarios de un proyecto intentan realizar cambios conflictivos en una función al mismo tiempo, algunos cambios podrían fallar. Cloud IAM resuelve este problema mediante una propiedad etag en las funciones personalizadas. Esta propiedad se usa para verificar si la función personalizada cambió desde la última solicitud. Cuando realizas una solicitud a Cloud IAM con un valor de Etag, Cloud IAM compara este valor en la solicitud con el valor de Etag existente asociado a la función personalizada. Solo escribe el cambio si los valores de Etag coinciden.

Cuando actualices una función, primero debes obtener la función con roles.get(), actualizarla y, luego, escribir la función actualizada con roles.patch(). Usa el valor de Etag cuando establezcas la función solo si la función correspondiente en roles.get() contiene un valor de Etag.

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona tu organización del menú desplegable Organización.
  3. Haz clic en una función personalizada.
  4. Haz clic en Editar función.
  5. Haz clic en Agregar permisos para agregar permisos nuevos a la función.
  6. Desmarca permisos para quitarlos de la función.
  7. Haz clic en Actualizar para guardar la función editada.

Comando de gcloud

Usa el comando gcloud iam roles update para actualizar las funciones personalizadas. Puedes usar este comando de las dos maneras que se mencionan a continuación:

  • Con un archivo YAML que contiene la definición de la función actualizada
  • Con marcas para especificar la definición de la función actualizada

Cuando actualices una función personalizada, debes especificar si se aplica a nivel de la organización o a nivel del proyecto mediante las marcas --organization [ORGANIZATION-ID] o --project [PROJECT-ID]. En cada uno de los siguientes ejemplos, se crea una función personalizada a nivel del proyecto.

Para actualizar una función personalizada con un archivo YAML, haz lo siguiente:

Ejecuta el siguiente comando de gcloud a fin de obtener la definición actual para la función:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función que quieres actualizar, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.

Con la ejecución del comando describe, se muestra la definición de la función, que incluye un valor de etag que identifica de forma única la versión actual de la función. El valor de etag debe proporcionarse en la definición de la función actualizada para garantizar que no se reemplace ningún cambio de función simultáneo.

Con el comando describe, se muestra el siguiente resultado:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description".
  • [ETAG-VALUE] es el identificador único de la versión actual de la función, como BwVkBkbfr70=.
  • includedPermissions especifica la lista de uno o más permisos para incluir en la función personalizada, como - iam.roles.get.
  • [ROLE-ID] es el ID jerárquico de la función, que depende de si se creó a nivel del proyecto o de la organización. Por ejemplo: projects/my-project-id/roles/viewer.
  • [LAUNCH-STAGE] indica la etapa en la que se encuentra una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.
  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".

Para actualizar la función, incluye la definición de función de salida en un archivo YAML o actualiza el archivo original YAML con el valor de salida de etag.

Considera el siguiente archivo YAML de ejemplo, que contiene el resultado del comando describe y agrega dos permisos de Cloud Storage:

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

Guarda el archivo YAML y, luego, ejecuta el siguiente comando de gcloud:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función que quieres actualizar, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [YAML_FILE-PATH] es la ruta a la ubicación de tu archivo YAML que contiene la definición actualizada de la función personalizada.

En el siguiente ejemplo, se muestra cómo actualizar una función con el archivo YAML:

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

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

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

Para actualizar una función personalizada mediante marcas, haz lo siguiente:

Cada parte de la definición de una función se puede actualizar con la marca correspondiente. Consulta la página sobre gcloud iam roles update para obtener una lista de todas las marcas posibles.

Puedes usar las siguientes marcas para agregar o quitar permisos:

  • --add-permissions [PERMISSIONS]: Agrega a la función uno o más permisos separados por comas.
  • --remove-permissions [PERMISSIONS]: Quita de la función uno o más permisos separados por comas.

De manera alternativa, puedes especificar los permisos nuevos con la marca --permissions [PERMISSIONS] y proporcionar una lista de permisos separados por coma para reemplazar la existente.

Para actualizar otros aspectos de la definición de la función, ejecuta el siguiente comando de gcloud:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id.
  • [ROLE-TITLE] es un título descriptivo para la función, como "Role Viewer".
  • [ROLE-DESCRIPTION] es una descripción corta sobre la función, como "My custom role description.".
  • [LAUNCH-STAGE] indica la etapa en la que se encuentra una función en el ciclo de vida de lanzamiento, como ALPHA, BETA o GA.

En el siguiente ejemplo, se muestra cómo agregar permisos a una función mediante marcas:

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

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

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

API de REST

Usa el método Role UpdateRole(UpdateRoleRequest) para editar una función personalizada existente.

Si conoces el ID de la función personalizada que deseas editar, obtén la función con el método roles.get() y, luego, actualízala con roles.patch().

Si no conoces el ID de función de la función personalizada que deseas editar, enumera todas las funciones con ListRoles() para identificar la función. roles.list() muestra una lista de todas las funciones que hacen referencia al recurso. Luego, actualiza la función con roles.patch().

Configura el siguiente parámetro obligatorio en roles.patch():

  • Nombre de la función, como organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}.

De manera opcional, configura el campo update_mask para que especifique los campos que se pueden actualizar en el futuro.

Ejemplo

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

En el ejemplo anterior, se ilustra lo siguiente:

  • [ROLE-NAME] es el nombre de la función. Por ejemplo, organizations/123456/roles/appengine.customRoleEditor. puede tener el formato roles/{ROLE-NAME}, organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME} o projects/{PROJECT-ID}/roles/{ROLE-NAME}.

  • [ROLE-TITLE] es el título de la función. Por ejemplo, New custom editor..

  • [ROLE-DESCRIPTION] es una descripción de la función. Por ejemplo, “Mi nueva descripción larga de editor”.
  • [PERMISSION] es el permiso que deseas incluir en la función. Por ejemplo, storage.objects.update.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para actualizar la función.
INVALID_ARGUMENT No se pueden actualizar las funciones predefinidas.
INVALID_ARGUMENT El nombre de la solicitud ([ROLE-NAME]) y el nombre de la función () deben coincidir.
INVALID_ARGUMENT El permiso [PERMISSION] no es válido.
ABORTED Hubo cambios de política simultáneos dado que el etag no coincidió. Vuelve a intentar todo el proceso de lectura, modificación y escritura con la retirada exponencial.

Algunas funciones predefinidas contienen permisos obsoletos o permisos que no están permitidos en las funciones personalizadas. La creación de una función personalizada basada en una función predefinida que contenga permisos obsoletos o restringidos fallará.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

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

Inhabilita una función personalizada

Puedes inhabilitar una función personalizada. Cuando una función está inhabilitada, todos los enlaces de políticas relacionados con ella se desactivan, lo que significa que no se concederán los permisos en la función, incluso si concedes la función a un usuario.

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Haz clic en el menú desplegable "Seleccionar un proyecto" en la parte superior de la página.
  3. Selecciona tu organización o proyecto.
  4. Selecciona una función personalizada y haz clic en Inhabilitar.

Comando de gcloud

Si quieres usar el comando gcloud iam roles update para inhabilitar una función personalizada, establece su etapa de lanzamiento en DISABLED. Como se describe en la pestaña gcloud de la sección Edita una función personalizada existente, puedes actualizar una función personalizada existente mediante los dos métodos siguientes:

  • Con un archivo YAML que contiene la definición de la función actualizada
  • Con marcas para especificar la definición de la función actualizada

La forma más fácil de inhabilitar una función personalizada existente es usar la marca --stage y establecerla en DISABLED. Ejecuta el siguiente de comando de gcloud:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

En el siguiente ejemplo, se muestra cómo inhabilitar una función:

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

Si la función se actualizó con éxito, se muestra la siguiente respuesta:

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

API de REST

Usa el método roles.patch() para inhabilitar una función personalizada.

Si conoces el ID de función de la función personalizada que deseas inhabilitar, obtén la función con el método roles.get(). Cambia la propiedad stage de la función a DISABLED y, luego, llama al método roles.patch() para actualizar la función.

Si no conoces el ID de función de la función personalizada que deseas inhabilitar, enumera todas las funciones mediante roles.list() para identificarla. roles.list() muestra una lista de todas las funciones que hacen referencia al recurso. Identifica la función que deseas inhabilitar, cambia su propiedad rolelaunchstage a DISABLED, y, luego, llama al método roles.patch() para actualizar la función.

Para inhabilitar una función, establece los siguientes campos:

  • Establece el nombre completo de la función, organizations/{organization-id}/roles/{role}..
  • En Role,, establece stage en DISABLED..
  • Establece update_mask en “paths: stage”.

Si quieres volver a habilitar la función, sigue el mismo proceso anterior de inhabilitación de la función, pero establece la propiedad stage de la función en ALPHA, BETA o GA.

Ejemplo

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

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para actualizar la función.
INVALID_ARGUMENT No se pueden actualizar las funciones seleccionadas.
INVALID_ARGUMENT El nombre de la solicitud ([ROLE-NAME]) y el nombre de la función () deben coincidir.
INVALID_ARGUMENT El permiso [PERMISSION] no es válido.
ABORTED Hubo cambios de política simultáneos. Vuelve a intentar todo el proceso de lectura, modificación y escritura con la retirada exponencial.

C#

Actualiza el campo stage de la función a DISABLED.

Go

Actualiza el campo stage de la función a DISABLED.

Python

Actualiza el campo stage de la función a DISABLED.

Enumera las funciones

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones


    Todas las funciones personalizadas del proyecto se enumeran en la página.

Comando de gcloud

Usa el comando gcloud iam roles list a fin de enumerar las funciones personalizadas y predefinidas de una organización o un proyecto.

Ejecuta el siguiente comando de gcloud para enumerar las funciones personalizadas y especificar las funciones personalizadas a nivel del proyecto o de la organización:

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

[PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

Para enumerar las funciones que se borraron, también puedes especificar la marca --show-deleted.

Ejecuta el siguiente comando de gcloud para enumerar las funciones predefinidas:

gcloud iam roles list

API de REST

El método roles.list() se puede usar para enumerar todas las funciones personalizadas definidas en una organización o en un proyecto. También se puede usar a fin de enumerar las funciones predefinidas si estableces el campo superior de la solicitud en "".

Para llamar a roles.list(), configura el siguiente campo en la solicitud:

  • El superior que deseas usar para obtener todas las funciones personalizadas, como las siguientes
    • projects/{PROJECT-ID}
    • organizations/{ORGANIZATION-ID}

Si deseas que el resultado contenga los permisos de cada función, establece el campo view en RoleView::FULL.

Si deseas que el resultado contenga las funciones que se borraron recientemente, establece el campo showDeleted en true.

Si deseas enumerar todas las funciones predefinidas, establece el superior en "" (string vacía).

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para enumerar funciones en {path}.
INVALID_ARGUMENT El superior {path} no es válido. El superior debe tener el formato organizations/{organization-id}, projects/{project-id} o estar vacío.
INVALID_ARGUMENT La vista de funciones no es válida.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

Borra una función personalizada

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Selecciona la función que deseas borrar y haz clic en el ícono de la papelera en la parte superior de la página.

Comando de gcloud

Usa el comando gcloud iam roles delete para borrar una función personalizada. La función está suspendida y no se puede usar para crear nuevas vinculaciones de políticas de IAM.

Ejecuta el siguiente comando de gcloud para borrar una función personalizada:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

La función no se incluirá en la gcloud iam roles list, a menos que se incluya la marca --show-deleted. Las funciones que se borraron se indican mediante el bloque deleted: true en una respuesta de la list, como la que se muestra a continuación:

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

API de REST

roles.delete borra una función. La función está suspendida y no se puede usar para crear nuevas vinculaciones de políticas de IAM.

El name puede estar en los siguientes formatos:

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

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para borrar la función en {path}.
FAILED_PRECONDITION No puedes borrar la función {ROLE-NAME} porque ya se borró.
FAILED_PRECONDITION No puedes borrar una función {ROLE-NAME} reservada.
INVALID_ARGUMENT Las funciones seleccionadas no pueden estar en un estado borrado.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

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

Cuando se borra una función, sus enlaces permanecen, pero están inactivos. Puedes recuperar una función dentro de un plazo de 7 días. Durante este período de 7 días, la función se mostrará como Borrada en Cloud Console y no aparecerá en comandos programáticos de list (a menos que showDeleted se configure en la solicitud).

Después de 7 días, la función está programada para borrarse de forma definitiva. Este proceso lleva 30 días. Durante el período de 30 días, la función y todos los enlaces asociados se quitan de forma permanente, y no puedes crear una nueva función con el mismo ID de función.

Una vez que la función se haya borrado de forma permanente, 37 días después de la solicitud de eliminación inicial, puedes crear una nueva función con el mismo ID de función.

Recupera una función personalizada

Console

  1. Ve a la página Funciones en Cloud Console.

    Abrir la página Funciones

  2. Encuentra la función que deseas recuperar, haz clic en el ícono de más al final de la fila y, luego, en Recuperar.

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todas las vinculaciones asociadas a esta.

Comando de gcloud

Usa el comando gcloud iam roles undelete para recuperar una función personalizada. Cuando recuperas una función, esta vuelve a su estado anterior.

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todas las vinculaciones asociadas a esta.

Ejecuta el siguiente comando de gcloud para recuperar una función personalizada:

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

Cada uno de los valores del marcador de posición se describe a continuación:

  • [ROLE-ID] es el nombre de la función, como viewer.
  • [PROJECT-ID] es el nombre del proyecto, como my-project-id. También puedes usar la marca --organization [ORGANIZATION-ID] si la función se creó a nivel de la organización, como 1234567.

En el siguiente ejemplo, se muestra cómo recuperar una función personalizada:

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

Si la función se recuperó con éxito, se muestra la siguiente respuesta:

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

API de REST

roles.undelete recupera una función a su estado anterior.

El name puede estar en los siguientes formatos:

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

La función solo se puede recuperar dentro de los 7 días posteriores a la eliminación. Después de 7 días, la función se borra de forma permanente y se quitan todas las vinculaciones asociadas a esta.

Códigos de error

Código de error Mensaje de estado
PERMISSION_DENIED No tienes permiso para recuperar la función en {path}.
FAILED_PRECONDITION No se puede recuperar una función que no está borrada.
FAILED_PRECONDITION No puedes recuperar una función {ROLE-NAME} reservada.
INVALID_ARGUMENT Las funciones predefinidas no se pueden recuperar.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para C#.


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

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

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

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido con bibliotecas cliente de Cloud IAM. Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python que aparecen en la Guía de inicio rápido de Cloud IAM con bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Cloud IAM para Python.

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

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

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