Diese Seite wurde von der Cloud Translation API übersetzt.

Zugriffssteuerung für die Conversational Analytics API mit IAM

Die Conversational Analytics API verwendet Identity and Access Management (IAM) für die Zugriffssteuerung. So können Sie Daten-Agents freigeben und steuern, wer die Berechtigung hat, sie zu erstellen, zu verwalten und mit ihnen zu interagieren. Auf dieser Seite werden die vordefinierten IAM-Rollen beschrieben, die Sie Hauptkonten (z. B. Nutzern, Gruppen und Dienstkonten) zuweisen können, um ihnen diese Berechtigungen zu erteilen.

Hinweise

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.

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

Vordefinierte IAM-Rollen für die Conversational Analytics API ermöglichen eine detaillierte Steuerung darüber, wer Daten-Agents erstellen, verwalten und mit ihnen interagieren kann. In diesem Abschnitt wird erläutert, wie Sie Daten-Agents freigeben, indem Sie IAM-Rollen zuweisen. Außerdem werden die IAM-Rollen beschrieben, die für andere häufige Nutzeraufgaben erforderlich sind.

Sie können Rollen auf Projektebene zuweisen, um Berechtigungen für alle Agents in einem Projekt zu erteilen. Wenn Sie den Zugriff auf einen bestimmten Agent steuern möchten, kann ein Agent-Inhaber (ein Prinzipal mit der Rolle Gemini Data Analytics Data Agent Owner) die IAM-Richtlinie dieses Agents programmatisch ändern.

Das folgende Diagramm zeigt, wie ein Agent-Inhaber den Zugriff auf einen bestimmten Agent verwalten kann:

Ein Agent-Inhaber weist anderen Nutzern die Rollen „Data Agent Editor“ und „Data Agent User“ zu.

In diesem Szenario erstellt eine Senior Data Analyst mit der Rolle Gemini Data Analytics Data Agent Creator einen Agent. Wenn ein Nutzer einen Agent erstellt, wird ihm automatisch die Rolle Gemini Data Analytics Data Agent Owner für diesen Agent zugewiesen. Als Inhaber des Agents verwaltet der Senior Data Analyst den Zugriff auf den Agent, indem er die IAM-Richtlinie festlegt und den Teammitgliedern die folgenden Rollen zuweist:

Gemini Data Analytics Data Agent Editor: Der Agent-Inhaber weist diese Rolle Junior Data Analysts zu. Mit dieser Rolle können Junior-Analysten die Konfiguration des Agents bearbeiten und mit dem Agenten chatten.
Gemini Data Analytics Data Agent User: Der Agent-Inhaber weist diese Rolle Teammitgliedern zu, die die Konfiguration des Agents nicht bearbeiten müssen. Mit dieser Rolle können diese Teammitglieder mit dem Agenten chatten.

Erforderliche Rollen für häufige Nutzeraufgaben

Berücksichtigen Sie die folgenden gängigen Nutzeraufgaben, um zu entscheiden, welche Rollen 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.
KI‑Agenten freigeben: Weisen Sie Nutzern, die Agents für andere Hauptkonten freigeben müssen, indem sie Agent-Berechtigungen verwalten, die Rolle Gemini Data Analytics Data Agent Owner zu.
Agent-Berechtigungen verwalten: Weisen Sie Nutzern, die Agents für andere Nutzer freigeben müssen, indem sie Agent-Berechtigungen verwalten, oder 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, Agents 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.

Vordefinierte Rollen für die Conversational Analytics API

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 IAM-Rollen für die Conversational Analytics API auf Projektebene oder für einen bestimmten Agent gewähren. Wenn Sie einem Hauptkonto eine Rolle auf Projektebene zuweisen, erhält es dieselben Berechtigungen für alle Agents in diesem Projekt. Wenn Sie die Richtlinie für einen bestimmten Agent festlegen, haben Sie mehr Kontrolle.

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.

Rollen für alle Agents in einem Projekt zuweisen

Verwenden Sie die Google Cloud Console oder die Google Cloud CLI, um Rollen für ein gesamtes Projekt zuzuweisen.

Console

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

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

IAM aufrufen
Klicken Sie auf Zugriff erlauben.
Geben Sie im Feld Neue Hauptkonten die E-Mail-Adresse des Nutzers, der Gruppe oder des Dienstkontos ein.
Filtern Sie im Menü Rolle auswählen nach Gemini Data Analytics, um die verfügbaren IAM-Rollen für die Conversational Analytics API aufzurufen.
Wählen Sie die entsprechende Rolle aus, z. B. Gemini Data Analytics Data Agent User.
Klicken Sie auf Speichern.

gcloud

So weisen Sie Rollen mit der gcloud CLI zu:

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

gcloud auth login
gcloud config set project project_id

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"

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. test-user@gmail.com.
service_account_email: Die E-Mail-Adresse des Dienstkontos, z. B. test-proj@example.domain.com.
gda_grantable_role: Die spezifische IAM-Rolle für die Conversational Analytics API, die Sie zuweisen möchten, z. B. geminidataanalytics.dataAgentCreator.

Rollen für einen bestimmten Agent zuweisen

Wenn Sie den Zugriff für einen bestimmten KI-Datenagenten verwalten möchten, müssen Sie die Zulassungsrichtlinie dieses Agenten programmatisch ändern. Dieser Prozess folgt dem Standardmuster Lesen-Ändern-Schreiben. Dabei lesen Sie die aktuelle Richtlinie, ändern sie und schreiben sie dann zurück.

Die folgenden Beispiele zeigen die Anfragetexte zum Abrufen und Festlegen von IAM-Richtlinien für einen KI-Datenagenten.

HTTP

Wenn Sie die vorhandene Richtlinie für einen Agent abrufen möchten, senden Sie eine POST-Anfrage an den :getIamPolicy-Endpunkt mit dem folgenden Anfragetext:

{
  "resource": "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
}

Wenn Sie die Richtlinie für einen Agent festlegen möchten, senden Sie eine POST-Anfrage an den :setIamPolicy-Endpunkt mit dem folgenden Anfragetext:

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

Ersetzen Sie Folgendes:

PROJECT_ID: Ihre Google Cloud Projekt-ID
AGENT_ID: die ID des KI-Datenagenten, für den die Richtlinie abgerufen oder festgelegt werden soll.
ROLE: Die zu gewährende Rolle, z. B. roles/geminidataanalytics.dataAgentUser.
EMAIL: Die E-Mail-Adresse des Nutzers, z. B. test-user@gmail.com.

Vollständige Beispiele finden Sie unter IAM-Richtlinie für einen KI-Datenagenten abrufen und IAM-Richtlinie für einen KI-Datenagenten festlegen.

Python SDK

Wenn Sie die vorhandene Richtlinie für einen Agent abrufen möchten, verwenden Sie die Methode get_iam_policy, wie in der folgenden Beispielanfrage:

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

Verwenden Sie die Methode set_iam_policy, um die Richtlinie für einen Agent festzulegen, wie im folgenden Beispielanfrage:

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
)