Crea e gestisci ruoli personalizzati

In questa pagina viene descritto come creare e gestire i ruoli personalizzati di Identity and Access Management (IAM). La gestione dei ruoli include la modifica, la disattivazione, l'elenco, l'eliminazione e l'annullamento dell'eliminazione dei ruoli.

Prima di iniziare

  • Attiva IAM API.

    Abilita l'API

  • Configurare l'autenticazione.

    Seleziona la scheda relativa a come intendi utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi e alle API di Google Cloud, non devi configurare l'autenticazione.

    gcloud

    In questa pagina puoi utilizzare gli esempi di gcloud CLI da uno dei seguenti ambienti di sviluppo:

    • Cloud Shell: per utilizzare un terminale online con gcloud CLI già configurato, attiva Cloud Shell.

      In fondo a questa pagina viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. L'inizializzazione della sessione può richiedere alcuni secondi.

    • shell locale: per utilizzare gcloud CLI in un ambiente di sviluppo locale, installa e initialize gcloud CLI.

    C++

    Per utilizzare gli esempi C++ in questa pagina da un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    C#

    Per utilizzare gli esempi .NET in questa pagina da un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    Go

    Per utilizzare gli esempi Go in questa pagina da un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    Java

    Per utilizzare gli esempi Java in questa pagina da un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    Python

    Per utilizzare gli esempi Python in questa pagina da un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura le Credenziali predefinite dell'applicazione con le tue credenziali utente.

    1. Installa Google Cloud CLI.
    2. Per initialize gcloud CLI, esegui questo comando:

      gcloud init
    3. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

    Per saperne di più, consulta Configurare l'autenticazione per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud.

    REST

    Per utilizzare gli esempi di API REST su questa pagina in un ambiente di sviluppo locale, devi utilizzare le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI, quindi initialize eseguendo questo comando:

      gcloud init

  • Scopri la gerarchia delle risorse di Google Cloud.

  • Consulta Informazioni sui ruoli IAM personalizzati.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire i ruoli personalizzati, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Visualizza le autorizzazioni disponibili per progetti, cartelle e organizzazioni

Puoi creare ruoli personalizzati per un'intera organizzazione o per un progetto specifico all'interno di quell'organizzazione. Le autorizzazioni disponibili per i ruoli personalizzati dipendono da dove crei il ruolo. Ad esempio, se un'autorizzazione può essere utilizzata solo a livello di organizzazione, non puoi includerla in un ruolo personalizzato a livello di progetto.

Per verificare quali autorizzazioni sono disponibili per i ruoli personalizzati a livello di organizzazione e di progetto, puoi utilizzare gcloud CLI o l'API Identity and Access Management per elencare le autorizzazioni disponibili in un'organizzazione o un progetto specifici. Ad esempio, puoi ottenere tutte le autorizzazioni disponibili per i ruoli personalizzati creati nel tuo progetto.

Alcune autorizzazioni potrebbero non essere visibili o utilizzabili in un ruolo personalizzato, anche se sono supportate nei ruoli personalizzati. Ad esempio, un'autorizzazione potrebbe non essere disponibile per l'utilizzo nei ruoli personalizzati se non hai abilitato l'API per il servizio.

Per saperne di più sulle autorizzazioni che puoi aggiungere ai ruoli personalizzati, consulta Autorizzazioni supportate.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam list-testable-permissions per visualizzare un elenco delle autorizzazioni disponibili per i ruoli personalizzati in un'organizzazione o un progetto specifico. La risposta elenca le autorizzazioni che puoi utilizzare nei ruoli personalizzati per quel progetto o organizzazione.

    Per elencare le autorizzazioni disponibili nei ruoli personalizzati per un progetto o un'organizzazione, esegui questo comando:

    gcloud iam list-testable-permissions FULL_RESOURCE_NAME \
        --filter="customRolesSupportLevel!=NOT_SUPPORTED"

    Sostituisci FULL_RESOURCE_NAME con uno dei seguenti valori:

    • Progetto: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID (ad esempio, //cloudresourcemanager.googleapis.com/projects/my-project)

    • Organizzazione: //cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID (ad esempio, //cloudresourcemanager.googleapis.com/organizations/123456789012)

    I risultati indicano se ciascuna autorizzazione è supportata nei ruoli personalizzati. Le autorizzazioni che non hanno un campo customRolesSupportLevel sono completamente supportate.

    Il comando list-testable-permissions potrebbe restituire centinaia di risultati. Questo esempio parziale mostra il formato di ciascun risultato:

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

    queryTestablePermissions(fullResourceName);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def query_testable_permissions(resource: str) -> None:
    """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"])

REST

Il metodo permissions.queryTestablePermissions elenca le autorizzazioni disponibili in un'organizzazione o in un progetto.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • FULL_RESOURCE_NAME: un URI composto dal nome del servizio e dal percorso della risorsa. Ad esempio, consulta la sezione Nomi completi delle risorse.
  • PAGE_SIZE: facoltativo. Il numero di autorizzazioni da includere nella risposta. Il valore predefinito è 100, mentre il valore massimo è 1000. Se il numero di autorizzazioni è maggiore della dimensione della pagina, la risposta contiene un token di impaginazione che puoi utilizzare per recuperare la pagina dei risultati successiva.
  • NEXT_PAGE_TOKEN: facoltativo. Il token di impaginazione restituito in una risposta precedente da questo metodo. Se specificato, l'elenco delle autorizzazioni verificabili inizierà dove è terminata la risposta precedente.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene l'elenco delle autorizzazioni.

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

recupera i metadati del ruolo

Prima di creare un ruolo personalizzato, è consigliabile ottenere i metadati per i ruoli predefiniti e personalizzati. I metadati del ruolo includono l'ID ruolo e le autorizzazioni contenute nel ruolo. Puoi visualizzare i metadati utilizzando la console Google Cloud o l'API IAM.

Per visualizzare i metadati del ruolo, utilizza uno dei metodi seguenti:

Console

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona la tua organizzazione o il tuo progetto dall'elenco a discesa nella parte superiore della pagina.

  3. Seleziona la casella di controllo relativa a uno o più ruoli per visualizzare le autorizzazioni dei ruoli. Il riquadro laterale a destra mostra le eventuali autorizzazioni contenute negli eventuali ruoli.

Le icone nella colonna Tipo indicano se si tratta di un ruolo personalizzato o di un ruolo predefinito

Se vuoi trovare tutti i ruoli che includono un'autorizzazione specifica, digita il nome dell'autorizzazione nella casella Filtro nella parte superiore dell'elenco Ruoli.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles describe per visualizzare i metadati relativi a ruoli predefiniti e ruoli personalizzati.

    Per visualizzare i metadati per un ruolo predefinito, esegui questo comando:

    gcloud iam roles describe ROLE_ID

    ROLE_ID è l'ID del ruolo. I ruoli predefiniti includono il prefisso role nei relativi ID, ad esempio roles/iam.roleViewer.

    L'esempio seguente mostra l'output del comando describe quando viene eseguito nel ruolo predefinito 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
    

    Per visualizzare i metadati relativi a un ruolo personalizzato, esegui uno dei seguenti comandi:

    • Per visualizzare i metadati per un ruolo personalizzato creato a livello di organizzazione, esegui questo comando:

      gcloud iam roles describe --organization=ORGANIZATION_ID ROLE_ID
    • Per visualizzare i metadati per un ruolo personalizzato creato a livello di progetto, esegui questo comando:

      gcloud iam roles describe --project=PROJECT_ID ROLE_ID

    Ogni valore segnaposto è descritto di seguito:

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    • ROLE_ID è l'ID del ruolo, esclusi eventuali prefissi come projects/, organizations/ o roles/. Ad esempio, myCompanyAdmin.

    Per saperne di più, consulta la documentazione di riferimento per gcloud iam roles describe.

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

    getRole(roleId);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def get_role(name: str) -> None:
    """Gets a role."""

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

REST

Il metodo roles.get ottiene la definizione di un ruolo.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • ROLE_NAME: il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene la definizione del ruolo.

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

Creazione di un ruolo personalizzato

Puoi creare un ruolo personalizzato a livello di progetto o organizzazione.

Un ruolo personalizzato a livello di organizzazione può includere qualsiasi autorizzazione IAM supportata nei ruoli personalizzati. Un ruolo personalizzato a livello di progetto può contenere qualsiasi autorizzazione supportata, ad eccezione delle autorizzazioni che possono essere utilizzate solo a livello di organizzazione o cartella, ad esempio resourcemanager.organizations.get. Se provi ad aggiungere queste autorizzazioni a un ruolo personalizzato a livello di progetto, verrà visualizzato un messaggio di errore:

Console

Viene visualizzato il seguente messaggio di avviso: "Non applicabile per i ruoli personalizzati a livello di progetto". L'autorizzazione verrà deselezionata automaticamente dall'elenco delle autorizzazioni incluse e potrai procedere con la creazione del ruolo.

gcloud

Viene restituito il seguente messaggio di errore: INVALID_ARGUMENT: Permission PERMISSION is not valid. Il ruolo personalizzato non verrà creato finché non rimuovi l'autorizzazione dalla definizione del ruolo e provi a eseguire di nuovo l'operazione.

API REST

Viene restituito il seguente messaggio di errore: Permission PERMISSION is not valid, insieme a un codice di errore HTTP 400 e allo stato INVALID_ARGUMENT. Il ruolo personalizzato non verrà creato finché non rimuovi l'autorizzazione dalla definizione del ruolo e riprovi a eseguire l'operazione.

Ogni ruolo personalizzato può contenere fino a 3000 autorizzazioni. Inoltre, la dimensione totale massima del titolo, della descrizione e dei nomi delle autorizzazioni per un ruolo personalizzato è di 64 kB. Se devi creare un ruolo personalizzato più ampio, puoi suddividere le autorizzazioni tra più ruoli personalizzati. Scegli titoli di ruolo che mostrino la relazione tra i ruoli personalizzati, ad esempio Custom Admin (1 of 2) e Custom Admin (2 of 2).

Ogni ruolo personalizzato può avere una fase di avvio. La maggior parte delle fasi di lancio è informativa e consente di capire se ciascun ruolo è pronto per un uso diffuso. Inoltre, la fase di lancio di DISABLED consente di disattivare un ruolo personalizzato. Per ulteriori informazioni sulle fasi di lancio, consulta Test e deployment.

Console

Alcuni ruoli predefiniti contengono autorizzazioni deprecate o autorizzazioni che, altrimenti, non sono consentite nei ruoli personalizzati. Se provi a creare un ruolo personalizzato in base a uno di questi ruoli predefiniti, il ruolo personalizzato ometterà le autorizzazioni deprecate e limitate.

Per creare un nuovo ruolo personalizzato da zero:

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Utilizzando l'elenco a discesa nella parte superiore della pagina, seleziona l'organizzazione o il progetto in cui vuoi creare un ruolo.

  3. Fai clic su Crea ruolo.

  4. Inserisci un nome, un titolo, una descrizione e una fase di lancio del ruolo per il ruolo. Il nome del ruolo non può essere modificato dopo la creazione del ruolo.

  5. Fai clic su Aggiungi autorizzazioni.

  6. Seleziona le autorizzazioni che vuoi includere nel ruolo e fai clic su Aggiungi autorizzazioni. Utilizza gli elenchi a discesa Tutti i servizi e Tutti i tipi per filtrare e selezionare le autorizzazioni per servizi e tipi.

Creazione di un ruolo personalizzato basato su un ruolo predefinito esistente:

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona l'organizzazione o il progetto in cui vuoi creare un ruolo.
  3. Seleziona i ruoli su cui vuoi basare il nuovo ruolo personalizzato.
  4. Fai clic su Crea ruolo da selezione.
  5. Inserisci un nome, un titolo, una descrizione e una fase di lancio del ruolo per il ruolo. Il nome del ruolo non può essere modificato dopo la creazione del ruolo.
  6. Deseleziona le autorizzazioni che vuoi escludere dal ruolo.
  7. Fai clic su Aggiungi autorizzazioni per includere le autorizzazioni.
  8. Fai clic su Crea.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles create per creare nuovi ruoli personalizzati. Puoi utilizzare questo comando in due modi:

    • Fornendo un file YAML che contiene la definizione del ruolo

    • Può utilizzare i flag per specificare la definizione del ruolo

    Quando crei un ruolo personalizzato, devi specificare se si applica a livello di organizzazione o di progetto utilizzando i flag --organization=ORGANIZATION_ID o --project=PROJECT_ID. Ogni esempio riportato di seguito crea un ruolo personalizzato a livello di progetto.

    Un ruolo personalizzato può contenere solo le autorizzazioni supportate nei ruoli personalizzati. Se il ruolo personalizzato contiene altre autorizzazioni, il comando ha esito negativo.

    Per creare un ruolo personalizzato utilizzando un file YAML:

    Crea un file YAML contenente la definizione del tuo ruolo personalizzato. Il file deve essere strutturato nel seguente modo:

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

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_TITLE è un titolo descrittivo per il ruolo, come "My Company Admin".

    • ROLE_DESCRIPTION è una breve descrizione del ruolo, ad esempio "My custom role description".

    • LAUNCH_STAGE indica la fase di un ruolo nel ciclo di vita del lancio, ad esempio ALPHA, BETA o GA.

    • PERMISSION_1 e PERMISSION_2 sono autorizzazioni da includere nel ruolo personalizzato, ad esempio iam.roles.get. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    Salva il file YAML ed esegui uno dei seguenti comandi:

    • Per creare un ruolo personalizzato a livello di organizzazione, esegui questo comando:

      gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
          --file=YAML_FILE_PATH
    • Per creare un ruolo personalizzato a livello di progetto, esegui questo comando:

      gcloud iam roles create ROLE_ID --project=PROJECT_ID \
          --file=YAML_FILE_PATH

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    • YAML_FILE_PATH è il percorso della posizione del file YAML che contiene la definizione del ruolo personalizzato.

    Esempi

    Il seguente file YAML di esempio mostra come creare una definizione di ruolo:

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

    L'esempio seguente mostra come creare un ruolo a livello di organizzazione utilizzando il file YAML:

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

    Se il ruolo è stato creato correttamente, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come creare un ruolo a livello di progetto utilizzando il file YAML:

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

    Se il ruolo è stato creato correttamente, l'output del comando è simile al seguente:

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

    Per creare un ruolo personalizzato utilizzando i flag:

    Esegui uno dei seguenti comandi:

    • Per creare un ruolo personalizzato a livello di organizzazione, esegui questo comando:

      gcloud iam roles create ROLE_ID--organization=ORGANIZATION_ID \
          --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
          --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE
    • Per creare un ruolo personalizzato a livello di progetto, esegui questo comando:

      gcloud iam roles create ROLE_ID --project=PROJECT_ID \
          --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
          --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    • ROLE_TITLE è un titolo descrittivo per il ruolo, come "My Company Admin".

    • ROLE_DESCRIPTION è una breve descrizione del ruolo, ad esempio "My custom role description.".

    • PERMISSIONS_LIST contiene un elenco separato da virgole di autorizzazioni che vuoi includere nel ruolo personalizzato. Ad esempio: iam.roles.get,iam.roles.list. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    • LAUNCH_STAGE indica la fase di un ruolo nel ciclo di vita del lancio, ad esempio ALPHA, BETA o GA.

    Esempi

    L'esempio seguente mostra come creare un ruolo a livello di organizzazione utilizzando i flag:

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

    Se il ruolo è stato creato correttamente, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come creare un ruolo a livello di progetto utilizzando i flag:

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

    Se il ruolo è stato creato correttamente, l'output del comando è simile al seguente:

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def create_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

REST

Il metodo roles.create crea un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • RESOURCE_TYPE: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • RESOURCE_ID: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, come my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • ROLE_ID: il nome del ruolo, ad esempio myCompanyAdmin.
  • ROLE_TITLE: il titolo leggibile per il ruolo. Ad esempio, My Company Admin.
  • ROLE_DESCRIPTION: una descrizione del ruolo. Ad esempio, "The company admin role allows company admins to access important resources".
  • PERMISSION_1 e PERMISSION_2: le autorizzazioni da includere nel ruolo. Ad esempio, storage.objects.update. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    Un ruolo personalizzato può contenere solo le autorizzazioni supportate nei ruoli personalizzati. Se il ruolo personalizzato contiene altre autorizzazioni, la richiesta non riesce.

  • LAUNCH_STAGE: l'attuale fase di lancio del ruolo. Questo campo può contenere uno dei seguenti valori: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene il ruolo che hai creato.

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

Modificare un ruolo personalizzato esistente

Un pattern comune per l'aggiornamento dei metadati di una risorsa, ad esempio un ruolo personalizzato, è il pattern lettura-modifica-scrittura. Con questo pattern, puoi leggere lo stato attuale del ruolo, aggiornare i dati localmente e inviare i dati modificati per la scrittura.

Il pattern di lettura, modifica e scrittura può causare un conflitto se due o più processi indipendenti tentano di eseguire la sequenza contemporaneamente. Ad esempio, se due proprietari di un progetto tentano di apportare modifiche in conflitto a un ruolo contemporaneamente, alcune modifiche potrebbero non riuscire. IAM risolve questo problema utilizzando una proprietà etag nei ruoli personalizzati. Questa proprietà viene utilizzata per verificare se il ruolo personalizzato è cambiato dall'ultima richiesta. Quando invii una richiesta a IAM con un valore etag, IAM confronta il valore etag nella richiesta con il valore etag esistente associato al ruolo personalizzato. Scrive la modifica solo se i valori etag corrispondono.

Quando aggiorni un ruolo, recuperalo prima utilizzando roles.get(), aggiorna il ruolo e poi scrivi il ruolo aggiornato utilizzando roles.patch(). Utilizza il valore etag quando imposti il ruolo solo se il ruolo corrispondente in roles.get() contiene un valore etag.

Console

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Utilizzando l'elenco a discesa nella parte superiore della pagina, seleziona il progetto o l'organizzazione che contiene il ruolo da modificare.

  3. Fai clic su un ruolo personalizzato.

  4. Fai clic su Modifica ruolo.

  5. Per aggiornare i metadati del ruolo, modifica Titolo, Descrizione o Fase di lancio del ruolo.

  6. Per aggiornare le autorizzazioni del ruolo:

    1. Fai clic su Aggiungi autorizzazioni per aggiungere nuove autorizzazioni al ruolo.
    2. Deseleziona le autorizzazioni per rimuovere le autorizzazioni dal ruolo.
  7. Fai clic su Aggiorna per salvare il ruolo modificato.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles update per aggiornare i ruoli personalizzati. Puoi utilizzare questo comando in due modi:

    • Fornendo un file YAML che contiene la definizione del ruolo aggiornata

    • Può utilizzare i flag per specificare la definizione del ruolo aggiornata.

    Quando aggiorni un ruolo personalizzato, devi specificare se si applica a livello di organizzazione o di progetto utilizzando i flag --organization=ORGANIZATION_ID o --project=PROJECT_ID. Ogni esempio riportato di seguito crea un ruolo personalizzato a livello di progetto.

    Per aggiornare un ruolo personalizzato utilizzando un file YAML:

    Ottieni la definizione attuale del ruolo eseguendo uno dei seguenti comandi:

    • Per ottenere la definizione di un ruolo personalizzato a livello di organizzazione, esegui questo comando:

      gcloud iam roles describe ROLE_ID --organization=ORGANIZATION_ID
    • Per ottenere la definizione di un ruolo personalizzato a livello di progetto, esegui questo comando:

      gcloud iam roles describe ROLE_ID --project=PROJECT_ID

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo da aggiornare, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    Il comando describe restituisce la definizione del ruolo e include un valore etag che identifica in modo univoco la versione corrente del ruolo. È necessario specificare il valore etag nella definizione del ruolo aggiornata per garantire che eventuali modifiche simultanee ai ruoli non vengano sovrascritte.

    Il comando describe restituisce il seguente output:

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

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_DESCRIPTION è una breve descrizione del ruolo, ad esempio "My custom role description".

    • ETAG è l'identificatore univoco della versione corrente del ruolo, ad esempio BwVkBkbfr70=.

    • PERMISSION_1 e PERMISSION_2 sono autorizzazioni da includere nel ruolo personalizzato, ad esempio iam.roles.get. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    • ROLE_NAME è il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

    • LAUNCH_STAGE indica la fase di un ruolo nel ciclo di vita del lancio, ad esempio ALPHA, BETA o GA.

    • ROLE_TITLE è un titolo descrittivo per il ruolo, come "My Company Admin".

    Per aggiornare il ruolo, includi la definizione del ruolo come output in un file YAML o aggiorna il file YAML originale con il valore etag restituito.

    Considera il seguente file YAML di esempio, che contiene l'output del comando describe per un ruolo a livello di progetto e aggiunge due autorizzazioni Cloud Storage:

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

    Salva il file YAML ed esegui uno dei seguenti comandi:

    • Per aggiornare un ruolo a livello di organizzazione, esegui questo comando:

      gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
          --file=YAML_FILE_PATH
    • Per aggiornare un ruolo a livello di progetto, esegui questo comando:

      gcloud iam roles update ROLE_ID --project=PROJECT_ID \
          --file=YAML_FILE_PATH

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo da aggiornare, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project-id.

    • YAML_FILE_PATH è il percorso della posizione del file YAML che contiene la definizione del ruolo personalizzato aggiornata.

    Esempi

    L'esempio seguente mostra come aggiornare un ruolo a livello di organizzazione utilizzando un file YAML:

    gcloud iam roles update ROLE_ID --organization=ORGANIZATION_ID \
        --file=YAML_FILE_PATH
    • Per aggiornare un ruolo a livello di progetto, esegui questo comando:

      gcloud iam roles update ROLE_ID --project=PROJECT_ID \
          --file=YAML_FILE_PATH

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo da aggiornare, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    • YAML_FILE_PATH è il percorso della posizione del file YAML che contiene la definizione del ruolo personalizzato aggiornata.

    Esempi

    L'esempio seguente mostra come aggiornare un ruolo a livello di organizzazione utilizzando un file YAML:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come aggiornare un ruolo a livello di progetto utilizzando un file YAML:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

    Per aggiornare un ruolo personalizzato mediante i flag:

    Ogni parte della definizione di un ruolo può essere aggiornata utilizzando un flag corrispondente. Consulta l'argomento gcloud iam roles update per un elenco di tutti i possibili flag.

    Per aggiungere o rimuovere autorizzazioni, puoi utilizzare i seguenti flag:

    • --add-permissions=PERMISSIONS: aggiunge al ruolo una o più autorizzazioni separate da virgole. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    • --remove-permissions=PERMISSIONS: rimuove dal ruolo una o più autorizzazioni separate da virgole. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.

    In alternativa, puoi semplicemente specificare le nuove autorizzazioni utilizzando il flag --permissions=PERMISSIONS e fornendo un elenco separato da virgole di autorizzazioni per sostituire l'elenco esistente.

    Per aggiornare altre parti della definizione del ruolo, esegui uno dei seguenti comandi:

    • Per aggiornare un ruolo a livello di organizzazione, esegui questo comando:

      gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
          --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
          --stage=LAUNCH_STAGE
    • Per aggiornare un ruolo a livello di progetto, esegui questo comando:

      gcloud iam roles update ROLE_ID --project=PROJECT_ID \
          --title=ROLE_TITLE --description=ROLE_DESCRIPTION \
          --stage=LAUNCH_STAGE

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    • ROLE_TITLE è un titolo descrittivo per il ruolo, come "My Company Admin".

    • ROLE_DESCRIPTION è una breve descrizione del ruolo, ad esempio "My custom role description.".

    • LAUNCH_STAGE indica la fase di un ruolo nel ciclo di vita del lancio, ad esempio ALPHA, BETA o GA.

    Esempi

    L'esempio seguente mostra come aggiungere autorizzazioni a un ruolo a livello di organizzazione utilizzando i flag:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come aggiungere autorizzazioni a un ruolo a livello di progetto utilizzando i flag:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

    editRole(projectId, roleId, description);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def edit_role(
    name: str, project: str, title: str, description: str, permissions: str, stage: str
) -> dict:
    """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

REST

Il metodo roles.patch aggiorna un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

Obbligatorie:

  • RESOURCE_TYPE: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • RESOURCE_ID: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, come my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • ROLE_NAME: il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Consiglio:

  • ETAG: l'identificatore di una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche al ruolo.

Facoltativo (definisci uno o più dei seguenti valori):

  • ROLE_TITLE: il titolo leggibile per il ruolo. Ad esempio, My Company Admin.
  • ROLE_DESCRIPTION: una descrizione del ruolo. Ad esempio, "The company admin role allows company admins to access important resources".
  • PERMISSION_1 e PERMISSION_2: le autorizzazioni da includere nel ruolo. Ad esempio, storage.objects.update. Non puoi utilizzare caratteri jolly (*) nei nomi delle autorizzazioni.
  • LAUNCH_STAGE: l'attuale fase di lancio del ruolo. Questo campo può contenere uno dei seguenti valori: EAP, ALPHA, BETA, GA, DEPRECATED o DISABLED.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene una definizione abbreviata del ruolo che include il nome del ruolo, i campi che hai aggiornato e un etag che identifica la versione attuale del ruolo.

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

Disattivare un ruolo personalizzato

Puoi disattivare un ruolo personalizzato modificando la fase di avvio in DISABLED. Quando un ruolo è disabilitato, tutte le associazioni di ruoli correlate al ruolo sono disattivate, il che significa che la concessione del ruolo a un utente non ha alcun effetto.

Console

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Fai clic sull'elenco a discesa "Seleziona un progetto" nella parte superiore della pagina.

  3. Seleziona la tua organizzazione o il tuo progetto.

  4. Seleziona un ruolo personalizzato e fai clic su Disattiva.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles update per disabilitare un ruolo personalizzato impostando la fase di avvio su DISABLED.

    Come descritto nella scheda gcloud della sezione Modifica di un ruolo personalizzato esistente, puoi aggiornare un ruolo personalizzato esistente nei due modi seguenti:

    • Fornendo un file YAML che contiene la definizione del ruolo aggiornata

    • Può utilizzare i flag per specificare la definizione del ruolo aggiornata.

    Il modo più semplice per disabilitare un ruolo personalizzato esistente è utilizzare il flag --stage e impostarlo su DISABLED. Esegui uno dei seguenti comandi:

    • Per disabilitare un ruolo a livello di organizzazione, esegui questo comando:

      gcloud iam roles update ROLE_ID--organization=ORGANIZATION_ID \
          --stage=DISABLED
    • Per disabilitare un ruolo a livello di progetto, esegui questo comando:

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

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    Esempi

    L'esempio seguente mostra come disabilitare un ruolo a livello di organizzazione:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come disabilitare un ruolo a livello di progetto:

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

    Se il ruolo è stato aggiornato correttamente, l'output del comando è simile al seguente:

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

C++

Aggiorna il campo stage del ruolo su DISABLED.

C#

Aggiorna il campo stage del ruolo su DISABLED.

Go

Aggiorna il campo stage del ruolo su DISABLED.

Java

Aggiorna il campo stage del ruolo su DISABLED.

Python

Aggiorna il campo stage del ruolo su DISABLED.

REST

Il metodo roles.patch consente di modificare la fase di avvio di un ruolo personalizzato in DISABLED, il che disabilita il ruolo.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • RESOURCE_TYPE: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • RESOURCE_ID: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, come my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • ROLE_NAME: il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.
  • ETAG: l'identificatore di una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche al ruolo.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Elenco dei ruoli

Puoi elencare tutti i ruoli personalizzati creati nel progetto o nell'organizzazione.

Console

Nella console Google Cloud, vai alla pagina Ruoli.

Vai alla pagina Ruoli

Tutti i ruoli personalizzati per l'organizzazione o il progetto che hai selezionato sono elencati nella pagina.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles list per elencare i ruoli personalizzati e predefiniti per un progetto o un'organizzazione:

    • Per elencare i ruoli personalizzati a livello di organizzazione, esegui questo comando:

      gcloud iam roles list --organization=ORGANIZATION_ID
    • Per elencare i ruoli personalizzati a livello di progetto, esegui questo comando:

      gcloud iam roles list --project=PROJECT_ID

    Ogni valore segnaposto è descritto di seguito:

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    Per elencare i ruoli eliminati, puoi anche specificare il flag --show-deleted.

    Esegui questo comando per elencare i ruoli predefiniti:

    gcloud iam roles list

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

    listRoles(projectId);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def list_roles(project_id: str) -> None:
    """Lists roles."""

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

REST

Il metodo roles.list elenca tutti i ruoli personalizzati in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • RESOURCE_TYPE: il tipo di risorsa di cui vuoi gestire i ruoli personalizzati. Utilizza il valore projects o organizations.
  • RESOURCE_ID: l'ID progetto o l'ID organizzazione di cui vuoi gestire i ruoli personalizzati. Gli ID progetto sono stringhe alfanumeriche, come my-project. Gli ID organizzazione sono numerici, ad esempio 123456789012.
  • ROLE_VIEW: facoltativo. Le informazioni da includere per i ruoli restituiti. Per includere le autorizzazioni dei ruoli, imposta questo campo su FULL. Per escludere le autorizzazioni dei ruoli, imposta questo campo su BASIC. Il valore predefinito è BASIC.
  • PAGE_SIZE: facoltativo. Il numero di ruoli da includere nella risposta. Il valore predefinito è 300, mentre il valore massimo è 1000. Se il numero di ruoli è maggiore della dimensione della pagina, la risposta contiene un token di impaginazione che puoi utilizzare per recuperare la pagina dei risultati successiva.
  • NEXT_PAGE_TOKEN: facoltativo. Il token di impaginazione restituito in una risposta precedente da questo metodo. Se specificato, l'elenco dei ruoli inizierà dove è terminata la richiesta precedente.

Metodo HTTP e URL:

GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Eliminazione di un ruolo personalizzato

Puoi eliminare qualsiasi ruolo personalizzato nel progetto o nell'organizzazione.

Console

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Seleziona il ruolo che vuoi eliminare e fai clic su Elimina nella parte superiore della pagina.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles delete per eliminare un ruolo personalizzato:

    • Per eliminare un ruolo personalizzato a livello di organizzazione, esegui questo comando:

      gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID
    • Per eliminare un ruolo personalizzato a livello di progetto, esegui questo comando:

      gcloud iam roles delete ROLE_ID --project=PROJECT_ID

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    Il ruolo non sarà incluso in gcloud iam roles list, a meno che non sia incluso il flag --show-deleted. I ruoli eliminati sono indicati dal blocco deleted: true in una risposta list, ad esempio:

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

    deleteRole(projectId, roleId);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def delete_role(name: str, project: str) -> dict:
    """Deletes a role."""

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

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

REST

Il metodo roles.delete elimina un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • ROLE_NAME: il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene la definizione del ruolo che è stato eliminato.

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

Quando un ruolo viene eliminato, tutte le associazioni di ruoli che fanno riferimento a quel ruolo rimangono nei criteri di autorizzazione, ma non hanno alcun effetto. Puoi annullare l'eliminazione di un ruolo entro sette giorni. Durante questo periodo di 7 giorni, la console Google Cloud mostra che il ruolo è stato eliminato. Puoi anche elencare i ruoli eliminati in modo programmatico, ma vengono omessi per impostazione predefinita.

Dopo 7-14 giorni, è pianificata l'eliminazione definitiva del ruolo. A questo punto, il ruolo non verrà più conteggiato ai fini del limite di 300 ruoli personalizzati per organizzazione o di 300 ruoli personalizzati per progetto.

La procedura di eliminazione definitiva richiede 30 giorni. Durante questo periodo di 30 giorni, il ruolo e tutte le associazioni associate vengono rimossi definitivamente e non puoi creare un nuovo ruolo con lo stesso ID ruolo.

Dopo che il ruolo è stato eliminato definitivamente, fino a 44 giorni dopo la richiesta di eliminazione iniziale, puoi creare un nuovo ruolo utilizzando lo stesso ID ruolo.

Annullare l'eliminazione di un ruolo personalizzato

L'annullamento dell'eliminazione di un ruolo ne ripristina lo stato precedente.

L'eliminazione dei ruoli può essere annullata solo entro 7 giorni. Dopo 7 giorni, il ruolo può essere eliminato definitivamente in qualsiasi momento e tutte le associazioni di ruoli che fanno riferimento al ruolo vengono rimosse.

Console

  1. Nella console Google Cloud, vai alla pagina Ruoli.

    Vai alla pagina Ruoli

  2. Individua il ruolo che vuoi annullare, fai clic sull'icona Altro alla fine della riga e fai clic su Annulla eliminazione.

gcloud

  1. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Utilizza il comando gcloud iam roles undelete per annullare l'eliminazione di un ruolo personalizzato:

    • Per annullare l'eliminazione di un ruolo personalizzato a livello di organizzazione, esegui questo comando:

      gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID
    • Per annullare l'eliminazione di un ruolo personalizzato a livello di progetto, esegui questo comando:

      gcloud iam roles undelete ROLE_ID --project=PROJECT_ID

    Ogni valore segnaposto è descritto di seguito:

    • ROLE_ID è il nome del ruolo, ad esempio myCompanyAdmin.

    • ORGANIZATION_ID è l'ID numerico dell'organizzazione, ad esempio 123456789012.

    • PROJECT_ID è il nome del progetto, ad esempio my-project.

    Esempi

    L'esempio seguente mostra come annullare l'eliminazione di un ruolo personalizzato a livello di organizzazione:

    gcloud iam roles undelete myCompanyAdmin --organization=123456789012

    Se l'eliminazione del ruolo è andata a buon fine, l'output del comando è simile al seguente:

    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

    L'esempio seguente mostra come annullare l'eliminazione di un ruolo personalizzato a livello di progetto:

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

    Se l'eliminazione del ruolo è andata a buon fine, l'output del comando è simile al seguente:

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

C++

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C++.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

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

C#

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM C#.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Go.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Java.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.


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

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

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

    undeleteRole(projectId, roleId);
  }

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

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

Python

Per scoprire come installare e utilizzare la libreria client per IAM, vedi librerie client IAM. Per maggiori informazioni, consulta la documentazione di riferimento dell'API IAM Python.

Per eseguire l'autenticazione in IAM, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Prima di iniziare.

def undelete_role(name: str, project: str) -> dict:
    """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

REST

Il metodo roles.undelete annulla l'eliminazione di un ruolo personalizzato in un progetto o in un'organizzazione.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

  • ROLE_NAME: il nome completo del ruolo, inclusi eventuali prefissi organizations/, projects/ o roles/. Ad esempio, organizations/123456789012/roles/myCompanyAdmin.
  • ETAG: l'identificatore di una versione del ruolo. Includi questo campo per evitare di sovrascrivere altre modifiche al ruolo.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "etag": "ETAG"
}

Per inviare la richiesta, espandi una di queste opzioni:

La risposta contiene la definizione del ruolo che è stato annullato.

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

Passaggi successivi