Kunden-verwaltete Verschlüsselungsschlüssel (CMEK)

Gemini Data Analytics verschlüsselt ruhende Kundeninhalte standardmäßig. Gemini Data Analytics übernimmt die Verschlüsselung für Sie, ohne dass Sie weitere Maßnahmen ergreifen müssen. Diese Option heißt Google-Standardverschlüsselung.

Wenn Sie Ihre Verschlüsselungsschlüssel selbst verwalten möchten, können Sie vom Kunden verwaltete Verschlüsselungsschlüssel (CMEKs, Customer-Managed Encryption Keys) in Cloud KMS mit CMEK-integrierten Diensten wie Gemini Data Analytics verwenden. Mit Cloud KMS-Schlüsseln haben Sie die Kontrolle über Schutz level, Speicherort, Rotationszeitplan, Nutzungs- und Zugriffsberechtigungen sowie über kryptografische Grenzen. Mit Cloud KMS können Sie außerdem Audit-Logs aufrufen und den Lebenszyklus von Schlüsseln steuern. Statt es Google zu überlassen, die symmetrischen Schlüsselverschlüsselungsschlüssel (Key Encryption Keys, KEKs) zum Schutz Ihrer Daten zu besitzen und zu verwalten, können Sie diese auch über Cloud KMS steuern und verwalten.

Nachdem Sie Ihre Ressourcen mit CMEKs eingerichtet haben, ähnelt der Zugriff auf Ihre Gemini Data Analytics-Ressourcen der Verwendung der Google-Standardverschlüsselung. Weitere Informationen zu Ihren Verschlüsselung soptionen finden Sie unter Kundenverwaltete Verschlüsselungsschlüssel (CMEK).

Auf dieser Seite wird beschrieben, wie Sie mit vom Kunden verwalteten Verschlüsselungsschlüsseln (CMEK) Daten schützen, die von der Conversational Analytics API mit Looker-Datenquellen verwendet werden. Die Conversational Analytics API ist ein Produkt im Gemini Data Analytics-Dienst (geminidataanalytics.googleapis.com).

CMEK für Conversational Analytics API-Ressourcen

Wenn Sie CMEK für eine Conversational Analytics API-Ressource konfigurieren, werden die vertraulichen ruhenden Daten mit dem angegebenen Cloud KMS-Schlüssel verschlüsselt. Sie können CMEK unabhängig für DataAgent- und Conversation-Ressourcen konfigurieren.

Sie können CMEK nur beim Erstellen der Ressource konfigurieren. Wenn Sie CMEK verwenden möchten, müssen Sie beim Erstellen einer DataAgent- oder Conversation-Ressource das Feld kms_key angeben. Sie können einer vorhandenen Ressource keinen Cloud KMS-Schlüssel hinzufügen oder ihn ändern.

Mit CMEK geschützte Inhalte

CMEK für die Conversational Analytics API schützt die folgenden ruhenden Daten:

DataAgent Ressourcen: Alle wichtigen Kundeninhalte in den Feldern data_analytics_agent, staging_context, published_context und last_published_context. Dazu gehören Felder wie system_instruction und example_queries.
Conversation-Ressourcen: Alle Nachrichten und der gesamte Statusverlauf.

Die folgenden Daten werden nicht mit dem CMEK-Schlüssel des Kunden verschlüsselt. Stattdessen werden diese Daten durch die Google-Standardverschlüsselung geschützt:

DataAgent resources: Metadatenfelder wie name, display_name, description, labels, create_time, update_time, delete_time, purge_time und kms_key
Conversation-Ressourcen: Metadatenfelder wie name, agents, labels, create_time, last_used_time und kms_key

Beschränkungen

Für CMEK für die Conversational Analytics API gelten die folgenden Einschränkungen:

CMEK muss beim Erstellen der Ressource konfiguriert werden. Es kann einer vorhandenen Ressource nicht hinzugefügt oder geändert werden.
Der Cloud KMS-Schlüssel und die Conversational Analytics API-Ressource müssen sich am selben Standort befinden. Die Region global wird nicht unterstützt.
Für Conversational Analytics API-Ressourcen wird CMEK in der Region us-east4 unterstützt.
Für Conversational Analytics API-Ressourcen wird CMEK nur für Looker-Datenquellen unterstützt.
Sie können nur einen CMEK pro Projekt und Region für alle Conversation-Ressourcen in diesem Projekt und dieser Region verwenden.

Hinweis

Bevor Sie CMEK mit der Conversational Analytics API verwenden können, führen Sie die folgenden Schritte aus:

Aktivieren Sie die erforderlichen APIs in der Google Cloud Console oder der Google Cloud CLI.
Console
Aktivieren Sie in der Google Cloud Console die folgenden APIs für Ihr Google Cloud Projekt.

Gemini Data Analytics API aktivieren

Gemini für Google Cloud API aktivieren

Cloud Key Management Service API aktivieren

**Tipp**: Wenn Sie eine API aktivieren, müssen Sie die Google Cloud Seite der Console möglicherweise aktualisieren, um zu bestätigen, dass sie aktiviert wurde.
gcloud
Führen Sie mit der Google Cloud CLI die folgenden gcloud services enable-Befehle aus, um die Gemini Data Analytics API, die Gemini for Google Cloud API und die Cloud Key Management Service API zu aktivieren:
```
gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id
```
Ersetzen Sie in den vorherigen Beispielbefehlen der gcloud CLI project_id durch die Projekt-ID Ihres Projekts in Google Cloud .
Fügen Sie Ihr Projekt der Zulassungsliste hinzu.

Ihr Google Cloud Projekt muss einer Zulassungsliste hinzugefügt werden, damit Sie CMEK mit Gemini Data Analytics verwenden können. Wenn Sie Ihr Projekt der Zulassungsliste hinzufügen lassen möchten, senden Sie Ihre Projekt-ID über das Formular für die Zulassungsliste für GDA-CMEK. Das Hinzufügen Ihres Projekts zur Zulassungsliste dauert etwa ein bis zwei Arbeitstage.
Erstellen Sie einen Cloud KMS-Schlüsselbund und einen Schlüssel am selben Standort wie Ihre Conversational Analytics API-Ressourcen. Weitere Informationen finden Sie unter Schlüssel erstellen.
Erstellen Sie die von Google verwalteten Dienst-Agents, auch bekannt als Per-Project-Per-Product Service Accounts (P4SAs), falls sie noch nicht vorhanden sind. Diese Dienst-Agents sind erforderlich, damit die Dienste, die zum Schutz Ihrer Conversational Analytics API-Ressourcen mit CMEK verwendet werden, auf Ihren Cloud KMS-Schlüssel zugreifen können.

Führen Sie die folgenden gcloud-Befehle aus, um die Dienst-Agents zu erstellen:
```
gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch Ihre Google Cloud Projekt-ID.
Weisen Sie beiden Dienst-Agents, die Sie im vorherigen Schritt erstellt haben, die Rolle „Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler“ (roles/cloudkms.cryptoKeyEncrypterDecrypter) in Identity and Access Management (IAM) zu, damit der Gemini Data Analytics-Dienst Ihren Cloud KMS-Schlüssel zum Ver- und Entschlüsseln Ihrer Conversational Analytics API-Daten verwenden kann.

Gewähren Sie dem Gemini Data Analytics-Dienst-Agent die Berechtigung:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Gewähren Sie dem Gemini for Google Cloud API-Dienst-Agent die Berechtigung:
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Ersetzen Sie in den vorherigen Codebeispielen die Beispielwerte wie folgt:
- KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
- KEY_LOCATION: Die Region Ihres Schlüsselbunds (z. B. us-east4).
- KEY_RING_NAME: Der Name Ihres Schlüsselbunds.
- PROJECT_NUMBER: Ihre Google Cloud Projekt nummer, in der Sie API-Ressourcen erstellen.
- KMS_PROJECT_ID: Die Projekt-ID, in der der Schlüssel erstellt wurde. Diese kann mit dem Projekt identisch sein, in dem Sie API-Ressourcen erstellen.

Ressourcen mit CMEK schützen

In diesem Abschnitt wird beschrieben, wie Sie eine neue DataAgent- oder Conversation-Ressource mit CMEK schützen, indem Sie mit der REST API beim Erstellen der Ressource einen Cloud KMS-Schlüssel im Feld kms_key angeben.

Sie können CMEK nur beim Erstellen einer DataAgent- oder Conversation-Ressource aktivieren.

Ein CMEK-Schlüssel muss sich in derselben Region wie die Ressource befinden, die er schützt. Weitere Informationen finden Sie unter Beschränkungen.

`DataAgent`-Ressource mit CMEK schützen

Wenn Sie eine neue DataAgent-Ressource mit CMEK schützen möchten, geben Sie beim Erstellen des Daten-KI-Agenten einen Cloud KMS-Schlüssel im Feld kms_key an.

Python SDK

Das folgende Beispiel zeigt, wie Sie beim Erstellen einer DataAgent-Ressource mit dem Python SDK einen Cloud KMS-Schlüssel angeben. Ein Beispiel für eine vollständige -Anfrage finden Sie unter KI-Datenagenten mit dem Python SDK erstellen.create

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

Ersetzen Sie im vorherigen Beispiel die Werte wie folgt:

BILLING_PROJECT_ID: Ihre Abrechnungsprojekt-ID.
KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
KMS_PROJECT_ID: Die Projekt-ID, in der der Schlüssel erstellt wurde. Wenn das Feld leer bleibt, wird billing_project verwendet.
LOCATION: Die Region Ihres Schlüsselbunds.

HTTP

Das folgende Beispiel zeigt, wie Sie beim Erstellen einer DataAgent-Ressource mit HTTP und Python einen Cloud KMS-Schlüssel im Anfragetext angeben. Ein Beispiel für eine vollständige -Anfrage finden Sie unter KI-Datenagenten mit HTTP und Python erstellen.create

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

Ersetzen Sie im vorherigen Beispiel die Werte wie folgt:

KMS_PROJECT_ID: Die Projekt-ID, in der der Schlüssel erstellt wurde.
LOCATION: Die Region Ihres Schlüsselbunds.
KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.

`Conversation`-Ressource mit CMEK schützen

Wenn Sie eine neue Conversation-Ressource mit CMEK schützen möchten, geben Sie beim Erstellen der Unterhaltung einen Cloud KMS-Schlüssel im Feld kms_key an.

Python SDK

Das folgende Beispiel zeigt, wie Sie beim Erstellen einer Conversation-Ressource mit dem Python SDK einen Cloud KMS-Schlüssel angeben. Ein Beispiel für eine vollständige -Anfrage finden Sie unter KI-Datenagenten mit dem Python SDK erstellen.create

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

Ersetzen Sie im vorherigen Beispiel die Werte wie folgt:

BILLING_PROJECT_ID: Ihre Abrechnungsprojekt-ID.
KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.
KMS_PROJECT_ID: Die Projekt-ID, in der der Schlüssel erstellt wurde. Wenn das Feld leer bleibt, wird billing_project verwendet.
LOCATION: Die Region Ihres Schlüsselbunds.

HTTP

Das folgende Beispiel zeigt, wie Sie beim Erstellen einer Conversation-Ressource mit HTTP und Python einen Cloud KMS-Schlüssel im Anfragetext angeben. Ein Beispiel für eine vollständige -Anfrage finden Sie unter KI-Datenagenten mit HTTP und Python erstellen.create

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

Ersetzen Sie im vorherigen Beispiel die Werte wie folgt:

KMS_PROJECT_ID: Die Projekt-ID, in der der Schlüssel erstellt wurde.
LOCATION: Die Region Ihres Schlüsselbunds.
KEY_RING_NAME: Der Name Ihres Cloud KMS-Schlüsselbunds.
KEY_NAME: Der Name Ihres Cloud KMS-Schlüssels.

Fehlerbehebung

In diesem Abschnitt werden häufige Probleme und wichtige Überlegungen bei der Verwendung von CMEK mit der Conversational Analytics API behandelt.

Änderungen des Schlüsselstatus

Wenn eine Cloud KMS-Schlüsselversion, die eine Conversational Analytics API-Ressource schützt, nicht mehr verfügbar ist, verlieren Sie den Zugriff auf die Daten, die mit diesem Schlüssel verschlüsselt wurden. Wenn Sie versuchen, auf geschützte Daten zuzugreifen, während der Schlüssel nicht verfügbar ist, z. B. durch Lesen des Kontexts einer DataAgent-Ressource oder durch Zugriff auf den Conversation-Verlauf, schlägt die Anfrage fehl. Der zurückgegebene Fehler hängt davon ab, warum der Schlüssel nicht verfügbar ist:

Wenn die Schlüsselversion deaktiviert oder gelöscht wird, schlägt der Vorgang in der Regel mit einem FAILED_PRECONDITION Fehler fehl.
Wenn die IAM-Rolle cloudkms.cryptoKeyEncrypterDecrypter für den Dienst-Agent gcp-sa-geminidataanalytics oder gcp-sa-cloudaicompanion widerrufen wird, schlägt der Vorgang in der Regel mit einem PERMISSION_DENIED- oder NOT_FOUND-Fehler fehl.

Auch wenn der Schlüssel nicht verfügbar ist, können Sie Vorgänge ausführen, bei denen der Inhalt nicht entschlüsselt werden muss, z. B. das Löschen der DataAgent- oder Conversation-Ressource.

Um den Zugriff auf verschlüsselte Daten wiederherzustellen, aktivieren Sie den Schlüssel wieder und prüfen Sie, ob die Dienst-Agents die erforderlichen IAM-Berechtigungen haben. Weitere Informationen finden Sie unter Hinweis.

Cloud KMS-Kontingente und die Conversational Analytics API

Wenn Sie CMEK in der Conversational Analytics API verwenden, können Ihre Projekte Kontingente für kryptografische Cloud KMS-Anfragen verbrauchen. Wenn Sie beispielsweise eine DataAgent-Ressource lesen oder auf den Conversation-Verlauf zugreifen, der durch CMEK geschützt ist, muss Cloud KMS die Daten entschlüsseln.

Ver- und Entschlüsselungsvorgänge über CMEK-Schlüssel wirken sich auf die Cloud KMS-Kontingente so aus:

Für in Cloud KMS generierte Software-CMEK-Schlüssel wird kein Cloud KMS-Kontingent verbraucht.
Bei Hardware-CMEK-Schlüsseln (manchmal auch Cloud HSM-Schlüssel genannt) werden Verschlüsselungs- und Entschlüsselungsvorgänge auf Cloud HSM-Kontingente in dem Projekt angerechnet, das den Schlüssel enthält.
Bei externen CMEK-Schlüsseln (manchmal auch Cloud EKM-Schlüssel genannt) werden Verschlüsselungs- und Entschlüsselungsvorgänge auf Cloud EKM-Kontingente in dem Projekt angerechnet, das den Schlüssel enthält.

Weitere Informationen finden Sie unter Cloud KMS-Kontingente.

Nächste Schritte

Informationen zum Aktivieren der Conversational Analytics API
Informationen zum Authentifizieren und Herstellen einer Verbindung zu einer Datenquelle mit der Conversational Analytics API
Informationen zum Erstellen eines KI-Datenagenten mit dem Python SDK
Informationen zum Erstellen eines KI-Datenagenten mit HTTP und Python
Weitere Informationen zu Cloud KMS.
Informationen zu CMEK-Organisationsrichtlinien

Kunden-verwaltete Verschlüsselungsschlüssel (CMEK) Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

CMEK für Conversational Analytics API-Ressourcen

Mit CMEK geschützte Inhalte

Beschränkungen

Hinweis

Console

gcloud

Ressourcen mit CMEK schützen

DataAgent-Ressource mit CMEK schützen

Python SDK

HTTP

Conversation-Ressource mit CMEK schützen

Python SDK

HTTP

Fehlerbehebung

Änderungen des Schlüsselstatus

Cloud KMS-Kontingente und die Conversational Analytics API

Nächste Schritte

Kunden-verwaltete Verschlüsselungsschlüssel (CMEK)

`DataAgent`-Ressource mit CMEK schützen

`Conversation`-Ressource mit CMEK schützen