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 recomendable saber qué permisos se pueden aplicar a un recurso. Puedes obtener todos los permisos que se pueden aplicar a un recurso, y los recursos siguientes en la jerarquía, mediante la herramienta de línea de comandos de gcloud, Google Cloud Console o la API de administración de identidades y accesos. Por ejemplo, puedes obtener todos los permisos que puedes aplicar en una organización y en sus proyectos.

Console

  1. En Cloud Console, ve a la página Funciones.

    Ir a 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 Administrador de instancia de procesamiento, el panel del lado 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 mostrados son los que se pueden usar para crear una función personalizada en este recurso y en cualquiera que se encuentre debajo 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 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 permisos compatibles y no compatibles, consulta Compatibilidad para permisos de funciones personalizadas.

API de REST

El método permissions.queryTestablePermissions permite enumerar todos los permisos que puedes probar en un recurso.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • full-resource-name: Un URI que consiste en el nombre del servicio y la ruta al recurso. Para ver ejemplos, consulta Nombres completos de recursos.
  • page-size: Opcional. Es la cantidad de permisos que se incluirán en la respuesta. El valor predeterminado es 100 y el valor máximo es 1,000. Si la cantidad de permisos es mayor que el tamaño de la página, la respuesta contiene un token de paginación que puedes usar para consultar la siguiente página de resultados.
  • next-page-token: Opcional. Es el token de paginación que se mostró en una respuesta anterior de este método. Si se especifica, la lista de permisos que se pueden probar comenzará desde el punto en que finalizó la solicitud anterior.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 la función incluyen el ID de función y los permisos contenidos en la función. Puedes ver los metadatos con Cloud Console o la API de IAM.

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

Console

  1. En Cloud Console, ve a la página Funciones.

    Ir a 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 función. El panel lateral derecho muestra los permisos contenidos en las funciones, si los hay.

Los íconos de la columna Tipo (Type) indican si es una función personalizada o una función predefinida

Si deseas buscar todas las funciones que incluyen un permiso específico, escribe el nombre del permiso en el cuadro Filtro 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-id

role-id es el ID de la función. Las funciones predefinidas incluyen el prefijo role en sus ID, por ejemplo, roles/iam.roleViewer.

En el siguiente ejemplo, se demuestra la salida 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, ejecuta uno de los siguientes comandos gcloud:

  • Para ver los metadatos de una función personalizada creada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles describe --organization=organization-id role-id
    
  • Para ver los metadatos de una función personalizada creada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.
  • role-id es el ID de la función, sin incluir los prefijos como projects/, organizations/ o roles/. Por ejemplo, myCompanyAdmin.

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

API de REST

El método roles.get permite obtener la definición de una función.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • full-role-id: Es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene la definición de la función.

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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

Puedes crear una función personalizada a nivel del proyecto o de la organización.

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 la función de organización o la función de administrador de funciones de IAM.

El tamaño total del título, la descripción y los nombres de permisos para una función personalizada se limita a 64 KB. Si necesitas crear una función personalizada más grande, puedes dividir los permisos en varias funciones personalizadas. Elige títulos de funciones que muestren la relación entre las funciones personalizadas, como Custom Admin (1 of 2) y Custom Admin (2 of 2).

Console

Para crear una nueva función personalizada desde cero, haz lo siguiente:

  1. En Cloud Console, ve a la página Funciones.

    Ir a la página Funciones

  2. En la lista desplegable de la parte superior de la página, selecciona la organización o el proyecto en el que deseas crear una funció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 servicio y tipo.

Crea una función personalizada con base en una función seleccionada existente:

  1. En Cloud Console, ve a la página Funciones.

    Ir a la página Funciones

  2. Selecciona la organización o el proyecto en el que deseas crear una funció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 debe estar estructurado de la siguiente manera:

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

Cada valor de marcador de posición se describe a continuación:

  • role-title es un título descriptivo para la función, como "My Company Admin".
  • role-description es una descripción breve de 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.
  • permission-1 y permission-2 son permisos para incluir en la función personalizada, como iam.roles.get.

Guarda el archivo YAML y, luego, ejecuta uno de los siguientes comandos:

  • Para crear una función personalizada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles create role-id --organization=organization-id \
      --file=yaml-file-path
    
  • Para crear una función personalizada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.
  • yaml-file-path es la ruta de acceso a la ubicación de tu archivo YAML que contiene la definición de la función personalizada.

Ejemplos

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

title: "My Company Admin"
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 a nivel de la organización mediante el archivo YAML:

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

Si la función se creó con éxito, el resultado del comando es similar al siguiente:

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

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

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

Si la función se creó con éxito, el resultado del comando es similar al siguiente:

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

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

Ejecuta uno de los siguientes comandos:

  • Para crear una función personalizada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles create role-id --organization=organization-id \
      --title=role-title --description=role-description \
      --permissions=permissions-list --stage=launch-stage
    
  • Para crear una función personalizada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.
  • role-title es un título descriptivo para la función, como "My Company Admin".
  • role-description es una descripción breve de 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.

Ejemplos

En el siguiente ejemplo, se muestra cómo crear una función a nivel de la organización mediante marcas:

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

Si la función se creó con éxito, el resultado del comando es similar al siguiente:

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

En el siguiente ejemplo, se muestra cómo crear una función a nivel del proyecto mediante marcas:

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

Si la función se creó con éxito, el resultado del comando es similar al siguiente:

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

API de REST

El método roles.create permite crear una función personalizada en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • resource-type: Es el tipo de recurso cuyas funciones personalizadas quieres administrar. Usa el valor projects o organizations.
  • resource-id: Es el ID del proyecto o de la organización cuyas funciones personalizadas deseas administrar.
  • role-id: Es el nombre de la función, como myCompanyAdmin.
  • role-title: Es el título legible para la función. Por ejemplo, My Company Admin.
  • role-description: Es una descripción para la función. Por ejemplo, "The company admin role allows company admins to access important resources".
  • permission-1 y permission-2: Son los permisos que deseas incluir en la función. Por ejemplo, storage.objects.update.
  • launch-stage: Es la etapa de lanzamiento actual de la función. Este campo puede contener uno de los siguientes valores: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene la función que creaste.

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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

Lee, modifica, escribe

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. 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 IAM con un valor ETag, IAM compara ese valor en la solicitud con el valor ETag existente asociado con la función personalizada. Solo escribe el cambio si los valores ETag coinciden.

Cuando actualices una función, primero debes obtenerla 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. En Cloud Console, ve a la página Funciones.

    Ir a la página Funciones

  2. En la lista desplegable de la parte superior de la página, selecciona el proyecto o la organización que contiene la función que deseas editar.

  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 uno de los siguientes comandos para obtener la definición actual de la función:

  • Para obtener la definición de una función personalizada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles describe role-id --organization=organization-id
    
  • Para obtener la definición de función de una función personalizada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función que quieres actualizar, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.

El comando describe muestra la definición de la función y, además, 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.

El comando describe muestra el siguiente resultado:

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

Cada valor de marcador de posición se describe a continuación:

  • role-description es una descripción breve de 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=.
  • permission-1 y permission-2 son permisos para incluir en la función personalizada, como iam.roles.get.
  • full-role-id es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin..
  • 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 "My Company Admin".

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 la salida del comando describe para una función a nivel del proyecto 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/myCompanyAdmin
stage: ALPHA
title: My Company Admin

Guarda el archivo YAML y, luego, ejecuta uno de los siguientes comandos:

  • Para actualizar una función a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles update role-id --organization=organization-id \
      --file=yaml-file-path
    
  • Para actualizar una función a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función que quieres actualizar, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.
  • yaml-file-path es la ruta de acceso a la ubicación de tu archivo YAML que contiene la definición de la función personalizada actualizada.

Ejemplos

En el siguiente ejemplo, se muestra cómo actualizar una función a nivel de la organización mediante un archivo YAML:

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

En el siguiente ejemplo, se muestra cómo actualizar una función a nivel de proyecto mediante un archivo YAML:

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

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

Cada parte de la definición de una función se puede actualizar mediante la marca correspondiente. Consulta el tema 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 mediante la marca --permissions=permissions y proporcionar una lista de permisos separados por comas para reemplazar la lista existente.

Para actualizar otras partes de la definición de la función, ejecuta uno de los siguientes comandos:

  • Para actualizar una función a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles update role-id --organization=organization-id \
      --title=role-title --description=role-description \
      --stage=launch-stage
    
  • Para actualizar una función a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.
  • role-title es un título descriptivo para la función, como "My Company Admin".
  • role-description es una descripción breve de 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.

Ejemplos

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

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

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

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

API de REST

El método roles.patch permite actualizar una función personalizada en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

Obligatorios:

  • resource-type: Es el tipo de recurso cuyas funciones personalizadas quieres administrar. Usa el valor projects o organizations.
  • resource-id: Es el ID del proyecto o de la organización cuyas funciones personalizadas deseas administrar.
  • full-role-id: Es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin.

Recomendados:

  • etag: Es un identificador para una versión de la función. Incluye este campo para evitar reemplazar otros cambios de funciones.

Opcional (define uno o más de los siguientes valores):

  • role-title: Es el título legible para la función. Por ejemplo, My Company Admin.
  • role-description: Es una descripción para la función. Por ejemplo, "The company admin role allows company admins to access important resources".
  • permission-1 y permission-2: Son los permisos que deseas incluir en la función. Por ejemplo, storage.objects.update.
  • launch-stage: Es la etapa de lanzamiento actual de la función. Este campo puede contener uno de los siguientes valores: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene una definición de función abreviada que incluye el nombre de la función, los campos que actualizaste y un ETag que identifica la versión actual de la función.

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

Algunas funciones predefinidas contienen permisos obsoletos o permisos que, de otra manera, 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 esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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. En Cloud Console, ve a la página Funciones.

    Ir a 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 siguientes dos métodos:

  • 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 uno de los siguientes comandos:

  • Para inhabilitar una función a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles update role-id --organization=organization-id \
      --stage=DISABLED
    
  • Para inhabilitar una función a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.

Ejemplos

En el siguiente ejemplo, se muestra cómo inhabilitar una función a nivel de la organización:

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

En el siguiente ejemplo, se muestra cómo inhabilitar una función a nivel del proyecto:

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

Si la función se actualizó con éxito, el resultado del comando es similar al siguiente:

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

API de REST

El método roles.patch permite cambiar la etapa de lanzamiento de una función personalizada a DISABLED para inhabilitarla.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • resource-type: Es el tipo de recurso cuyas funciones personalizadas quieres administrar. Usa el valor projects o organizations.
  • resource-id: Es el ID del proyecto o de la organización cuyas funciones personalizadas deseas administrar.
  • full-role-id: Es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin.

  • etag: Es un identificador para una versión de la función. Incluye este campo para evitar reemplazar otros cambios de funciones.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

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

Puedes enumerar todas las funciones personalizadas creadas en tu organización o proyecto.

Console

En Cloud Console, ve a la página Funciones.

Ir a la página Funciones

Todas las funciones personalizadas para la organización o el proyecto que seleccionaste 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.

Para enumerar las funciones personalizadas, ejecuta uno de los siguientes comandos:

  • Para enumerar las funciones personalizadas a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles list --organization=organization-id
    
  • Para enumerar las funciones personalizadas a nivel de proyecto, ejecuta el siguiente comando:

    gcloud iam roles list --project=project-id
    

Cada valor de marcador de posición se describe a continuación:

  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.

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 permite enumerar todas las funciones personalizadas de un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • resource-type: Es el tipo de recurso cuyas funciones personalizadas quieres administrar. Usa el valor projects o organizations.
  • resource-id: Es el ID del proyecto o de la organización cuyas funciones personalizadas deseas administrar.
  • role-view: Es opcional. Es la información que se debe incluir para las funciones que se muestran. Para incluir los permisos de las funciones, establece este campo en FULL. Para excluir los permisos de las funciones, establece este campo en BASIC. El valor predeterminado es BASIC.
  • page-size: Opcional. Es la cantidad de funciones que se deben incluir en la respuesta. El valor predeterminado es 300 y el valor máximo es 1,000. Si la cantidad de funciones es mayor que el tamaño de la página, la respuesta contiene un token de paginación que puedes usar para consultar la siguiente página de resultados.
  • next-page-token: Opcional. Es el token de paginación que se mostró en una respuesta anterior de este método. Si se especifica, la lista de funciones comenzará desde el punto en que finalizó la solicitud anterior.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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

Puedes borrar cualquier función personalizada en tu organización o proyecto.

Console

  1. En Cloud Console, ve a la página Funciones.

    Ir a la página Funciones

  2. Selecciona la función que deseas borrar y haz clic en  Borrar 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 nuevos enlaces de políticas de IAM.

Para borrar una función personalizada, ejecuta uno de los siguientes comandos:

  • Para borrar una función personalizada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles delete role-id --organization=organization-id
    
  • Para borrar una función personalizada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.

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

API de REST

El método roles.delete permite borrar una función personalizada en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • full-role-id: Es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene la definición de la función que se borró.

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 vinculaciones permanecen, pero están inactivas. 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. En este punto, la función ya no se tiene en cuenta para el límite de 300 funciones personalizadas por organización o 300 funciones personalizadas por proyecto.

El proceso de eliminación permanente demora 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 función nueva 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 función nueva con el mismo ID de función.

Recupera una función personalizada

Cuando recuperas una función, esta vuelve a su estado anterior.

Las funciones solo se pueden recuperar en un plazo de 7 días. Después de este plazo, se borran de forma permanente y se quitan todas las vinculaciones asociadas con ellas.

Console

  1. En Cloud Console, ve a la página Funciones.

    Ir a la página Funciones

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

Comando de gcloud

Usa el comando gcloud iam roles undelete para recuperar una función personalizada.

Para recuperar una función personalizada, ejecuta uno de los siguientes comandos:

  • Para recuperar una función personalizada a nivel de la organización, ejecuta el siguiente comando:

    gcloud iam roles undelete role-id --organization=organization-id
    
  • Para recuperar una función personalizada a nivel de proyecto, ejecuta el siguiente comando:

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

Cada valor de marcador de posición se describe a continuación:

  • role-id es el nombre de la función, como myCompanyAdmin.
  • organization-id es el ID numérico de la organización, como 123456789012.
  • project-id es el nombre del proyecto, como my-project-id.

Ejemplos

En el siguiente ejemplo, se muestra cómo recuperar una función personalizada a nivel de la organización:

gcloud iam roles undelete myCompanyAdmin --organization=123456789012

Si la función se recuperó con éxito, el resultado del comando es similar al siguiente:

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

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

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

Si la función se recuperó con éxito, el resultado del comando es similar al siguiente:

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

API de REST

El método roles.undelete permite recuperar una función personalizada en un proyecto o una organización.

Antes de usar cualquiera de los datos de solicitud que se muestran a continuación, realiza los siguientes reemplazos:

  • full-role-id: Es el ID de función completo, incluidos los prefijos organizations/, projects/ o roles/. Por ejemplo: organizations/123456789012/roles/myCompanyAdmin.

  • etag: Es un identificador para una versión de la función. Incluye este campo para evitar reemplazar otros cambios de funciones.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "etag": "etag"
}

Para enviar tu solicitud, expande una de estas opciones:

La respuesta contiene la definición de la función que se recuperó.

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

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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 esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de IAM para Go.

import (
	"context"
	"fmt"
	"io"

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

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

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

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de IAM sobre el uso de bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de 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

Próximos pasos