IAM-Rollen und ‑Berechtigungen für die Conversational Analytics API zuweisen

Dieses Produkt oder diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und ‑Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Die Conversational Analytics API verwendet Identity and Access Management (IAM), um den Zugriff zum Erstellen, Verwalten und Interagieren mit Daten-Agents zu steuern. Mit IAM weisen Sie Hauptkonten (z. B. Nutzer, Gruppen und Dienstkonten) Rollen zu, um ihnen Berechtigungen zu erteilen. Jede Rolle umfasst eine oder mehrere Berechtigungen, die festlegen, welche Aktionen ein Hauptkonto ausführen kann.

Auf dieser Seite werden die vordefinierten IAM-Rollen für die Conversational Analytics API beschrieben. Sie können diese IAM-Rollen in der Google Cloud Console für das Projekt zuweisen, in dem die Conversational Analytics API aktiviert ist. Eine ausführliche Anleitung finden Sie unter Rollen über die Google Cloud Console zuweisen. Sie können auch die Google Cloud CLI verwenden, um Rollen zuzuweisen, wie unter IAM-Rollen zuweisen beschrieben.

Vorbereitung

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Project IAM Admin (roles/resourcemanager.projectIamAdmin) für das Projekt zuzuweisen, in dem die Conversational Analytics API aktiviert ist. So erhalten Sie die Berechtigungen, die Sie zum Zuweisen von IAM-Rollen für die Conversational Analytics API benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Hinweis: Einfache IAM-Rollen können auch Berechtigungen zum Zuweisen von IAM-Rollen für die Conversational Analytics API enthalten. In einer Produktionsumgebung sollten Sie keine einfachen Rollen zuweisen, Sie können sie aber in einer Entwicklungs- oder Testumgebung gewähren.

Übersicht über IAM-Rollen für die Conversational Analytics API

Die Conversational Analytics API bietet eine Reihe vordefinierter IAM-Rollen. Mit diesen Rollen können Sie Berechtigungen für Aufgaben wie das Erstellen und Bearbeiten von Agents, das Teilen und Verwalten von Agents, das Ansehen von und Chatten mit Agents sowie die Verwendung der API in einem zustandslosen Chatmodus gewähren.

Hinweis: Mit IAM-Rollen für die Conversational Analytics API wird der Zugriff auf Agents und ihre Konfigurationen gesteuert, nicht jedoch der auf die zugrunde liegenden Daten selbst.

Die vordefinierten IAM-Rollen für die Conversational Analytics API sind Teil des Dienstes geminidataanalytics. Die technischen Namen für diese Rollen folgen dem Muster roles/geminidataanalytics.ROLE_NAME. In der Google Cloud Console können Sie nach diesen Rollen filtern, indem Sie nach dem Dienst Gemini Data Analytics suchen.

Sie können IAM-Rollen für die Conversational Analytics API auf Projektebene zuweisen.

Erforderliche Rollen für häufige Nutzeraufgaben

Berücksichtigen Sie die folgenden gängigen Nutzeraufgaben, um zu entscheiden, welche Rollen einem Hauptkonto zugewiesen werden sollen.

Neue Daten-Agents erstellen

Weisen Sie Nutzern, die für das Erstellen neuer Daten-Agents in einem Projekt verantwortlich sind, die Rolle Gemini Data Analytics Data Agent Creator zu.

Agent-Berechtigungen verwalten

Weisen Sie Nutzern, die die höchste Kontrollstufe für einen Agent benötigen, die Rolle Gemini Data Analytics Data Agent Owner zu. Dazu gehört die Möglichkeit, Berechtigungen zu verwalten und Agents freizugeben oder zu löschen. Wenn ein Nutzer einen Agent erstellt, wird ihm diese Rolle automatisch für den jeweiligen Agent zugewiesen.

Agent-Konfigurationen bearbeiten

Weisen Sie Nutzern, die die Konfiguration eines Agents ändern, z. B. den Kontext oder die Zuordnungen von Datenquellen, die Rolle Gemini Data Analytics Data Agent Editor zu. Diese Nutzer haben keine Berechtigungen, um den Agent freizugeben oder zu löschen.

Mit Agents chatten

Weisen Sie die Rolle Gemini Data Analytics Data Agent User Nutzern oder Anwendungen zu, die hauptsächlich über Fragen und Antworten mit Agents interagieren.

Agent-Konfigurationen ansehen

Weisen Sie Nutzern, die schreibgeschützten Zugriff zum Ansehen von Agent-Konfigurationen benötigen, die Rolle Gemini Data Analytics Data Agent Viewer zu.

Mit Inline-Kontext chatten

Weisen Sie Nutzern oder Anwendungen, die in einem zustandslosen Modus mit der API interagieren, die Rolle Gemini Data Analytics Stateless Chat User zu. In diesem Modus stellt der Nutzer den gesamten Kontext für die Unterhaltung in jeder Anfrage bereit.

Eine Liste der vordefinierten Rollen und der darin enthaltenen Berechtigungen finden Sie unter Vordefinierte Rollen für die Conversational Analytics API.

Vordefinierte Rollen für die Conversational Analytics API

Hinweis: Wenn Sie einem Nutzer Zugriff auf einen Daten-Agent gewähren, kann er keine Unterhaltungen sehen, die von anderen Nutzern gestartet wurden. Wenn Sie beispielsweise Unterhaltungen für einen Agent auflisten, werden nur Unterhaltungen zurückgegeben, die vom aktuellen Nutzer erstellt wurden.

In der folgenden Tabelle werden die vordefinierten Rollen für die Conversational Analytics API beschrieben. Wenn die vordefinierten Rollen nicht die gewünschten Berechtigungen bieten, können Sie auch eigene benutzerdefinierte Rollen erstellen.

Rolle	Berechtigungen
Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) Erteilt einem Hauptkonto die Berechtigung, neue Daten-Agent-Ressourcen in einem bestimmten Projekt zu erstellen. Wenn ein Hauptkonto einen Agent erstellt, wird diesem Hauptkonto automatisch die Rolle dataAgentOwner für den jeweiligen Agent zugewiesen.	geminidataanalytics.dataAgents.create
Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) Gewährt einem Hauptkonto die vollständige Kontrolle über den Lebenszyklus eines beliebigen Agents im Projekt, einschließlich des Freigebens und Löschens von Agents. Diese Rolle ist für vertrauenswürdige Hauptkonten vorgesehen, die die gemeinsame Nutzung von Agents verwalten können. Diese Rolle erbt alle Berechtigungen der Rollen dataAgentEditor, dataAgentUser und dataAgentViewer. Ein Hauptkonto mit dieser Rolle kann Agents freigeben und löschen.	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) Gewährt die Berechtigung, vorhandene Agent-Konfigurationen zu ändern und zu verwalten. Diese Rolle übernimmt alle Berechtigungen der Rollen dataAgentUser und dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat geminidataanalytics.dataAgents.update
Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser) Gewährt die Berechtigung, mit den spezifischen Agents zu chatten, auf die das Hauptkonto Zugriff hat. Diese Rolle übernimmt alle Berechtigungen der Rolle dataAgentViewer.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get geminidataanalytics.dataAgents.chat
Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) Gewährt einem Hauptkonto nur Lesezugriff zum Auflisten und Aufrufen von Agent-Konfigurationen. Diese Rolle berechtigt nicht zum Chatten mit Agents.	geminidataanalytics.dataAgents.list geminidataanalytics.dataAgents.get
Gemini Data Analytics Stateless Chat User (roles/geminidataanalytics.dataAgentStatelessUser) Erteilt einem Hauptkonto die Berechtigung, die Chat API im zustandslosen Modus aufzurufen. Beim zustandslosen Chat wird der Kontext direkt in der Anfrage angegeben, anstatt bei der Erstellung explizit in der Agent-Konfiguration gespeichert zu werden.	geminidataanalytics.chat

IAM-Rollen zuweisen

Sie können Hauptkonten IAM-Rollen für die Conversational Analytics API über die Google Cloud Console oder die Google Cloud CLI zuweisen.

Console

So weisen Sie einem Hauptkonto in der Google Cloud Console eine Rolle zu:

1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

   IAM aufrufen

2. Klicken Sie auf Zugriff erlauben.

3. Geben Sie im Feld Neue Hauptkonten die E-Mail-Adresse des Nutzers, der Gruppe oder des Dienstkontos ein.

4. Filtern Sie im Menü Rolle auswählen nach Gemini Data Analytics, um die verfügbaren IAM-Rollen für die Conversational Analytics API aufzurufen.

5. Wählen Sie die entsprechende Rolle aus, z. B. Gemini Data Analytics Data Agent User.

6. Klicken Sie auf Speichern.

gcloud

So weisen Sie Rollen mit der gcloud CLI zu:

1. Melden Sie sich in Google Cloud an und legen Sie Ihr Projekt fest:

gcloud auth login
gcloud config set project project_id

1. Optional können Sie mit dem Befehl gcloud iam list-grantable-roles die IAM-Rollen für die Conversational Analytics API auflisten, die Sie für Ihr Projekt zuweisen können:

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

1. Weisen Sie einem Hauptkonto mithilfe des Befehls gcloud projects add-iam-policy-binding eine Rolle zu.

• Verwenden Sie den folgenden Befehl, um einem Nutzer eine Rolle zuzuweisen:

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

• Verwenden Sie den folgenden Befehl, um einem Dienstkonto eine Rolle zuzuweisen:

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

Ersetzen Sie im vorherigen Beispiel die Beispielwerte so:

• project_id: Die Projekt-ID von Google Cloud
• user_email: Die E-Mail-Adresse des Nutzers, z. B. [e-mail].
• service_account_email: Die E-Mail-Adresse des Dienstkontos, z. B. [e-mail].
• gda_grantable_role: Die spezifische IAM-Rolle für die Conversational Analytics API, die Sie zuweisen möchten, z. B. geminidataanalytics.dataAgentCreator.