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

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.

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/v1beta/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 /v1beta/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 /v1beta/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 :

De plus, l'utilisateur ou le compte de service qui s'authentifie doit disposer des autorisations Looker requises.

Choisir la méthode d'authentification appropriée

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 Looker (Google Cloud Core) avec uniquement des connexions privées doivent s'authentifier avec un jeton d'accès.

Utilisez le tableau suivant pour choisir la méthode d'authentification appropriée.

Type d'utilisateur Méthode d'authentification Pour Looker (version initiale) Pour Looker (Google Cloud Core) Pour Looker (Google Cloud Core) qui n'utilise que des connexions privées Description
Intégrer des utilisateurs Jeton d'accès login_user login_user N/A Respecte les autorisations LookML au niveau des lignes et des colonnes (par exemple, access_filters, access_grants, sql_always_where) du access_token de l'utilisateur cible.
Utilisateurs standards Jeton d'accès

login_user

Ou

Client OAuth

 Client OAuth Client OAuth Respecte les autorisations LookML au niveau des lignes et des colonnes (par exemple, access_filters, access_grants, sql_always_where) du access_token de l'utilisateur cible.
Compte de service Looker réservé à l'API Clé API ID client et code secret ID client et code secret N/A Tous les utilisateurs partagent le même niveau d'accès à Looker.

Les clés API utilisent les autorisations et les niveaux d'accès de l'utilisateur. Les clés API peuvent être utiles si vous créez une application dans laquelle tous les utilisateurs partagent le même niveau d'accès.

Un jeton d'accès vous permet d'utiliser les autorisations LookML au niveau des lignes et des colonnes (par exemple,access_filters, access_grants, sql_always_where) du access_token de l'utilisateur cible. Un jeton d'accès est utile pour une application mutualisée.

Autorisations Looker requises

L'utilisateur ou le compte de service dont les identifiants sont utilisés pour l'authentification doit disposer d'un rôle Looker qui inclut les autorisations suivantes pour les modèles que vous souhaitez interroger :

Vous pouvez configurer ces autorisations dans la section Admin > Rôles de votre instance Looker.

S'authentifier 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.

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.

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.

S'authentifier 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.

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 à une ou plusieurs tables BigQuery avec l'API Conversational Analytics, vous devez vous authentifier auprès du projet BigQuery correspondant pour chaque table. Pour chaque tableau, fournissez 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 ne limite pas le nombre de tables BigQuery auxquelles vous pouvez vous connecter. Toutefois, la connexion à un grand nombre de tables peut réduire la précision ou vous faire dépasser la limite de jetons d'entrée de Gemini. Les requêtes qui nécessitent des jointures complexes sur plusieurs tables peuvent également 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

L'exemple de code suivant définit une connexion à plusieurs tables BigQuery.

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

Remplacez les exemples de valeurs comme suit :

  • my_project_id : ID du projet Google Cloud contenant l'ensemble de données et la table BigQuery auxquels vous souhaitez vous connecter. Pour vous connecter à un ensemble de données public, spécifiez bigquery-public-data.
  • my_dataset_id : ID de l'ensemble de données BigQuery.
  • my_table_id : 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 définit une connexion à plusieurs tables BigQuery et montre comment authentifier votre compte Google auprès de BigQuery dans Colaboratory.

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]

Remplacez les exemples de valeurs comme suit :

  • my_project_id : ID du projet Google Cloud contenant l'ensemble de données et la table BigQuery auxquels vous souhaitez vous connecter. Pour vous connecter à un ensemble de données public, spécifiez bigquery-public-data.
  • my_dataset_id : ID de l'ensemble de données BigQuery. Par exemple, san_francisco.
  • my_table_id : ID de la table BigQuery. Par exemple, street_trees.

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.