Mit der Conversational Analytics API eine Datenquelle authentifizieren und eine Verbindung 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:

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

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

Mit der Conversational Analytics API können Sie jeweils nur zu einem Looker-Explore eine Verbindung herstellen.

Erforderliche Looker-Berechtigungen

Dem Nutzer oder Dienstkonto, dessen Anmeldedaten für die Authentifizierung verwendet werden, muss eine Looker-Rolle zugewiesen werden, die die folgenden Berechtigungen für die Modelle enthält, die Sie abfragen möchten:

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

Authentifizierung mit Looker API-Schlüsseln

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. Kunden, die die Option Private IP-Adresse für Looker (Google Cloud Core) verwenden, können diese Methode nicht nutzen und sollten sich mit einem Zugriffstoken authentifizieren.

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.

Authentifizierung mit einem Zugriffstoken

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-Tabellen herstellen möchten, müssen Sie sich für jede Tabelle im 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

Mit der Conversational Analytics API gibt es keine harten Beschränkungen für die Anzahl der BigQuery-Tabellen, mit denen Sie eine Verbindung herstellen können. Wenn Sie jedoch eine Verbindung zu einer großen Anzahl von Tabellen herstellen, kann dies die Genauigkeit verringern oder dazu führen, dass Sie das Eingabetokenlimit von Gemini überschreiten. Abfragen, für die komplexe Joins über mehrere Tabellen hinweg erforderlich sind, 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

Im 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.

Im 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.