Cette page explique comment s'authentifier auprès de l'API Conversational Analytics. Elle explique également comment configurer des connexions à vos données dans Looker, BigQuery, Data Studio et des bases de données (AlloyDB, GoogleSQL pour Spanner, Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL) à 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.
Si vous prévoyez d'utiliser des clés de chiffrement gérées par le client (CMEK) pour protéger vos ressources de l'API Conversational Analytics, vous devez autoriser le compte de service de l'API à utiliser votre clé Cloud Key Management Service. Pour en savoir plus, consultez la section Avant de commencer de la documentation sur les CMEK.
S'authentifier auprès de l'API Conversational Analytics
Cette section explique comment s'authentifier auprès de l'API Conversational Analytics à l'aide des méthodes HTTP et Python pour obtenir les jetons d'autorisation nécessaires. Les exemples suivants utilisent une logique de point de terminaison régional basée sur l'emplacement de la ressource. Pour en savoir plus sur les points de terminaison régionaux, consultez Résidence des données.
HTTP curl
L'exemple de commande curl suivant cible une méthode de point de terminaison d'API pour montrer comment envoyer une requête authentifiée à l'aide du jeton d'identité généré par la Google Cloud CLI :
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD
Remplacez les exemples de valeurs comme suit :
- ENDPOINT_URL : URL du point de terminaison du service correspondant à votre emplacement, par exemple
geminidataanalytics.googleapis.compour l'emplacement par défautglobalougeminidataanalytics.us.rep.googleapis.compour l'emplacement multirégionalus. - PROJECT_ID : ID du projet Google Cloud dans lequel vous avez activé les API requises.
LOCATION : emplacement où vos ressources sont stockées (par exemple,
globalouus-east4).METHOD : méthode ou chemin d'accès à la ressource du point de terminaison cible (par exemple,
dataAgentspour créer un agent oudataAgents/AGENT_IDpour obtenir un agent spécifique).
HTTP avec Python
L'exemple de code Python suivant cible une méthode de point de terminaison de l'API pour montrer comment obtenir un jeton d'accès et envoyer une requête HTTP authentifiée. Le code crée dynamiquement l'URL du point de terminaison en fonction du type d'emplacement spécifié.
billing_project = 'PROJECT_ID'
location = 'LOCATION'
access_token = !gcloud auth application-default print-access-token
# Set the base URL based on location.
if not location or location == "global":
base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
# Regional endpoints
base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
# Multi-regional endpoints
base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"
url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/METHOD"
headers = {"Authorization": f'Bearer {access_token[0]}'}
Remplacez les exemples de valeurs comme suit :
- PROJECT_ID : ID du projet Google Cloud dans lequel vous avez activé les API requises.
LOCATION : emplacement où vos ressources sont stockées (par exemple,
globalouus-east4).METHOD : méthode ou chemin d'accès à la ressource du point de terminaison cible. Exemple :
- Pour créer un agent de données, utilisez la méthode
POSTet spécifiezdataAgents. - Pour lister les agents de données existants, utilisez la méthode
GETet spécifiezdataAgents.
- Pour créer un agent de données, utilisez la méthode
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 connaître les rôles et autorisations requis, les options d'autorisation et des exemples de code permettant de se connecter aux explorations Looker, consultez Se connecter à Looker. Pour les instances qui n'utilisent que des connexions privées, consultez Se connecter à une instance Looker (Google Cloud Core) qui utilise des connexions privées.
Se connecter à BigQuery avec l'API Conversational Analytics
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. L'API Conversational Analytics est compatible avec les connexions aux tables BigQuery et aux graphiques avec BigQuery Graph.
L'API Conversational Analytics n'impose pas de limite stricte au 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.
Se connecter à des tables
Pour vous connecter à une ou plusieurs tables BigQuery, indiquez l'ID du projet, l'ID de l'ensemble de données et l'ID de chaque table.
Les exemples suivants montrent comment se connecter à une ou plusieurs tables BigQuery à l'aide de requêtes HTTP ou du SDK Python.
HTTP avec Python
L'exemple de code suivant définit une connexion à plusieurs tables BigQuery :
bigquery_data_sources = {
"bq": {
"tableReferences": [
{
"projectId": "PROJECT_ID",
"datasetId": "DATASET_ID",
"tableId": "TABLE_ID"
},
{
"projectId": "PROJECT_ID_2",
"datasetId": "DATASET_ID_2",
"tableId": "TABLE_ID_2"
},
{
"projectId": "PROJECT_ID_3",
"datasetId": "DATASET_ID_3",
"tableId": "TABLE_ID_3"
},
]
}
}
Remplacez les exemples de valeurs comme suit :
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3 : 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. - DATASET_ID, DATASET_ID_2, DATASET_ID_3 : ID de l'ensemble de données BigQuery (ou
catalog.namespacepour les tables de catalogue d'environnements d'exécution Lakehouse). - TABLE_ID, TABLE_ID_2, TABLE_ID_3 : ID de la table BigQuery (ou nom de la table pour les tables du catalogue d'environnements d'exécution Lakehouse).
SDK Python
Vous pouvez utiliser le SDK auth de Colaboratory pour vous authentifier à l'aide des identifiants de votre compte Google et autoriser le client Colab à accéder à BigQuery à l'aide de vos identifiants.
L'exemple de code Python suivant définit une connexion à plusieurs tables BigQuery et montre comment s'authentifier à l'aide des identifiants de votre compte Google dans Colaboratory pour autoriser les requêtes.
from google.colab import auth
auth.authenticate_user()
# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "PROJECT_ID"
bigquery_table_reference.dataset_id = "DATASET_ID"
bigquery_table_reference.table_id = "TABLE_ID"
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "PROJECT_ID_2"
bigquery_table_reference_2.dataset_id = "DATASET_ID_2"
bigquery_table_reference_2.table_id = "TABLE_ID_2"
bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "PROJECT_ID_3"
bigquery_table_reference_3.dataset_id = "DATASET_ID_3"
bigquery_table_reference_3.table_id = "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 :
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3 : 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. - DATASET_ID, DATASET_ID_2, DATASET_ID_3 : ID de l'ensemble de données BigQuery (ou
catalog.namespacepour les tables de catalogue d'environnements d'exécution Lakehouse). Par exemple,san_francisco. - TABLE_ID, TABLE_ID_2, TABLE_ID_3 : ID de la table BigQuery (ou nom de la table pour les tables du catalogue d'environnements d'exécution Lakehouse). Par exemple,
street_trees.
Se connecter à BigQuery Graph
Les exemples suivants montrent comment se connecter à un ou plusieurs graphiques avec BigQuery Graph à l'aide de requêtes HTTP ou du SDK Python.
Pour en savoir plus sur les exigences liées aux éditions BigQuery et les limites des requêtes de graphe, consultez Se connecter à BigQuery Graph.
HTTP avec Python
L'exemple de code suivant définit une connexion à un graphe BigQuery :
bigquery_data_sources = {
"bq": {
"propertyGraphReferences": [
{
"projectId": "GRAPH_PROJECT_ID",
"datasetId": "GRAPH_DATASET_ID",
"propertyGraphId": "GRAPH_ID"
}
]
}
}
Remplacez les exemples de valeurs comme suit :
- GRAPH_PROJECT_ID : ID du projet Google Cloud contenant le graphe BigQuery.
- GRAPH_DATASET_ID : ID de l'ensemble de données BigQuery contenant le graphe.
- GRAPH_ID : ID du graphe 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 à un graphe BigQuery :
from google.colab import auth
auth.authenticate_user()
# BigQuery graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]
Remplacez les exemples de valeurs comme suit :
- GRAPH_PROJECT_ID : ID du projet Google Cloud contenant le graphe BigQuery.
- GRAPH_DATASET_ID : ID de l'ensemble de données BigQuery contenant le graphe.
- GRAPH_ID : ID du graphe BigQuery.
Se connecter à Data Studio avec l'API Conversational Analytics
Pour vous connecter à Data Studio avec l'API Conversational Analytics, vous devez d'abord activer l'API Data Studio. Cette section explique comment configurer l'API Conversational Analytics pour qu'elle se connecte à Data Studio à l'aide de requêtes HTTP directes ou d'un SDK.
Pour utiliser l'API Conversational Analytics avec Data Studio Pro, votre abonnement Pro doit se trouver en dehors d'un périmètre VPC-SC.
Activer l'API Data Studio
Pour activer l'API Data Studio, suivez les instructions de Activer l'API.
S'authentifier auprès de Data Studio
Pour vous connecter à Data Studio avec l'API Conversational Analytics, vous devez vous assurer que l'utilisateur ou le compte de service authentifié est autorisé à accéder à la source de données Data Studio, puis fournir l'ID de la source de données.
HTTP avec Python
Une fois l'API Data Studio activée, vous pouvez vous connecter à Data 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 Data Studio dans le corps de votre requête HTTP.
Vous pouvez vous connecter à Data 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": "DATASOURCE_ID"
}
]
}
}
Remplacez your_studio_datasource_id par l'ID de source de données Data Studio que vous souhaitez utiliser.
SDK Python
Une fois l'API Data Studio activée, vous pouvez vous connecter à Data 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 Data Studio.
datasource_id = "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 Data Studio que vous souhaitez utiliser.
Se connecter à des bases de données avec l'API Conversational Analytics
Pour vous connecter à des bases de données avec l'API Conversational Analytics, vous devez disposer des autorisations IAM nécessaires pour votre instance de base de données. Facultatif : Si vous utilisez des ensembles de contexte (bêta) avec votre source de données de base de données, pour créer, importer ou gérer des ensembles de contexte, vous devez également activer l'API Knowledge Catalog et accorder le rôle Éditeur de catalogue Dataplex (roles/dataplex.catalogEditor) ou Administrateur de catalogue Dataplex (roles/dataplex.catalogAdmin) sur le projet. Pour en savoir plus, consultez Autorisations des ensembles de contextes.
Se connecter à AlloyDB pour PostgreSQL
L'utilisateur ou le compte de service doit disposer du rôle alloydb.databaseUser. Pour en savoir plus, consultez Authentification IAM pour les bases de données AlloyDB.
HTTP avec Python
L'exemple de code suivant montre comment spécifier les détails de votre source de données AlloyDB dans le corps de votre requête HTTP.
alloydb_data_sources = {
"alloydb": {
"database_reference": {
"project_id": alloydb_project_id,
"region": location,
"cluster_id": alloydb_cluster_id,
"instance_id": alloydb_instance_id,
"database_id": alloydb_database_id,
"table_ids":["table1", "table2", "table3"]
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/alloydb_project_id/locations/{location}/contextSets/your_context_set_id"
# }
}
}
Remplacez les exemples de valeurs comme suit :
- your_table_id : liste d'ID de table séparés par une virgule. Si ce paramètre n'est pas défini, toutes les tables de la base de données sont prises en compte.
- your_context_set_id (facultatif) : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation AlloyDB.
SDK Python
L'exemple de code Python suivant montre comment définir les détails de votre source de données AlloyDB à l'aide du SDK Python.
# AlloyDB data source
alloydb_table_ids = ["your_table_id_1", "your_table_id_2"]
alloydb_context_set_id = "your_context_set_id"
alloydb_reference = geminidataanalytics.AlloyDbReference()
alloydb_reference.database_reference.table_id = alloydb_table_ids
alloydb_reference_database_reference.project_id = billing_project
alloydb_reference_database_reference.region = "us-central1" # Example region
alloydb_reference_database_reference.cluster_id = alloydb_cluster_id
alloydb_reference_database_reference.instance_id = alloydb_instance_id
alloydb_reference_database_reference.database_id = alloydb_database_id
# optional set agent context reference
# alloydb_ref_1.agent_context_reference.context_set_id = f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
alloydb_reference.agent_context_reference.context_set_id = alloydb_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.alloydb.alloydb_reference = alloydb_reference
Remplacez les exemples de valeurs comme suit :
- your_table_id_1 : ID de la première table de votre instance AlloyDB.
- your_table_id_2 : ID de la deuxième table de votre instance AlloyDB.
- your_context_set_id : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation AlloyDB.
Se connecter à GoogleSQL pour Spanner
L'utilisateur ou le compte de service doit disposer du rôle spanner.databaseReader. Pour en savoir plus, consultez Appliquer des rôles IAM.
HTTP avec Python
L'exemple de code suivant montre comment spécifier les détails de votre source de données GoogleSQL pour Spanner dans le corps de votre requête HTTP.
spanner_data_sources = {
"spanner_reference": {
"database_reference": {
"project_id": spanner_project_id,
"region": location,
"engine": engine,
"instance_id": spanner_instance_id,
"database_id": spanner_database_id,
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
# }
}
}
Remplacez les exemples de valeurs comme suit :
- your_table_id_1 : ID de la première table de votre instance GoogleSQL pour Spanner.
- your_table_id_2 : ID de la deuxième table de votre instance GoogleSQL pour Spanner.
- your_context_set_id : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation Spanner.
SDK Python
L'exemple de code Python suivant montre comment définir les détails de votre source de données GoogleSQL pour Spanner à l'aide du SDK Python.
# Spanner data source
spanner_table_ids = ["your_table_id_1", "your_table_id_2"]
spanner_context_set_id = "your_context_set_id"
spanner_reference = geminidataanalytics.SpannerReference()
spanner_reference.database_reference.table_id = spanner_table_ids
spanner_reference.agent_context_reference.context_set_id = spanner_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.spanner.spanner_reference = spanner_reference
Remplacez les exemples de valeurs comme suit :
- your_table_id_1 : ID de la première table de votre instance GoogleSQL pour Spanner.
- your_table_id_2 : ID de la deuxième table de votre instance GoogleSQL pour Spanner.
- your_context_set_id : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation Spanner.
Se connecter à Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL
Les sections suivantes expliquent comment se connecter à Cloud SQL pour MySQL et à Cloud SQL pour PostgreSQL. L'utilisateur ou le compte de service doit disposer des rôles cloudsql.studioUser et cloudsql.instanceUser. Pour en savoir plus, consultez Gérer les utilisateurs avec l'authentification IAM pour les bases de données Cloud SQL pour MySQL et Gérer les utilisateurs avec l'authentification IAM pour les bases de données Cloud SQL pour PostgreSQL.
HTTP avec Python
L'exemple de code suivant montre comment spécifier les détails de votre source de données Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL dans le corps de votre requête HTTP.
cloudsql_data_source = {
"cloudSqlReference": {
"databaseReference": {
"engine": MYSQL,
"project_id": cloud-db-nl2sql,
"region": us-central1,
"instance_id": nl2sql-birdsql-mysql,
"database_id": financial
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/cloud-db-nl2sql/locations/us-central1/contextSets/bdf_pg_all_templates\"
# }
}
}
Remplacez les exemples de valeurs comme suit :
- your_table_id_1 : ID de la première table de votre instance Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL.
- your_table_id_2 : ID de la deuxième table de votre instance Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL.
- your_context_set_id : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation de Cloud SQL pour MySQL et de Cloud SQL pour PostgreSQL.
SDK Python
L'exemple de code Python suivant montre comment définir les détails de vos sources de données Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL à l'aide du SDK Python.
# Cloud SQL data source
cloudsql_table_ids = ["your_table_id_1", "your_table_id_2"]
cloudsql_context_set_id = "your_context_set_id"
cloudsql_reference = geminidataanalytics.CloudSqlReference()
cloudsql_reference.database_reference.table_id = cloudsql_table_ids
cloudsql_reference.agent_context_reference.context_set_id = cloudsql_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloudsql.cloudsql_reference = cloudsql_reference
Remplacez les exemples de valeurs comme suit :
- your_table_id_1 : ID de la première table de votre instance Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL.
- your_table_id_2 : ID de la deuxième table de votre instance Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL.
- your_context_set_id : ID complet de l'ensemble de contextes à récupérer. Pour savoir comment trouver l'ID de l'ensemble de contexte, consultez la documentation de Cloud SQL pour MySQL et de Cloud SQL pour PostgreSQL.