Autenticar y conectar con una fuente de datos mediante la API Conversational Analytics

Los desarrolladores pueden usar la API Conversational Analytics, a la que se accede a través de geminidataanalytics.googleapis.com, para crear una interfaz de chat o un agente de datos basados en inteligencia artificial (IA) que responda a preguntas sobre datos estructurados en BigQuery, Looker y Looker Studio usando el lenguaje natural.

En esta página se describe cómo autenticarse en la API Conversational Analytics y configurar conexiones a sus datos en Looker, BigQuery y Looker Studio mediante solicitudes HTTP directas o el SDK. La API Conversational Analytics usa Google Cloud métodos de autenticación estándar.

Antes de empezar

Para poder autenticarte en la API Conversational Analytics y configurar conexiones con tus datos, debes cumplir los requisitos previos y habilitar las APIs necesarias para tu Google Cloud proyecto, tal como se describe en el artículo Habilitar la API Conversational Analytics.

Autenticar en la API Conversational Analytics

En esta sección se describe cómo autenticarse en la API Conversational Analytics (a través de geminidataanalytics.googleapis.com) mediante métodos HTTP y Python para obtener los tokens de autorización necesarios.

HTTP curl

El siguiente comando curl de ejemplo envía una solicitud a la API Conversational Analytics. El comando gcloud auth print-identity-token proporciona un token de acceso que se usa para la autorización. En el código de ejemplo, sustituya por la ruta de recurso de la API adecuada.

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

HTTP con Python

En el siguiente código de ejemplo de Python se muestra cómo obtener un token de acceso para la autenticación HTTP mediante la CLI de Google Cloud y 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]}'}

Sustituye los valores de ejemplo de la siguiente manera:

  • YOUR_BILLING_PROJECT: el ID de tu proyecto de facturación que tiene las APIs necesarias habilitadas.
  • method: ruta de recurso del endpoint de destino. Por ejemplo:
    • Para crear un agente de datos, usa el método POST y la ruta de recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.
    • Para ver una lista de los agentes de datos que ya tenga, use el método GET y la ruta del recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.

SDK de Python

El siguiente código de ejemplo de Python muestra cómo autenticar tu cuenta de Google para acceder a la API Conversational Analytics en Colaboratory:

from google.colab import auth
auth.authenticate_user()

Conectarse a Looker con la API Conversational Analytics

Para conectarse a Looker con la API Conversational Analytics, debe proporcionar la siguiente información:

Además, el usuario o la cuenta de servicio que se autentique debe tener los permisos de Looker necesarios.

A continuación, puedes elegir autenticarte con claves de API de Looker (ID de cliente y secreto de cliente) o con un token de acceso. Los clientes que usen la opción IP privada de Looker (Google Cloud Core) deben autenticarse con un token de acceso.

Con la API Conversational Analytics, solo puedes conectarte a una Exploración de Looker a la vez.

Permisos de Looker necesarios

El usuario o la cuenta de servicio cuyas credenciales se usen para la autenticación deben tener un rol de Looker que incluya los siguientes permisos para los modelos que quieras consultar:

Puede configurar estos permisos en la sección Administrar > Roles de su instancia de Looker.

Autenticación con claves de API de Looker

En esta sección se describe cómo generar las claves de API y configurar la API Conversational Analytics para conectarse a Looker mediante solicitudes HTTP directas o el SDK. Los clientes que usen la opción IP privada de Looker (Google Cloud core) no pueden usar este método y deben autenticarse con un token de acceso.

Para establecer una conexión con una instancia de Looker, necesitas claves de API de Looker válidas, que crea Looker y que constan de un ID de cliente y un secreto de cliente. Looker usa estas claves para autorizar solicitudes a la API de Looker.

Para obtener más información sobre cómo generar nuevas claves de API de Looker, consulta Configuración de administrador - Usuarios. Para obtener más información sobre los métodos de autenticación y la gestión de claves de API de Looker, consulta el artículo Autenticación de la API de Looker.

HTTP con Python

Una vez que hayas generado las claves de API (ID de cliente y secreto), podrás configurar la API Conversational Analytics para que se conecte a Looker haciendo solicitudes HTTP directas. En el siguiente código de ejemplo se muestra cómo especificar los detalles de la fuente de datos de Looker y las claves de API en el cuerpo de la solicitud 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",
    }
  }
}

Sustituye los valores de ejemplo de la siguiente manera:

  • your_looker_client_id: el ID de cliente de la clave de API de Looker que has generado.
  • your_looker_client_secret: el secreto de cliente de la clave de API de Looker que has generado.
  • https://your_company.looker.com: URL completa de tu instancia de Looker
  • your_model: nombre del modelo de LookML que quieras usar
  • your_explore: el nombre del Exploración del modelo especificado que quieras usar.

SDK de Python

Una vez que hayas generado las claves de API (ID de cliente y secreto), podrás configurar la API Conversational Analytics para que se conecte a Looker mediante Python. En el siguiente código de ejemplo de Python se muestra cómo especificar los detalles de tu fuente de datos de Looker y tus claves de API en la 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]

Sustituye los valores de ejemplo de la siguiente manera:

  • YOUR-LOOKER-CLIENT-ID: el ID de cliente de la clave de API de Looker que has generado.
  • YOUR-LOOKER-CLIENT-SECRET: el secreto de cliente de la clave de API de Looker que has generado.
  • YOUR-LOOKER-INSTANCE-URI: URL completa de tu instancia de Looker
  • YOUR-LOOKER-MODEL: el nombre del modelo de Looker que quieras usar.
  • YOUR-LOOKER-EXPLORE: nombre de la Exploración de Looker que quieras usar

Autenticación con un token de acceso

En esta sección se describe cómo configurar la API Conversational Analytics para conectarse a Looker mediante un token de acceso.

Para establecer una conexión con una instancia de Looker, necesitas un valor de OAuth2 access_token válido, que se crea mediante una solicitud correcta al endpoint de la API de Looker login.

Para obtener más información sobre cómo generar un token de acceso, consulta Autenticación de la API de Looker y cómo presentar credenciales de cliente para obtener un token de autorización.

HTTP con Python

En el siguiente ejemplo de código se muestra cómo especificar los detalles de la fuente de datos de Looker y el token de acceso en el cuerpo de la solicitud HTTP.

Te recomendamos que almacenes el token de acceso de Looker (access_token) como una variable de entorno para mejorar la seguridad.

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

Sustituye los valores de ejemplo de la siguiente manera:

  • YOUR-TOKEN: el valor access_token que generas para autenticarte en Looker.
  • https://your_company.looker.com: URL completa de tu instancia de Looker
  • your_model: nombre del modelo de LookML que quieras usar
  • your_explore: el nombre del Exploración del modelo especificado que quieras usar.

SDK de Python

El siguiente código de Python de ejemplo muestra cómo definir los detalles de la fuente de datos de Looker y el token de acceso para autenticarte con el SDK de Python.

Te recomendamos que almacenes el token de acceso de Looker (access_token) como una variable de entorno para mejorar la seguridad.

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]

Sustituye los valores de ejemplo de la siguiente manera:

  • YOUR-TOKEN: el valor de access_token que usas para autenticarte en Looker.
  • YOUR-LOOKER-INSTANCE-URI: URL completa de tu instancia de Looker
  • YOUR-LOOKER-MODEL: el nombre del modelo de Looker que quieras usar.
  • YOUR-LOOKER-EXPLORE: nombre de la Exploración de Looker que quieras usar

HTTP mediante JavaScript

En el siguiente ejemplo de código se muestra cómo especificar los detalles de la fuente de datos de Looker y el token de acceso en el cuerpo de la solicitud HTTP.

Te recomendamos que almacenes el token de acceso de Looker (access_token) como una variable de entorno para mejorar la seguridad.

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

Sustituye los valores de ejemplo de la siguiente manera:

  • YOUR-LOOKER-INSTANCE-URI: URL completa de tu instancia de Looker
  • YOUR-LOOKER-MODEL: nombre del modelo de LookML que quieras usar
  • YOUR-LOOKER-EXPLORE: el nombre del Exploración del modelo especificado que quieras usar.
  • YOUR-TOKEN: el valor access_token que generas para autenticarte en Looker.

Conectarse a BigQuery con la API Conversational Analytics

Para conectarse a una o varias tablas de BigQuery con la API Conversational Analytics, debe autenticarse en el proyecto de BigQuery correspondiente a cada tabla. En cada tabla, proporcione la siguiente información:

  • El ID del proyecto de BigQuery
  • ID del conjunto de datos de BigQuery
  • ID de la tabla de BigQuery

Con la API Conversational Analytics, no hay límites estrictos en el número de tablas de BigQuery a las que puede conectarse. Sin embargo, si te conectas a un gran número de tablas, puede que la precisión se reduzca o que superes el límite de tokens de entrada de Gemini. Las consultas que requieren combinaciones complejas en varias tablas también pueden dar lugar a respuestas menos precisas.

En esta sección se describe cómo configurar la API Conversational Analytics para conectarse a BigQuery mediante solicitudes HTTP directas o un SDK.

HTTP con Python

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

Sustituye los valores de ejemplo de la siguiente manera:

  • my_project_id: ID del Google Cloud proyecto que contiene el conjunto de datos y la tabla de BigQuery a los que quiere conectarse. Para conectarte a un conjunto de datos público, especifica bigquery-public-data.
  • my_dataset_id: ID del conjunto de datos de BigQuery.
  • my_table_id: el ID de la tabla de BigQuery.

SDK de Python

Puedes usar el auth SDK de Colaboratory para autenticarte en BigQuery con las credenciales de tu usuario autenticado en Colaboratory.

El siguiente código de Python de ejemplo define una conexión a varias tablas de BigQuery y muestra cómo autenticar tu cuenta de Google en BigQuery dentro de 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]

Sustituye los valores de ejemplo de la siguiente manera:

  • my_project_id: ID del Google Cloud proyecto que contiene el conjunto de datos y la tabla de BigQuery a los que quiere conectarse. Para conectarte a un conjunto de datos público, especifica bigquery-public-data.
  • my_dataset_id: ID del conjunto de datos de BigQuery. Por ejemplo, san_francisco.
  • my_table_id: el ID de la tabla de BigQuery. Por ejemplo, street_trees.

Conectarse a Looker Studio con la API Conversational Analytics

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

Habilitar la API de Looker Studio

Para habilitar la API Looker Studio, sigue las instrucciones que se indican en Habilitar la API.

Autenticarse en Looker Studio

Para conectarte a Looker Studio con la API Conversational Analytics, debes autenticarte en Looker Studio y proporcionar el ID de la fuente de datos de Looker Studio.

HTTP con Python

Una vez que hayas habilitado la API de Looker Studio, podrás autenticarte en Looker Studio haciendo solicitudes HTTP curl con Python. En el siguiente código de ejemplo se muestra cómo especificar los detalles de la fuente de datos de Looker en el cuerpo de la solicitud HTTP.

Puedes autenticarte en Looker Studio haciendo 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": "your_studio_datasource_id"
            }
        ]
    }
}

Sustituye your_studio_datasource_id por el ID de la fuente de datos de Looker Studio que quieras usar.

SDK de Python

Una vez que hayas habilitado la API de Looker Studio, podrás autenticarte en Looker Studio mediante un SDK. En el siguiente código de Python de ejemplo se muestra cómo especificar los detalles de la fuente de datos de Looker y autenticarse en 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]

Sustituye STUDIO-DATASOURCE-ID por el ID de la fuente de datos de Looker Studio que quieras usar.