Mit der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen

Entwickler können die Conversational Analytics API verwenden, auf die über geminidataanalytics.googleapis.com zugegriffen wird, um eine auf künstlicher Intelligenz (KI) basierende Chat-Oberfläche oder einen KI-Datenagenten zu erstellen, der Fragen zu strukturierten Daten in BigQuery, Looker und Looker Studio in natürlicher Sprache beantwortet.

Auf dieser Seite wird beschrieben, wie Sie sich bei der Conversational Analytics API authentifizieren und Verbindungen zu Ihren Daten in Looker, BigQuery und Looker Studio konfigurieren. Dazu können Sie entweder direkte HTTP-Anfragen oder das SDK verwenden. Für die Conversational Analytics API werden standardmäßige Authentifizierungsmethoden vonGoogle Cloud verwendet.

Hinweis

Bevor Sie sich bei der Conversational Analytics API authentifizieren und Verbindungen zu Ihren Daten konfigurieren können, müssen Sie die Voraussetzungen erfüllen und die erforderlichen APIs für Ihr Projekt von Google Cloud aktivieren, wie unter Conversational Analytics API aktivieren beschrieben.

Bei der Conversational Analytics API authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie sich mit HTTP- und Python-Methoden über geminidataanalytics.googleapis.com bei der Conversational Analytics API authentifizieren, um die erforderlichen Autorisierungstokens zu erhalten.

HTTP-Curl

Mit dem folgenden curl-Beispielbefehl wird eine Anfrage an die Conversational Analytics API gesendet. Der Befehl gcloud auth print-identity-token stellt ein Zugriffstoken bereit, das für die Autorisierung verwendet wird. Ersetzen Sie im Codebeispiel durch den entsprechenden API-Ressourcenpfad.

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://geminidataanalytics.googleapis.com/

HTTP mithilfe von Python

Der folgende Python-Beispielcode zeigt, wie Sie mit der Google Cloud CLI und Python ein Zugriffstoken für die HTTP-Authentifizierung abrufen.

  billing_project = 'YOUR_BILLING_PROJECT'
  access_token = !gcloud auth application-default print-access-token
  url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}:method"
  headers = {"Authorization": f'Bearer {access_token[0]}'}

Ersetzen Sie die Beispielwerte so:

YOUR_BILLING_PROJECT: Die ID Ihres Abrechnungsprojekts, in dem die erforderlichen APIs aktiviert sind.
method: Der Ressourcenpfad für den Zielendpunkt. Beispiel:
- Verwenden Sie zum Erstellen eines Daten-KI-Agenten die Methode POST und den Ressourcenpfad /v1beta/projects/{billing_project}/locations/global/dataAgents.
- Verwenden Sie die Methode GET und den Ressourcenpfad /v1beta/projects/{billing_project}/locations/global/dataAgents, um vorhandene Daten-KI-Agenten aufzulisten.

Python SDK

Das folgende Python-Codebeispiel zeigt, wie Sie Ihr Google-Konto für den Zugriff auf die Conversational Analytics API in Colaboratory authentifizieren:

from google.colab import auth
auth.authenticate_user()

Mit der Conversational Analytics API eine Verbindung zu Looker herstellen

Wenn Sie mit der Conversational Analytics API eine Verbindung zu Looker herstellen möchten, müssen Sie die folgenden Informationen angeben:

Die URL Ihrer Looker-Instanz
Das LookML-Modell und den Looker-Explore, die Sie als Datenquelle verwenden möchten

Außerdem muss das sich authentifizierende Nutzer- oder Dienstkonto die erforderlichen Looker-Berechtigungen haben.

Geeignete Authentifizierungsmethode auswählen

Für die Authentifizierung können Sie dann entweder Looker API-Schlüssel (Client-ID und Clientschlüssel) oder ein Zugriffstoken verwenden. Kunden, die Looker (Google Cloud Core) nur mit privaten Verbindungen verwenden, müssen sich mit einem Zugriffstoken authentifizieren.

Wählen Sie anhand der folgenden Tabelle die geeignete Authentifizierungsmethode aus.

Nutzertyp	Authentifizierungsmethode	Für Looker (Original)	Für Looker (Google Cloud Core)	Für Looker (Google Cloud Core) mit ausschließlich privaten Verbindungen	Beschreibung
Nutzer einbetten	Zugriffstoken	`login_user`	`login_user`	–	Berücksichtigt die LookML-Berechtigungen auf Zeilen- und Spaltenebene (z. B. `access_filters`, `access_grants`, `sql_always_where`) des `access_token` des Zielnutzers.
Nutzer mit Standardzugriff	Zugriffstoken	`login_user` Oder OAuth-Client	OAuth-Client	OAuth-Client	Berücksichtigt die LookML-Berechtigungen auf Zeilen- und Spaltenebene (z. B. `access_filters`, `access_grants`, `sql_always_where`) des `access_token` des Zielnutzers.
Dienstkonto nur für die Looker API	API-Schlüssel	Client-ID und Secret	Client-ID und Secret	–	Alle Nutzer haben dieselbe Zugriffsberechtigungen für Looker.

API-Schlüssel verwenden die Berechtigungen und Zugriffsebenen des Nutzers. Sie sind nützlich, wenn Sie eine Anwendung entwickeln, in der alle Nutzer dieselben Zugriffsberechtigungen haben.

Mit einem Zugriffstoken können Sie die LookML-Berechtigungen auf Zeilen- und Spaltenebene (z. B. access_filters, access_grants, sql_always_where) des access_token des Zielnutzers verwenden. Zugriffstoken sind für mandantenfähige Anwendungen sinnvoll.

Erforderliche Looker-Berechtigungen

Dem Nutzer- bzw. Dienstkonto, das für die Authentifizierung verwendet wird, muss eine Looker-Rolle mit den folgenden Berechtigungen für die abzufragenden Modelle zugewiesen werden:

Sie können diese Berechtigungen in Ihrer Looker-Instanz unter Verwaltung > Rollen konfigurieren.

Mit Looker API-Schlüsseln authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie die API-Schlüssel generieren und die Conversational Analytics API so konfigurieren, dass sie eine Verbindung zu Looker herstellt. Dazu können Sie entweder direkte HTTP-Anfragen oder das SDK verwenden.

Um eine Verbindung zu einer Looker-Instanz herzustellen, benötigen Sie gültige Looker API-Schlüssel, die von Looker erstellt werden und aus einer Client-ID und einem Clientschlüssel bestehen. Looker verwendet diese Schlüssel, um Anfragen an die Looker API zu autorisieren.

Weitere Informationen zum Generieren neuer Looker API-Schlüssel finden Sie unter Administratoreinstellungen – Nutzer. Weitere Informationen zu Authentifizierungsmethoden und zur Verwaltung von Looker API-Schlüsseln finden Sie unter Looker API-Authentifizierung.

HTTP mithilfe von Python

Nachdem Sie die API-Schlüssel (Client-ID und Clientschlüssel) generiert haben, können Sie die Conversational Analytics API so konfigurieren, dass sie über direkte HTTP-Anfragen eine Verbindung zu Looker herstellt. Im folgenden Beispielcode wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle und Ihre API-Schlüssel im Text Ihrer HTTP-Anfrage angeben.


looker_credentials = {
  "oauth": {
      "secret": {
        "client_id": "your_looker_client_id",
        "client_secret": "your_looker_client_secret",
      }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

Ersetzen Sie die Beispielwerte so:

your_looker_client_id: Die Client-ID Ihres generierten Looker API-Schlüssels.
your_looker_client_secret: Der Clientschlüssel Ihres generierten Looker API-Schlüssels.
https://your_company.looker.com: Die vollständige URL Ihrer Looker-Instanz.
your_model: Der Name des LookML-Modells, das Sie verwenden möchten.
your_explore: Der Name des Explores im angegebenen Modell, das Sie verwenden möchten.

Python SDK

Nachdem Sie die API-Schlüssel (Client-ID und Clientschlüssel) generiert haben, können Sie die Conversational Analytics API so konfigurieren, dass sie mit Python eine Verbindung zu Looker herstellt. Im folgenden Python-Codebeispiel wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle und Ihre API-Schlüssel für die Conversational Analytics API angeben.

looker_client_id = "YOUR-LOOKER-CLIENT-ID" # @param {type:"string"}
looker_client_secret = "YOUR-LOOKER-CLIENT-SECRET" # @param {type:"string"}
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI" # @param {type:"string"}
lookml_model = "YOUR-LOOKER-MODEL" # @param {type:"string"}
explore = "YOUR-LOOKER-EXPLORE" # @param {type:"string"}

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

Ersetzen Sie die Beispielwerte so:

YOUR-LOOKER-CLIENT-ID: Die Client-ID Ihres generierten Looker API-Schlüssels.
YOUR-LOOKER-CLIENT-SECRET: Der Clientschlüssel Ihres generierten Looker API-Schlüssels.
YOUR-LOOKER-INSTANCE-URI: Die vollständige URL Ihrer Looker-Instanz.
YOUR-LOOKER-MODEL: Der Name des Looker-Modells, das Sie verwenden möchten.
YOUR-LOOKER-EXPLORE: Der Name des Looker-Explores, den Sie verwenden möchten.

Mit einem Zugriffstoken authentifizieren

In diesem Abschnitt wird beschrieben, wie Sie die Conversational Analytics API so konfigurieren, dass sie mit einem Zugriffstoken eine Verbindung zu Looker herstellt.

Um eine Verbindung zu einer Looker-Instanz herzustellen, benötigen Sie einen gültigen OAuth2-access_token-Wert, der durch eine erfolgreiche Anfrage an den Looker API-Endpunkt login erstellt wird.

Weitere Informationen zum Generieren eines Zugriffstokens finden Sie unter Looker API-Authentifizierung und Clientanmeldedaten zum Abrufen eines Autorisierungstokens präsentieren.

HTTP mithilfe von Python

Im folgenden Beispielcode wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle und Ihr Zugriffstoken im Text Ihrer HTTP-Anfrage angeben.

Wir empfehlen, das Looker-Zugriffstoken (access_token) aus Sicherheitsgründen als Umgebungsvariable zu speichern.

looker_credentials = {
  "oauth": {
    "token": {
      "access_token": "YOUR-TOKEN",
    }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

Ersetzen Sie die Beispielwerte so:

YOUR-TOKEN: Der access_token-Wert, den Sie zur Authentifizierung bei Looker generieren.
https://your_company.looker.com: Die vollständige URL Ihrer Looker-Instanz.
your_model: Der Name des LookML-Modells, das Sie verwenden möchten.
your_explore: Der Name des Explores im angegebenen Modell, das Sie verwenden möchten.

Python SDK

Im folgenden Python-Beispielcode wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle und Ihr Zugriffstoken definieren, um sich mit dem Python SDK zu authentifizieren.

Wir empfehlen, das Looker-Zugriffstoken (access_token) aus Sicherheitsgründen als Umgebungsvariable zu speichern.

looker_access_token = "YOUR-TOKEN"
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI"
lookml_model = "YOUR-LOOKER-MODEL"
explore = "YOUR-LOOKER-EXPLORE"

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = looker_access_token

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

Ersetzen Sie die Beispielwerte so:

YOUR-TOKEN: Der access_token-Wert, den Sie zur Authentifizierung bei Looker verwenden.
YOUR-LOOKER-INSTANCE-URI: Die vollständige URL Ihrer Looker-Instanz.
YOUR-LOOKER-MODEL: Der Name des Looker-Modells, das Sie verwenden möchten.
YOUR-LOOKER-EXPLORE: Der Name des Looker-Explores, den Sie verwenden möchten.

HTTP mithilfe von JavaScript

Im folgenden Beispielcode wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle und Ihr Zugriffstoken im Text Ihrer HTTP-Anfrage angeben.

Wir empfehlen, das Looker-Zugriffstoken (access_token) aus Sicherheitsgründen als Umgebungsvariable zu speichern.

const requestBody = {
  project: GCP_PROJECT,
  messages: [
    {
      user_message: {
        text: inputWithPreviousMessages,
      },
    },
  ],
  context: {
    system_instruction: agentConfig.system_instructions,
    datasource_references: {
      looker: {
        explore_references: [
          {
            looker_instance_uri: YOUR-LOOKER-INSTANCE-URI,
            lookml_model: YOUR-LOOKER-MODEL,
            explore: YOUR-LOOKER-EXPLORE,
          },
        ],
        credentials: {
          oauth: {
            token: {
              access_token: YOUR-TOKEN,
            },
          },
        },
      },
    },
  },
}

Ersetzen Sie die Beispielwerte so:

YOUR-LOOKER-INSTANCE-URI: Die vollständige URL Ihrer Looker-Instanz.
YOUR-LOOKER-MODEL: Der Name des LookML-Modells, das Sie verwenden möchten.
YOUR-LOOKER-EXPLORE: Der Name des Explores im angegebenen Modell, das Sie verwenden möchten.
YOUR-TOKEN: Der access_token-Wert, den Sie zur Authentifizierung bei Looker generieren.

Mit der Conversational Analytics API eine Verbindung zu BigQuery herstellen

Wenn Sie mit der Conversational Analytics API eine Verbindung zu einer oder mehreren BigQuery-Tabelle(n) herstellen möchten, müssen Sie sich für jede Tabelle beim entsprechenden BigQuery-Projekt authentifizieren. Geben Sie für jede Tabelle die folgenden Informationen an:

Die BigQuery-Projekt-ID
Die BigQuery-Dataset-ID
Die BigQuery-Tabellen-ID

Bei der Conversational Analytics API gibt es keine strikten Grenzwerte für die Anzahl der BigQuery-Tabellen, zu denen Sie eine Verbindung herstellen können. Wenn Sie jedoch zu einer großen Anzahl an Tabellen eine Verbindung herstellen, kann dies die Accuracy beeinträchtigen oder dazu führen, dass das Eingabetokenlimit von Gemini überschritten wird. Abfragen mit komplexen Joins über mehrere Tabellen hinweg können ebenfalls zu weniger genauen Antworten führen.

In diesem Abschnitt wird beschrieben, wie Sie die Conversational Analytics API so konfigurieren, dass sie entweder über direkte HTTP-Anfragen oder über ein SDK eine Verbindung zu BigQuery herstellt.

HTTP mithilfe von Python

Mit dem folgenden Beispielcode wird eine Verbindung zu mehreren BigQuery-Tabellen definiert.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "my_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        {
          "projectId": "my_project_id_3",
          "datasetId": "my_dataset_id_3",
          "tableId": "my_table_id_3"
        },
      ]
    }
}

Ersetzen Sie die Beispielwerte so:

my_project_id: die ID des Projekts in Google Cloud , das das BigQuery-Dataset und die BigQuery-Tabelle enthält, zu denen Sie eine Verbindung herstellen möchten. Wenn Sie eine Verbindung zu einem öffentlichen Dataset herstellen möchten, geben Sie bigquery-public-data an.
my_dataset_id: Die ID des BigQuery-Datasets.
my_table_id: Die ID der BigQuery-Tabelle.

Python SDK

Mit dem auth SDK von Colaboratory können Sie sich mit den Anmeldedaten Ihres in Colaboratory authentifizierten Nutzers bei BigQuery authentifizieren.

Mit dem folgenden Python-Beispielcode wird eine Verbindung zu mehreren BigQuery-Tabellen definiert und gezeigt, wie Sie Ihr Google-Konto in Colaboratory bei BigQuery authentifizieren.

from google.colab import auth
auth.authenticate_user()

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "my_project_id"
bigquery_table_reference.dataset_id = "my_dataset_id"
bigquery_table_reference.table_id = "my_table_id"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_table_id_3"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2, bigquery_table_reference_3]

Ersetzen Sie die Beispielwerte so:

my_project_id: die ID des Projekts in Google Cloud , das das BigQuery-Dataset und die BigQuery-Tabelle enthält, zu denen Sie eine Verbindung herstellen möchten. Wenn Sie eine Verbindung zu einem öffentlichen Dataset herstellen möchten, geben Sie bigquery-public-data an.
my_dataset_id: Die ID des BigQuery-Datasets. Beispiel: san_francisco.
my_table_id: Die ID der BigQuery-Tabelle. Beispiel: street_trees.

Mit der Conversational Analytics API eine Verbindung zu Looker Studio herstellen

Wenn Sie mit der Conversational Analytics API eine Verbindung zu Looker Studio herstellen möchten, müssen Sie zuerst die Looker Studio API aktivieren. In diesem Abschnitt wird beschrieben, wie Sie die Conversational Analytics API so konfigurieren, dass sie entweder über direkte HTTP-Anfragen oder über ein SDK eine Verbindung zu Looker Studio herstellt.

Looker Studio API aktivieren

Folgen Sie der Anleitung unter API aktivieren, um die Looker Studio API zu aktivieren.

Bei Looker Studio authentifizieren

Wenn Sie mit der Conversational Analytics API eine Verbindung zu Looker Studio herstellen möchten, müssen Sie sich bei Looker Studio authentifizieren und die Looker Studio-Datenquellen-ID angeben.

HTTP mithilfe von Python

Nachdem Sie die Looker Studio API aktiviert haben, können Sie sich bei Looker Studio authentifizieren, indem Sie mit Python HTTP-Curl-Anfragen senden. Der folgende Beispielcode zeigt, wie Sie die Details Ihrer Looker-Datenquelle im Text Ihrer HTTP-Anfrage angeben.

Sie können sich bei Looker Studio authentifizieren, indem Sie direkte HTTP-Anfragen senden. Ein Beispiel für einen HTTP-Aufruf finden Sie im folgenden Codeblock.

looker_studio_data_source = {
    "studio":{
        "studio_references":
        [
            {
              "datasource_id": "your_studio_datasource_id"
            }
        ]
    }
}

Ersetzen Sie your_studio_datasource_id durch die tatsächliche Datenquellen-ID der Looker Studio-Datenquelle, die Sie verwenden möchten.

Python SDK

Nachdem Sie die Looker Studio API aktiviert haben, können Sie sich mit einem SDK bei Looker Studio authentifizieren. Im folgenden Python-Beispielcode wird gezeigt, wie Sie die Details Ihrer Looker-Datenquelle angeben und sich bei Looker Studio authentifizieren.


datasource_id = "STUDIO-DATASOURCE-ID"

# Looker Studio
studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.studio.studio_references = [studio_references]

Ersetzen Sie STUDIO-DATASOURCE-ID durch die tatsächliche Datenquellen-ID der Looker Studio-Datenquelle, die Sie verwenden möchten.

Mit der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Bei der Conversational Analytics API authentifizieren

HTTP-Curl

HTTP mithilfe von Python

Python SDK

Mit der Conversational Analytics API eine Verbindung zu Looker herstellen

Geeignete Authentifizierungsmethode auswählen

Erforderliche Looker-Berechtigungen

Mit Looker API-Schlüsseln authentifizieren

HTTP mithilfe von Python

Python SDK

Mit einem Zugriffstoken authentifizieren

HTTP mithilfe von Python

Python SDK

HTTP mithilfe von JavaScript

Mit der Conversational Analytics API eine Verbindung zu BigQuery herstellen

HTTP mithilfe von Python

Python SDK

Mit der Conversational Analytics API eine Verbindung zu Looker Studio herstellen

Looker Studio API aktivieren

Bei Looker Studio authentifizieren

HTTP mithilfe von Python

Python SDK

Mit der Conversational Analytics API authentifizieren und eine Verbindung zu einer Datenquelle herstellen