Autentica la identidad del usuario y conéctate a una fuente de datos

En esta página, se describe cómo autenticarte en la API de Conversational Analytics. También se explica cómo configurar conexiones a tus datos en Looker, BigQuery, Data Studio y bases de datos (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL) con solicitudes HTTP directas o el SDK. La API de Conversational Analytics usa Google Cloud métodos de autenticación estándar de .

Antes de comenzar

Antes de autenticarte en la API de Conversational Analytics y configurar las conexiones a tus datos, debes completar los requisitos previos y habilitar las APIs necesarias para tu proyecto de Google Cloud , como se describe en Habilita la API de Conversational Analytics.

Si planeas usar claves de encriptación administradas por el cliente (CMEK) para proteger tus recursos de la API de Conversational Analytics, debes otorgarle a la cuenta de servicio de la API permiso para usar tu clave de Cloud Key Management Service. Para obtener más detalles, consulta Antes de comenzar en la documentación de CMEK.

Autentícate en la API de Conversational Analytics

En esta sección, se describe cómo autenticarse en la API de Conversational Analytics con métodos HTTP y de Python para obtener los tokens de autorización necesarios. En los siguientes ejemplos, se usa la lógica de extremos regionales según la ubicación del recurso. Para obtener más información sobre los extremos regionales, consulta Residencia de datos.

curl HTTP

En el siguiente comando de curl de ejemplo, se orienta a un método de extremo de API para demostrar cómo enviar una solicitud autenticada con el token de identidad que genera Google Cloud CLI:

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD

Reemplaza los valores de muestra de la siguiente manera:

  • ENDPOINT_URL: Es la URL del extremo de servicio que corresponde a tu ubicación, por ejemplo, geminidataanalytics.googleapis.com para la ubicación predeterminada global o geminidataanalytics.us.rep.googleapis.com para la multirregión us.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud en el que habilitaste las APIs requeridas.
  • LOCATION: Es la ubicación en la que se almacenan tus recursos (por ejemplo, global o us-east4).

  • METHOD: Es el método de extremo de destino o la ruta de acceso del recurso (por ejemplo, dataAgents para crear un agente o dataAgents/AGENT_ID para obtener un agente específico).

HTTP con Python

En el siguiente código de Python de ejemplo, se orienta a un método de extremo de API para demostrar cómo obtener un token de acceso y enviar una solicitud HTTP autenticada. El código compila de forma dinámica la URL del extremo según el tipo de ubicación especificado.

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]}'}

Reemplaza los valores de muestra de la siguiente manera:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud en el que habilitaste las APIs requeridas.
  • LOCATION: Es la ubicación en la que se almacenan tus recursos (por ejemplo, global o us-east4).

  • METHOD: Es el método del extremo de destino o la ruta de acceso del recurso. Por ejemplo:

    • Para crear un agente de datos, usa el método POST y especifica dataAgents.
    • Para enumerar los agentes de datos existentes, usa el método GET y especifica dataAgents.

Python SDK

En el siguiente código de Python de muestra, se indica cómo autenticar tu Cuenta de Google para acceder a la API de Conversational Analytics en Colaboratory:

from google.colab import auth
auth.authenticate_user()

Conéctate a Looker con la API de Conversational Analytics

Para conocer los roles y permisos necesarios, las opciones de autorización y el código de muestra para conectarte a las exploraciones de Looker, consulta Conéctate a Looker. Para las instancias que solo usan conexiones privadas, consulta Conéctate a una instancia de Looker (Google Cloud Core) que use conexiones privadas.

Conéctate a BigQuery con la API de Conversational Analytics

En esta sección, se describe cómo configurar la API de Conversational Analytics para conectarse a BigQuery con solicitudes HTTP directas o un SDK. La API de Conversational Analytics admite conexiones a tablas de BigQuery y a grafos con BigQuery Graph.

Con la API de Conversational Analytics, no hay límites estrictos en la cantidad de tablas de BigQuery a las que puedes conectarte. Sin embargo, conectarse a una gran cantidad de tablas puede reducir la exactitud o hacer que excedas el límite de tokens de entrada de Gemini. Las consultas que requieren uniones complejas en varias tablas también pueden generar respuestas menos precisas.

Conectarse a tablas

Para conectarte a una o más tablas de BigQuery, proporciona el ID del proyecto, el ID del conjunto de datos y el ID de la tabla para cada tabla.

En los siguientes ejemplos, se muestra cómo conectarse a una o más tablas de BigQuery con solicitudes HTTP o el SDK de Python.

HTTP con Python

En el siguiente código de muestra, se define una conexión a varias tablas de 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"
        },
      ]
    }
}

Reemplaza los valores de muestra de la siguiente manera:

  • PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos y la tabla de BigQuery a los que deseas conectarte. Para conectarte a un conjunto de datos públicos, especifica bigquery-public-data.
  • DATASET_ID, DATASET_ID_2, DATASET_ID_3: Es el ID del conjunto de datos de BigQuery (o catalog.namespace para las tablas del catálogo de tiempo de ejecución de Lakehouse).
  • TABLE_ID, TABLE_ID_2, TABLE_ID_3: Es el ID de la tabla de BigQuery (o el nombre de la tabla para las tablas del catálogo de tiempo de ejecución de Lakehouse).

Python SDK

Puedes usar el SDK de auth desde Colaboratory para autenticarte con las credenciales de tu Cuenta de Google y autorizar al cliente de Colab a acceder a BigQuery con tus credenciales.

En el siguiente código de Python de ejemplo, se define una conexión a varias tablas de BigQuery y se muestra cómo autenticarte con las credenciales de tu Cuenta de Google en Colaboratory para autorizar solicitudes.

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]

Reemplaza los valores de muestra de la siguiente manera:

  • PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: Es el ID del proyecto de Google Cloud que contiene el conjunto de datos y la tabla de BigQuery a los que deseas conectarte. Para conectarte a un conjunto de datos públicos, especifica bigquery-public-data.
  • DATASET_ID, DATASET_ID_2, DATASET_ID_3: Es el ID del conjunto de datos de BigQuery (o catalog.namespace para las tablas del catálogo de tiempo de ejecución de Lakehouse). Por ejemplo, san_francisco.
  • TABLE_ID, TABLE_ID_2, TABLE_ID_3: Es el ID de la tabla de BigQuery (o el nombre de la tabla para las tablas del catálogo de tiempo de ejecución de Lakehouse). Por ejemplo, street_trees.

Conéctate a BigQuery Graph

En los siguientes ejemplos, se muestra cómo conectarse a uno o más grafos con BigQuery Graph a través de solicitudes HTTP o el SDK de Python.

Para obtener información sobre los requisitos de la edición de BigQuery y las limitaciones de las consultas de grafos, consulta Conéctate a BigQuery Graph.

HTTP con Python

En el siguiente código de muestra, se define una conexión a un grafo de BigQuery:

bigquery_data_sources = {
    "bq": {
      "propertyGraphReferences": [
        {
          "projectId": "GRAPH_PROJECT_ID",
          "datasetId": "GRAPH_DATASET_ID",
          "propertyGraphId": "GRAPH_ID"
        }
      ]
    }
}

Reemplaza los valores de muestra de la siguiente manera:

  • GRAPH_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el grafo de BigQuery.
  • GRAPH_DATASET_ID: Es el ID del conjunto de datos de BigQuery que contiene el grafo.
  • GRAPH_ID: Es el ID del grafo de BigQuery.

Python SDK

Puedes usar el SDK de auth de Colaboratory para autenticarte en BigQuery con las credenciales de tu usuario que se autenticó en Colaboratory.

En el siguiente código de Python de ejemplo, se define una conexión a un grafo de 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]

Reemplaza los valores de muestra de la siguiente manera:

  • GRAPH_PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene el grafo de BigQuery.
  • GRAPH_DATASET_ID: Es el ID del conjunto de datos de BigQuery que contiene el grafo.
  • GRAPH_ID: Es el ID del grafo de BigQuery.

Conéctate a Data Studio con la API de Conversational Analytics

Para conectarte a Data Studio con la API de Conversational Analytics, primero debes habilitar la API de Data Studio. En esta sección, se describe cómo configurar la API de Conversational Analytics para conectarse a Data Studio con solicitudes HTTP directas o un SDK.

Para usar la API de Conversational Analytics con Data Studio Pro, tu suscripción a Pro debe estar fuera de un perímetro de VPC-SC.

Habilita la API de Data Studio

Para habilitar la API de Data Studio, sigue las instrucciones que se indican en Habilita la API.

Autentícate en Data Studio

Para conectarte a Data Studio con la API de Conversational Analytics, debes asegurarte de que el usuario o la cuenta de servicio autenticados tengan autorización para acceder a la fuente de datos de Data Studio y, luego, proporcionar el ID de la fuente de datos.

HTTP con Python

Después de habilitar la API de Data Studio, puedes conectarte a Data Studio realizando solicitudes HTTP curl con Python. En el siguiente código de muestra, se indica cómo especificar los detalles de tu fuente de datos de Data Studio en el cuerpo de tu solicitud HTTP.

Puedes conectarte a Data Studio realizando solicitudes HTTP directas. En el siguiente bloque de código, se muestra una llamada HTTP de ejemplo.

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

Reemplaza your_studio_datasource_id por el ID real de la fuente de datos de Data Studio que quieras usar.

Python SDK

Después de habilitar la API de Data Studio, puedes conectarte a Data Studio con un SDK. En el siguiente código de Python de muestra, se indica cómo especificar los detalles de tu fuente de datos de 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]

Reemplaza STUDIO-DATASOURCE-ID por el ID real de la fuente de datos de Data Studio que quieras usar.

Conéctate a bases de datos con la API de Conversational Analytics

Para conectarte a bases de datos con la API de Conversational Analytics, debes tener los permisos de IAM necesarios para tu instancia de base de datos. De forma opcional, si usas conjuntos de contexto (versión preliminar) con tu fuente de datos de la base de datos, para crear, subir o administrar conjuntos de contexto, también debes habilitar la API de Knowledge Catalog y otorgar el rol de editor de Dataplex Catalog (roles/dataplex.catalogEditor) o administrador de Dataplex Catalog (roles/dataplex.catalogAdmin) en el proyecto. Para obtener más información, consulta El contexto establece permisos.

Conéctate a AlloyDB para PostgreSQL

La cuenta de servicio o el usuario debe tener el rol alloydb.databaseUser. Para obtener más información, consulta Autenticación de la base de datos de IAM de AlloyDB.

HTTP con Python

En el siguiente código de muestra, se indica cómo especificar los detalles de tu fuente de datos de AlloyDB en el cuerpo de tu solicitud 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"
      # }
  }
}

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id: Es la lista separada por comas de los IDs de tabla. Si no se establece, se consideran todas las tablas de la base de datos.
  • your_context_set_id: Opcional: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de AlloyDB.

Python SDK

En el siguiente código de Python de ejemplo, se muestra cómo definir los detalles de tu fuente de datos de AlloyDB con el SDK de 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

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id_1: Es el ID de la primera tabla de tu instancia de AlloyDB.
  • your_table_id_2: Es el ID de la segunda tabla de tu instancia de AlloyDB.
  • your_context_set_id: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de AlloyDB.

Conéctate a GoogleSQL para Spanner

La cuenta de servicio o el usuario debe tener el rol spanner.databaseReader. Para obtener más información, consulta Aplica roles de IAM.

HTTP con Python

En el siguiente código de muestra, se indica cómo especificar los detalles de tu fuente de datos de GoogleSQL para Spanner en el cuerpo de tu solicitud 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"
        # }
    }
}

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id_1: Es el ID de la primera tabla en tu instancia de GoogleSQL para Spanner.
  • your_table_id_2: Es el ID de la segunda tabla en tu instancia de GoogleSQL para Spanner.
  • your_context_set_id: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de Spanner.

Python SDK

En el siguiente código de muestra de Python, se indica cómo definir los detalles de la fuente de datos de GoogleSQL para Spanner con el SDK de 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

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id_1: Es el ID de la primera tabla en tu instancia de GoogleSQL para Spanner.
  • your_table_id_2: Es el ID de la segunda tabla en tu instancia de GoogleSQL para Spanner.
  • your_context_set_id: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de Spanner.

Conéctate a Cloud SQL para MySQL y Cloud SQL para PostgreSQL

En las siguientes secciones, se proporcionan instrucciones para conectarse a Cloud SQL para MySQL y Cloud SQL para PostgreSQL. La cuenta de servicio o el usuario debe tener los roles cloudsql.studioUser y cloudsql.instanceUser. Para obtener más información, consulta Administra usuarios con la autenticación de bases de datos de IAM para Cloud SQL para MySQL y Administra usuarios con la autenticación de bases de datos de IAM para Cloud SQL para PostgreSQL.

HTTP con Python

En el siguiente código de muestra, se indica cómo especificar los detalles de la fuente de datos de Cloud SQL para MySQL y Cloud SQL para PostgreSQL en el cuerpo de la solicitud 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\"
        # }
    }
}

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id_1: Es el ID de la primera tabla de tu instancia de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.
  • your_table_id_2: Es el ID de la segunda tabla en tu instancia de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.
  • your_context_set_id: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.

Python SDK

En el siguiente código de Python de ejemplo, se muestra cómo definir los detalles de la fuente de datos de Cloud SQL para MySQL y Cloud SQL para PostgreSQL con el SDK de 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

Reemplaza los valores de muestra de la siguiente manera:

  • your_table_id_1: Es el ID de la primera tabla de tu instancia de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.
  • your_table_id_2: Es el ID de la segunda tabla en tu instancia de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.
  • your_context_set_id: Es el ID completo del conjunto de contextos que se recuperará. Para obtener más información sobre cómo encontrar el ID del conjunto de contexto, consulta la documentación de Cloud SQL para MySQL y Cloud SQL para PostgreSQL.