S'authentifier et se connecter à une source de données avec l'API Conversational Analytics

Preview privée

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les développeurs peuvent utiliser l'API Conversational Analytics, accessible via geminidataanalytics.googleapis.com, pour créer une interface de chat ou un agent de données optimisés par l'intelligence artificielle (IA). Ces outils répondent aux questions sur les données structurées dans BigQuery, Looker et Looker Studio en utilisant le langage naturel.

Remarque : Pour utiliser l'API Conversational Analytics, vous devez participer à la preview privée. Pour manifester votre intérêt, remplissez le formulaire de participation à la preview.

Cette page explique comment s'authentifier auprès de l'API Conversational Analytics et configurer des connexions à vos données dans Looker, BigQuery et Looker Studio à l'aide de requêtes HTTP directes ou du SDK. L'API Conversational Analytics utilise des méthodes d'authentificationGoogle Cloud standards.

Avant de commencer

Avant de pouvoir vous authentifier auprès de l'API Conversational Analytics et configurer des connexions à vos données, vous devez remplir les conditions préalables et activer les API requises pour votre projet Google Cloud , comme décrit dans Activer l'API Conversational Analytics.

S'authentifier auprès de l'API Conversational Analytics

Cette section explique comment s'authentifier auprès de l'API Conversational Analytics (via geminidataanalytics.googleapis.com) à l'aide des méthodes HTTP et Python pour obtenir les jetons d'autorisation nécessaires.

HTTP curl

L'exemple de commande curl suivant envoie une requête à l'API Conversational Analytics. La commande gcloud auth print-identity-token fournit un jeton d'accès utilisé pour l'autorisation. Dans l'exemple de code, remplacez par le chemin d'accès approprié pour la ressource d'API.

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

HTTP avec Python

L'exemple de code Python suivant montre comment obtenir un jeton d'accès pour l'authentification HTTP à l'aide de la Google Cloud CLI et de Python.

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

Remplacez les exemples de valeurs comme suit :

• YOUR_BILLING_PROJECT : ID de votre projet de facturation pour lequel les API requises sont activées.
• method : chemin d'accès à la ressource pour le point de terminaison cible. Exemple :
  • Pour créer un agent de données, utilisez la méthode POST et le chemin d'accès à la ressource /v1alpha/projects/{billing_project}/locations/global/dataAgents.
  • Pour lister les agents de données existants, utilisez la méthode GET et le chemin d'accès à la ressource /v1alpha/projects/{billing_project}/locations/global/dataAgents.

SDK Python

L'exemple de code Python suivant montre comment authentifier votre compte Google pour accéder à l'API Conversational Analytics dans Colaboratory :

from google.colab import auth
auth.authenticate_user()

Se connecter à Looker avec l'API Conversational Analytics

Pour vous connecter à Looker avec l'API Conversational Analytics, vous devez fournir les informations suivantes :

• L'URL de votre instance Looker
• Le modèle LookML et l'exploration Looker spécifiques que vous souhaitez utiliser en guise de source de données

Vous pouvez ensuite choisir de vous authentifier à l'aide de clés API Looker (ID client et code secret du client) ou d'un jeton d'accès. Les clients qui utilisent l'option Adresse IP privée Looker (Google Cloud Core) doivent s'authentifier avec un jeton d'accès.

Vous ne pouvez vous connecter qu'à une seule exploration Looker à la fois avec l'API Conversational Analytics.

Authentification avec des clés API Looker

Cette section explique comment générer les clés API et configurer l'API Conversational Analytics pour vous connecter à Looker à l'aide de requêtes HTTP directes ou du SDK. Les clients qui utilisent l'option Adresse IP privée Looker (Google Cloud Core) ne peuvent pas utiliser cette méthode et doivent s'authentifier avec un jeton d'accès.

Pour établir une connexion avec une instance Looker, vous avez besoin de clés API Looker valides, lesquelles sont créées par Looker et se composent d'un ID client et d'un code secret du client. Looker utilise ces clés pour autoriser les requêtes envoyées à l'API Looker.

Pour en savoir plus sur la génération de clés API Looker, consultez Paramètres d'administration – Utilisateurs. Pour en savoir plus sur les méthodes d'authentification et la gestion des clés API Looker, consultez Authentification de l'API Looker.

HTTP avec Python

Une fois que vous avez généré les clés API (ID client et secret), vous pouvez configurer l'API Conversational Analytics pour qu'elle se connecte à Looker en effectuant des requêtes HTTP directes. L'exemple de code suivant montre comment spécifier les détails de votre source de données Looker et vos clés API dans le corps de votre requête HTTP.

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",
    }
  }
}

Remplacez les exemples de valeurs comme suit :

• your_looker_client_id : ID client de la clé API Looker générée.
• your_looker_client_secret : code secret du client pour la clé API Looker générée.
• https://your_company.looker.com : URL complète de votre instance Looker.
• your_model : nom du modèle LookML que vous souhaitez utiliser.
• your_explore : nom de l'exploration dans le modèle spécifié que vous souhaitez utiliser.

SDK Python

Une fois que vous avez généré les clés API (ID client et secret), vous pouvez configurer l'API Conversational Analytics pour qu'elle se connecte à Looker à l'aide de Python. L'exemple de code Python suivant montre comment spécifier les détails de votre source de données Looker et vos clés API pour l'API Conversational Analytics.

Conseil : Pour renforcer la sécurité, stockez l'ID client (looker_client_id) et le code secret du client Looker (looker_client_secret) en tant que variables d'environnement.

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]

Remplacez les exemples de valeurs comme suit :

• YOUR-LOOKER-CLIENT-ID : ID client de la clé API Looker générée.
• YOUR-LOOKER-CLIENT-SECRET : code secret du client pour la clé API Looker générée.
• YOUR-LOOKER-INSTANCE-URI : URL complète de votre instance Looker.
• YOUR-LOOKER-MODEL : nom du modèle Looker que vous souhaitez utiliser.
• YOUR-LOOKER-EXPLORE : nom de l'exploration Looker que vous souhaitez utiliser.

Authentification avec un jeton d'accès

Cette section explique comment configurer l'API Conversational Analytics pour qu'elle se connecte à Looker à l'aide d'un jeton d'accès.

Pour établir une connexion avec une instance Looker, vous avez besoin d'une valeur access_token OAuth2 valide, qui est créée par une requête au point de terminaison de l'API Looker login ayant abouti.

Pour en savoir plus sur la génération d'un jeton d'accès, consultez Authentification de l'API Looker et découvrez comment présenter des identifiants client pour obtenir un jeton d'autorisation.

Remarque : Les identifiants utilisés pour générer la valeur access_token doivent disposer des autorisations nécessaires pour utiliser les points de terminaison Looker Get LookML Model Explore et Run Inline Query. L'autorisation develop est une exigence minimale.

Utiliser une adresse IP publique Utiliser une adresse IP privée

HTTP avec Python

L'exemple de code suivant montre comment spécifier les détails de votre source de données Looker et votre jeton d'accès dans le corps de votre requête HTTP.

Pour renforcer la sécurité, nous vous recommandons de stocker le jeton d'accès Looker (access_token) en tant que variable d'environnement.

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",
    }
  }
}

Remplacez les exemples de valeurs comme suit :

• YOUR-TOKEN : valeur access_token que vous générez pour vous authentifier auprès de Looker.
• https://your_company.looker.com : URL complète de votre instance Looker.
• your_model : nom du modèle LookML que vous souhaitez utiliser.
• your_explore : nom de l'exploration dans le modèle spécifié que vous souhaitez utiliser.

SDK Python

L'exemple de code Python suivant montre comment définir les détails de votre source de données Looker et votre jeton d'accès pour vous authentifier à l'aide du SDK Python.

Pour renforcer la sécurité, nous vous recommandons de stocker le jeton d'accès Looker (access_token) en tant que variable d'environnement.

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]

Remplacez les exemples de valeurs comme suit :

• YOUR-TOKEN : valeur access_token que vous utilisez pour vous authentifier auprès de Looker.
• YOUR-LOOKER-INSTANCE-URI : URL complète de votre instance Looker.
• YOUR-LOOKER-MODEL : nom du modèle Looker que vous souhaitez utiliser.
• YOUR-LOOKER-EXPLORE : nom de l'exploration Looker que vous souhaitez utiliser.

HTTP avec JavaScript

L'exemple de code suivant montre comment spécifier les détails de votre source de données Looker et votre jeton d'accès dans le corps de votre requête HTTP.

Pour renforcer la sécurité, nous vous recommandons de stocker le jeton d'accès Looker (access_token) en tant que variable d'environnement.

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,
            },
          },
        },
      },
    },
  },
}

Remplacez les exemples de valeurs comme suit :

• YOUR-LOOKER-INSTANCE-URI : URL complète de votre instance Looker.
• YOUR-LOOKER-MODEL : nom du modèle LookML que vous souhaitez utiliser.
• YOUR-LOOKER-EXPLORE : nom de l'exploration dans le modèle spécifié que vous souhaitez utiliser.
• YOUR-TOKEN : valeur access_token que vous générez pour vous authentifier auprès de Looker.

Se connecter à BigQuery avec l'API Conversational Analytics

Pour vous connecter à BigQuery avec l'API Conversational Analytics, vous devez vous authentifier auprès de votre projet BigQuery et fournir les informations suivantes :

• L'ID du projet BigQuery
• L'ID de l'ensemble de données BigQuery
• L'ID de la table BigQuery

L'API Conversational Analytics vous permet de vous connecter à un maximum de 10 tables BigQuery à la fois pour les interroger.

Remarque : Les requêtes qui nécessitent des jointures complexes sur plusieurs tables peuvent générer des réponses moins précises.

Cette section explique comment configurer l'API Conversational Analytics pour qu'elle se connecte à BigQuery à l'aide de requêtes HTTP directes ou d'un SDK.

HTTP avec Python

Une fois que vous vous êtes authentifié auprès de votre projet BigQuery, vous pouvez configurer l'API Conversational Analytics pour accéder aux données dans BigQuery en effectuant des requêtes HTTP directes. L'exemple de code suivant montre comment spécifier les détails de votre source de données BigQuery dans le corps de votre requête HTTP.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "bigquery-public-data",
          "datasetId": "san_francisco",
          "tableId": "street_trees"
        }
      ]
    }
}

Remplacez les exemples de valeurs comme suit :

• bigquery-public-data : ID de votre projet BigQuery.
• san_francisco : ID de l'ensemble de données BigQuery.
• street_trees : ID de la table BigQuery.

SDK Python

Vous pouvez utiliser le SDK auth de Colaboratory pour vous authentifier auprès de BigQuery à l'aide des identifiants de votre utilisateur authentifié auprès de Colaboratory.

L'exemple de code Python suivant montre comment authentifier votre compte Google auprès de BigQuery dans Colaboratory et comment configurer l'API Conversational Analytics pour accéder à une source de données BigQuery.

from google.colab import auth
auth.authenticate_user()

bq_project_id = "YOUR-PROJECT-ID" # @param {type:"string"}
bq_dataset_id = "YOUR-DATASET-ID" # @param {type:"string"}
bq_table_id = "YOUR-TABLE-ID" # @param {type:"string"}

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = bq_project_id
bigquery_table_reference.dataset_id = bq_dataset_id
bigquery_table_reference.table_id = bq_table_id

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

Remplacez les exemples de valeurs comme suit :

• YOUR-PROJECT-ID : ID de votre projet BigQuery.
• YOUR-DATASET-ID : ID de votre ensemble de données BigQuery.
• YOUR-TABLE-ID : ID de votre table BigQuery.

Se connecter à Looker Studio avec l'API Conversational Analytics

Pour vous connecter à Looker Studio avec l'API Conversational Analytics, vous devez d'abord activer l'API Looker Studio. Cette section explique comment configurer l'API Conversational Analytics pour qu'elle se connecte à Looker Studio à l'aide de requêtes HTTP directes ou d'un SDK.

Activer l'API Looker Studio

Pour activer l'API Looker Studio, suivez les instructions de Activer l'API.

S'authentifier auprès de Looker Studio

Pour vous connecter à Looker Studio avec l'API Conversational Analytics, vous devez vous authentifier auprès de Looker Studio et fournir l'ID de la source de données Looker Studio.

HTTP avec Python

Une fois l'API Looker Studio activée, vous pouvez vous authentifier auprès de Looker Studio en envoyant des requêtes HTTP curl avec Python. L'exemple de code suivant montre comment spécifier les détails de votre source de données Looker dans le corps de votre requête HTTP.

Vous pouvez vous authentifier auprès de Looker Studio en envoyant des requêtes HTTP directes. Un exemple d'appel HTTP est présenté dans le bloc de code qui suit.

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

Remplacez your_studio_datasource_id par l'ID de source de données Looker Studio que vous souhaitez utiliser.

SDK Python

Une fois l'API Looker Studio activée, vous pouvez vous authentifier auprès de Looker Studio à l'aide d'un SDK. L'exemple de code Python suivant montre comment spécifier les détails de votre source de données Looker et vous authentifier auprès de Looker Studio.

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]

Remplacez STUDIO-DATASOURCE-ID par l'ID de source de données Looker Studio que vous souhaitez utiliser.