Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Controllo dell'accesso all'API Conversational Analytics con IAM

L'API Conversational Analytics utilizza Identity and Access Management (IAM) per controllo dell'accesso, che ti consente di condividere gli agent di dati e controllare chi ha l'autorizzazione per crearli, gestirli e interagire con loro. Questa pagina descrive i ruoli IAM predefiniti che puoi assegnare alle entità (come utenti, gruppi e account di servizio) per concedere queste autorizzazioni.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per assegnare i ruoli IAM dell'API Conversational Analytics, chiedi all'amministratore di concederti il ruolo IAM Project IAM Admin (roles/resourcemanager.projectIamAdmin) nel progetto in cui è abilitata l'API Conversational Analytics. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Panoramica dei ruoli IAM dell'API Conversational Analytics

I ruoli IAM predefiniti per l'API Conversational Analytics forniscono un controllo granulare su chi può creare, gestire e interagire con gli agent di dati. Questa sezione spiega come condividere gli agent di dati assegnando i ruoli IAM e descrive i ruoli IAM necessari per altre attività utente comuni.

Puoi concedere i ruoli a livello di progetto per fornire le autorizzazioni per tutti gli agent all'interno di un progetto. Per controllare l'accesso a un agente specifico, un proprietario dell'agente (un'entità con il ruolo Gemini Data Analytics Data Agent Owner) può modificare la policy IAM dell'agente a livello di programmazione.

Il seguente diagramma mostra come un proprietario dell'agente può gestire l'accesso a un agente specifico:

Il proprietario di un agente concede i ruoli Editor agente dati e Utente agente dati ad altri utenti.

In questo scenario, un analista di dati senior con il ruolo Gemini Data Analytics Data Agent Creator crea un agente. Quando un utente crea un agente, gli viene automaticamente concesso il ruolo Gemini Data Analytics Data Agent Owner per quell'agente. In qualità di proprietario dell'agente, l'analista di dati senior gestisce l'accesso all'agente impostando la relativa policy IAM e concede i seguenti ruoli ai membri del team:

Gemini Data Analytics Data Agent Editor: il proprietario dell'agente concede questo ruolo agli analisti di dati junior. Questo ruolo consente agli analisti junior di modificare la configurazione dell'agente e di chattare con l'agente.
Gemini Data Analytics Data Agent User: il proprietario dell'agente concede questo ruolo ai membri del team che non devono essere in grado di modificare la configurazione dell'agente. Questo ruolo consente ai membri del team di chattare con l'agente.

Ruoli richiesti per le attività utente comuni

Per aiutarti a decidere quali ruoli assegnare, considera le seguenti attività utente comuni:

Crea nuovi agent di dati: Assegna il ruolo Gemini Data Analytics Data Agent Creator agli utenti responsabili della creazione di nuovi agent di dati all'interno di un progetto.
Condividi gli agent: Assegna il ruolo Gemini Data Analytics Data Agent Owner agli utenti che devono condividere gli agent con altre entità gestendo le autorizzazioni degli agent.
Gestisci le autorizzazioni degli agent: Assegna il ruolo Gemini Data Analytics Data Agent Owner agli utenti che devono condividere gli agent con altri utenti gestendo le autorizzazioni degli agent o che hanno bisogno del livello di controllo più elevato su un agente, inclusa la possibilità di eliminare gli agent. Quando un utente crea un agente, il sistema gli concede automaticamente questo ruolo per l'agente specifico.
Modifica le configurazioni degli agent: Assegna il ruolo Gemini Data Analytics Data Agent Editor agli utenti che modificano la configurazione di un agente, ad esempio il contesto o i mapping delle origini dati. Questi utenti non hanno le autorizzazioni per condividere o eliminare l'agente.
Chatta con gli agent: Assegna il ruolo Gemini Data Analytics Data Agent User agli utenti o alle applicazioni che interagiscono principalmente con gli agent ponendo domande e ricevendo risposte.
Visualizza le configurazioni degli agent: Assegna il ruolo Gemini Data Analytics Data Agent Viewer agli utenti che hanno bisogno dell'accesso in sola lettura per visualizzare le configurazioni degli agent.
Chatta utilizzando il contesto incorporato: Assegna il ruolo Gemini Data Analytics Stateless Chat User agli utenti o alle applicazioni che interagiscono con l'API in modalità senza stato, in cui l'utente fornisce tutto il contesto per la conversazione all'interno di ogni richiesta.
Esegui query sui dati utilizzando il linguaggio naturale: Assegna il ruolo Gemini Data Analytics Query Data User agli utenti o alle applicazioni che devono utilizzare il linguaggio naturale per eseguire query sui dati e creare applicazioni di dati. Questo ruolo si applica solo ai database Cloud, ovvero AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL.

Ruoli predefiniti per l'API Conversational Analytics

La tabella seguente descrive i ruoli predefiniti per l'API Conversational Analytics. Se i ruoli predefiniti non forniscono l'insieme di autorizzazioni che ti interessa, puoi anche creare i tuoi ruoli personalizzati.

Ruolo	Autorizzazioni
Gemini Data Analytics Data Agent Creator (`roles/geminidataanalytics.dataAgentCreator`) Concede a un'entità l'autorizzazione per creare nuove risorse di agent di dati in un progetto specifico. Quando un'entità crea un agente, il sistema le concede automaticamente il ruolo `dataAgentOwner` per l'agente specifico.	`geminidataanalytics.dataAgents.create`
Gemini Data Analytics Data Agent Owner (`roles/geminidataanalytics.dataAgentOwner`) Concede a un'entità il controllo completo sul ciclo di vita di qualsiasi agente all'interno del progetto, inclusa la condivisione e l'eliminazione degli agent. Questo ruolo è destinato alle entità attendibili che possono gestire la condivisione degli agent. Questo ruolo eredita tutte le autorizzazioni dai ruoli `dataAgentEditor`, `dataAgentUser` e `dataAgentViewer`. Un'entità con questo ruolo può condividere ed eliminare gli agent.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Gemini Data Analytics Data Agent Editor (`roles/geminidataanalytics.dataAgentEditor`) Concede l'autorizzazione per modificare e gestire le configurazioni degli agent esistenti. Questo ruolo eredita tutte le autorizzazioni dai ruoli `dataAgentUser` e `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Gemini Data Analytics Data Agent User (`roles/geminidataanalytics.dataAgentUser`) Concede l'autorizzazione per chattare con gli agent specifici a cui è stato concesso l'accesso all'entità. Questo ruolo eredita tutte le autorizzazioni dal ruolo `dataAgentViewer`.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Gemini Data Analytics Data Agent Viewer (`roles/geminidataanalytics.dataAgentViewer`) Concede a un'entità l'autorizzazione di sola lettura per elencare e visualizzare le configurazioni degli agent. Questo ruolo non consente di chattare con gli agent.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Gemini Data Analytics Stateless Chat User (`roles/geminidataanalytics.dataAgentStatelessUser`) Concede a un'entità l'autorizzazione per chiamare l'API Chat in modalità senza stato. Con la chat senza stato, il contesto viene fornito direttamente nella richiesta anziché essere salvato esplicitamente nella configurazione dell'agente durante la creazione.	`geminidataanalytics.chat`
Gemini Data Analytics Query Data User (`roles/geminidataanalytics.queryDataUser`) Concede a un'entità l'autorizzazione per utilizzare il linguaggio naturale per eseguire query sui dati e creare applicazioni di dati utilizzando l'API QueryData. Questo ruolo si applica solo ai database Cloud, ovvero AlloyDB, GoogleSQL per Spanner, Cloud SQL e Cloud SQL per PostgreSQL.	`geminidataanalytics.locations.queryData`

Concedi i ruoli IAM

Puoi concedere i ruoli IAM dell'API Conversational Analytics a livello di progetto o per un agente specifico. La concessione di un ruolo a livello di progetto conferisce a un'entità le stesse autorizzazioni per tutti gli agent del progetto, mentre l'impostazione della policy su un agente specifico fornisce un controllo più granulare.

I ruoli IAM predefiniti per l'API Conversational Analytics fanno parte del servizio geminidataanalytics. I nomi tecnici di questi ruoli seguono il pattern roles/geminidataanalytics.ROLE_NAME. Nella Google Cloud console puoi trovare questi ruoli filtrando per il servizio Gemini Data Analytics.

Concedi i ruoli per tutti gli agent di un progetto

Utilizza la Google Cloud console o la Google Cloud CLI per concedere i ruoli per un intero progetto.

console

Per concedere un ruolo a un'entità nella Google Cloud console, completa i seguenti passaggi:

Nella Google Cloud console vai alla pagina IAM.

Vai a IAM
Fai clic su Concedi l'accesso.
Nel campo Nuove entità , inserisci l'indirizzo email dell'utente, del gruppo o del account di servizio.
Nel menu Seleziona un ruolo, filtra per Gemini Data Analytics per visualizzare i ruoli IAM disponibili per l'API Conversational Analytics.
Seleziona il ruolo appropriato, ad esempio Gemini Data Analytics Data Agent User.
Fai clic su Salva.

gcloud

Per concedere i ruoli utilizzando la gcloud CLI, completa i seguenti passaggi:

Accedieimposta il progetto: Google Cloud

gcloud auth login
gcloud config set project project_id

(Facoltativo) Per elencare i ruoli IAM dell'API Conversational Analytics che puoi concedere per il tuo progetto, utilizza il comando gcloud iam list-grantable-roles come segue:

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"

Concedi un ruolo a un'entità utilizzando il comando gcloud projects add-iam-policy-binding.

Per concedere un ruolo a un utente, utilizza il seguente comando:

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

Per assegnare un ruolo a un account di servizio, utilizza il seguente comando:

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

Nelle istruzioni precedenti, sostituisci i valori di esempio come segue:

project_id: l' Google Cloud ID progetto.
user_email: l'indirizzo email dell'utente, ad esempio test-user@example.com.
service_account_email: l'indirizzo email del account di servizio, ad esempio test-sa@example.com.
gda_grantable_role: il ruolo IAM specifico dell'API Conversational Analytics che vuoi concedere, ad esempio geminidataanalytics.dataAgentCreator.

Concedi i ruoli per un agente specifico

Per gestire l'accesso a un agente di dati specifico, devi modificare la policy di autorizzazione dell'agente a livello di programmazione. Questa procedura segue un pattern standard di lettura, modifica e scrittura in cui leggi la policy corrente, la modifichi e poi la riscrivi.

Gli esempi seguenti mostrano i corpi delle richieste per recuperare e impostare le policy IAM per un agente di dati.

HTTP

Per recuperare la policy esistente per un agente, invia una richiesta POST all'endpoint :getIamPolicy con il seguente corpo della richiesta:

{
  "resource": "projects/project_id/locations/global/dataAgents/agent_id"
}

Per impostare la policy per un agente, invia una richiesta POST all'endpoint :setIamPolicy con il seguente corpo della richiesta:

{
  "policy": {
    "bindings": [
      {
        "role": "role",
        "members": [
          "user:email"
        ]
      }
    ]
  }
}

Sostituisci quanto segue:

project_id: l' Google Cloud ID progetto.
agent_id: l'ID dell'agente di dati per il quale recuperare o impostare la policy.
role: il ruolo da concedere, ad esempio roles/geminidataanalytics.dataAgentUser.
email: l'indirizzo email dell'utente, ad esempio test-user@example.com.

Per esempi completi, vedi Recupera la policy IAM per un agente di dati e Imposta la policy IAM per un agente di dati.

SDK Python

Per recuperare la policy esistente per un agente, utilizza il metodo get_iam_policy, ad esempio nella seguente richiesta di esempio:

resource = "projects/project_id/locations/global/dataAgents/agent_id"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

Per impostare la policy per un agente, utilizza il metodo set_iam_policy, ad esempio nella seguente richiesta di esempio:

resource = "projects/project_id/locations/global/dataAgents/agent_id"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="role",
            members=["user:email"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)