Controllo dell'accesso all'API Conversational Analytics con IAM

Questo prodotto o funzionalità è soggetto ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

L'API Conversational Analytics utilizza Identity and Access Management (IAM) per controllo dell'accesso, il che ti consente di condividere gli agenti 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 service account) per concedere queste autorizzazioni.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per assegnare ruoli IAM 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.

Nota:i ruoli di base IAM potrebbero contenere anche autorizzazioni per assegnare ruoli IAM dell'API Conversational Analytics. Non devi concedere ruoli di base in un ambiente di produzione, ma puoi concederli in un ambiente di sviluppo o test.

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 agenti di dati. Questa sezione spiega come condividere gli agenti di dati assegnando ruoli IAM e descrive i ruoli IAM necessari per altre attività comuni degli utenti.

Come funziona la condivisione con gli agenti

Puoi concedere ruoli a livello di progetto per fornire autorizzazioni per tutti gli agenti all'interno di un progetto. Per controllare l'accesso a un agente specifico, un proprietario dell'agente (un principal con il ruolo Proprietario dell'agente di analisi dei dati Gemini) può modificare la policy IAM dell'agente in modo programmatico.

Importante:i ruoli IAM dell'API Conversational Analytics controllano l'accesso agli agenti e alle loro configurazioni, non alle origini dati sottostanti. Quando un utente interagisce con un agente, l'API esegue query sull'origine dati connessa (ad esempio Looker o BigQuery) utilizzando le credenziali dell'utente. Pertanto, per chattare correttamente con un agente, un utente deve disporre delle seguenti autorizzazioni:

• Un ruolo IAM API Conversational Analytics appropriato per accedere all'agente
• Autorizzazioni sufficienti nell'origine dati (ad esempio in Looker o BigQuery) per accedere ai dati su cui viene eseguita la query

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

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 i relativi criteri IAM e concede i seguenti ruoli ai membri del team:

• Gemini Data Analytics Data Agent Editor: il proprietario dell'agente concede questo ruolo ai junior data analyst. Questo ruolo consente agli analisti junior di modificare la configurazione dell'agente e di chattare con lui.
• Utente dell'agente Gemini Data Analytics: 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à comuni degli utenti

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

Crea nuovi agenti dati

Assegna il ruolo Gemini Data Analytics Data Agent Creator agli utenti responsabili della creazione di nuovi agenti dati all'interno di un progetto.

Condividere agenti

Assegna il ruolo Proprietario agente dati Gemini Data Analytics agli utenti che devono condividere gli agenti con altre entità gestendo le autorizzazioni dell'agente.

Gestire le autorizzazioni dell'agente

Assegna il ruolo Proprietario agente dati Gemini Data Analytics agli utenti che devono condividere gli agenti con altri utenti gestendo le autorizzazioni dell'agente o che hanno bisogno del massimo livello di controllo su un agente, inclusa la possibilità di eliminarli. Quando un utente crea un agente, il sistema concede automaticamente questo ruolo all'utente per l'agente specifico.

Modificare le configurazioni dell'agente

Assegna il ruolo Editor agente dati Gemini Data Analytics agli utenti che modificano la configurazione di un agente, ad esempio il contesto o i mapping delle origini dati. Questi utenti non dispongono delle autorizzazioni per condividere o eliminare l'agente.

Chatta con gli agenti

Assegna il ruolo Utente agente dati Gemini Data Analytics a utenti o applicazioni che interagiscono principalmente con gli agenti ponendo domande e ricevendo risposte.

Visualizza le configurazioni dell'agente

Assegna il ruolo Visualizzatore agente dati Gemini Data Analytics agli utenti che hanno bisogno dell'accesso di sola lettura per visualizzare le configurazioni dell'agente.

Chattare utilizzando il contesto in linea

Assegna il ruolo Gemini Data Analytics Stateless Chat User a utenti o applicazioni che interagiscono con l'API in modalità stateless, in cui l'utente fornisce tutto il contesto della conversazione all'interno di ogni richiesta.

Ruoli predefiniti per l'API Conversational Analytics

Nota :la concessione dell'accesso a un agente dati non consente di visualizzare le conversazioni avviate da altri utenti. Ad esempio, l'elenco delle conversazioni per un agente restituisce solo le conversazioni create dall'utente corrente.

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

Ruolo	Autorizzazioni
Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) Concede a un'entità l'autorizzazione per creare nuove risorse dell'agente di dati in un progetto specifico. Quando un principal crea un agente, il sistema gli concede automaticamente il ruolo dataAgentOwner per l'agente specifico.	geminidataanalytics.dataAgents.create
Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) Concede a un principal il controllo completo del ciclo di vita di qualsiasi agente all'interno del progetto, inclusa la condivisione e l'eliminazione degli agenti. Questo ruolo è destinato ai principal attendibili che possono gestire la condivisione degli agenti. Questo ruolo eredita tutte le autorizzazioni dei ruoli dataAgentEditor, dataAgentUser e dataAgentViewer. Un'entità con questo ruolo può condividere ed eliminare agenti.	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 agenti esistenti. Questo ruolo eredita tutte le autorizzazioni dei 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 a chattare con gli agenti specifici a cui è stato concesso l'accesso all'entità. Questo ruolo eredita tutte le autorizzazioni del ruolo dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) Concede a un principal l'autorizzazione di sola lettura per elencare e visualizzare le configurazioni degli agent. Questo ruolo non consente di chattare con gli agenti.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get
Gemini Data Analytics Stateless Chat User (roles/geminidataanalytics.dataAgentStatelessUser) Concede a un principal l'autorizzazione a chiamare l'API Chat in modalità stateless. Con la chat stateless, il contesto viene fornito direttamente nella richiesta anziché essere salvato in modo esplicito nella configurazione dell'agente durante la creazione.	geminidataanalytics.chat

Concedi 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 assegna a un'entità le stesse autorizzazioni per tutti gli agenti del progetto, mentre l'impostazione del criterio 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 ruoli per tutti gli agenti di un progetto

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

console

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

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

   Vai a IAM

2. Fai clic su Concedi l'accesso.

3. Nel campo Nuove entità, inserisci l'indirizzo email dell'utente, del gruppo o del account di servizio.

4. Nel menu Seleziona un ruolo, filtra per Gemini Data Analytics per visualizzare i ruoli IAM disponibili per l'API Conversational Analytics.

5. Seleziona il ruolo appropriato, ad esempio Utente agente dati Gemini Data Analytics.

6. Fai clic su Salva.

gcloud

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

1. Accedi a Google Cloud e imposta il tuo progetto:

gcloud auth login
gcloud config set project project_id

1. (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 nel seguente modo:

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

1. 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 questo 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: il tuo ID progetto Google Cloud .
• user_email: l'indirizzo email dell'utente, ad esempio [e-mail].
• service_account_email: l'indirizzo email del account di servizio, ad esempio [e-mail].
• gda_grantable_role: il ruolo IAM API Conversational Analytics specifico che vuoi concedere, ad esempio geminidataanalytics.dataAgentCreator.

Concedere ruoli per un agente specifico

Per gestire l'accesso per un agente dati specifico, devi modificare a livello di programmazione la policy di autorizzazione dell'agente. Questo processo segue un pattern di lettura, modifica e scrittura standard, in cui leggi il criterio corrente, lo modifichi e lo riscrivi.

Importante: il metodo setIamPolicy sostituisce qualsiasi criterio esistente sull'agente. Per conservare le autorizzazioni esistenti quando concedi nuovi ruoli, devi prima chiamare getIAMPolicy per recuperare il criterio esistente, modificarlo e poi passare l'oggetto criterio aggiornato nella chiamata a setIamPolicy.

Gli esempi riportati di seguito mostrano i corpi delle richieste per ottenere e impostare le policy IAM per un agente dati.

HTTP

Per ottenere 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: il tuo ID progetto Google Cloud .
• AGENT_ID: L'ID dell'agente dati per cui ottenere o impostare la policy.
• ROLE: il ruolo da concedere, ad esempio roles/geminidataanalytics.dataAgentUser.
• EMAIL: l'indirizzo email dell'utente, ad esempio [e-mail].

Per esempi completi, vedi Recuperare il criterio IAM per un agente dati e Impostare il criterio IAM per un agente dati.

SDK Python

Per ottenere la policy esistente per un agente, utilizza il metodo get_iam_policy, come 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, come 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
)

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto Google Cloud .
• AGENT_ID: L'ID dell'agente dati per cui ottenere o impostare la policy.
• ROLE: il ruolo da concedere, ad esempio roles/geminidataanalytics.dataAgentUser.
• EMAIL: l'indirizzo email dell'utente, ad esempio [e-mail].

Per esempi completi, vedi Recuperare il criterio IAM per un agente dati e Impostare il criterio IAM per un agente dati.