Cómo autenticar y conectarse a una fuente de datos con la API de Conversational Analytics

Este producto o función se encuentra sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

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

Antes de comenzar

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

Autentica en la API de Conversational Analytics

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

HTTP curl

El siguiente comando de curl de ejemplo envía una solicitud a la API de Conversational Analytics. El comando gcloud auth print-identity-token proporciona un token de acceso que se usa para la autorización. En el muestra de código, reemplaza 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 ejemplo de código de Python, se muestra cómo obtener un token de acceso para la autenticación HTTP con Google Cloud CLI 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]}'}

Reemplaza los valores de muestra de la siguiente manera:

• YOUR_BILLING_PROJECT: Es el ID de tu proyecto de facturación que tiene las APIs requeridas habilitadas.
• method: Es la ruta del recurso del extremo de destino. Por ejemplo:
  • Para crear un agente de datos, usa el método POST y la ruta de acceso al recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.
  • Para enumerar los agentes de datos existentes, usa el método GET y la ruta de acceso al recurso /v1beta/projects/{billing_project}/locations/global/dataAgents.

Python SDK

En el siguiente ejemplo de código de Python, se muestra 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 conectarte a Looker con la API de Conversational Analytics, debes proporcionar la siguiente información:

• La URL de tu instancia de Looker
• El modelo de LookML y el Explorar de Looker específicos que deseas usar como fuente de datos

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

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

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 de Conversational Analytics para conectarse a Looker con solicitudes HTTP directas o el SDK. Los clientes que usan la opción de 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 la API de Looker válidas, que crea Looker y constan de un ID de cliente y un secreto del cliente. Looker usa estas claves para autorizar solicitudes a la API de Looker.

Para obtener más información sobre cómo generar claves de la API de Looker nuevas, consulta Configuración del administrador: Usuarios. Para obtener más información sobre los métodos de autenticación y la administración de las claves de la API de Looker, consulta Autenticación de la API de Looker.

HTTP con Python

Después de generar las claves de API (ID y secreto del cliente), puedes configurar la API de Conversational Analytics para que se conecte a Looker realizando solicitudes HTTP directas. En el siguiente código de ejemplo, se muestra cómo especificar los detalles de tu fuente de datos de Looker y tus claves de API en el cuerpo de tu 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",
    }
  }
}

Reemplaza los valores de muestra de la siguiente manera:

• your_looker_client_id: Es el ID de cliente de la clave de API de Looker que generaste.
• your_looker_client_secret: El secreto del cliente de la clave de API de Looker que generaste
• https://your_company.looker.com: La URL completa de tu instancia de Looker
• your_model: El nombre del modelo de LookML que deseas usar
• your_explore: Nombre de la función Explorar dentro del modelo especificado que deseas usar

Python SDK

Después de generar las claves de API (ID y secreto del cliente), puedes configurar la API de Conversational Analytics para que se conecte a Looker con Python. En el siguiente ejemplo de código en Python, se muestra cómo especificar los detalles de tu fuente de datos de Looker y tus claves de API para la API de Conversational Analytics.

Nota: Para mejorar la seguridad, almacena el ID de cliente de Looker (looker_client_id) y el secreto del cliente de Looker (looker_client_secret) como variables de entorno.

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]

Reemplaza los valores de muestra de la siguiente manera:

• YOUR-LOOKER-CLIENT-ID: Es el ID de cliente de la clave de API de Looker que generaste.
• YOUR-LOOKER-CLIENT-SECRET: El secreto del cliente de la clave de API de Looker que generaste
• YOUR-LOOKER-INSTANCE-URI: La URL completa de tu instancia de Looker
• YOUR-LOOKER-MODEL: El nombre del modelo de Looker que deseas usar
• YOUR-LOOKER-EXPLORE: El nombre de la exploración de Looker que deseas usar

Autenticación con un token de acceso

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

Para establecer una conexión con una instancia de Looker, necesitas un valor access_token de OAuth2 válido, que se crea con una solicitud exitosa al extremo de 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.

Nota: Las credenciales que se usan para generar el valor de access_token deben tener los permisos necesarios para usar los extremos de Looker Get LookML Model Explore y Run Inline Query. El permiso develop es un requisito mínimo.

Uso de una IP pública Uso de una IP privada

HTTP con Python

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

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

Reemplaza los valores de muestra de la siguiente manera:

• YOUR-TOKEN: Es el valor de access_token que generas para autenticarte en Looker.
• https://your_company.looker.com: La URL completa de tu instancia de Looker
• your_model: El nombre del modelo de LookML que deseas usar
• your_explore: Nombre de la función Explorar dentro del modelo especificado que deseas usar

Python SDK

En el siguiente código de muestra en Python, se muestra cómo definir los detalles de tu fuente de datos de Looker y tu token de acceso para autenticarte con el SDK de Python.

Sugerimos almacenar 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]

Reemplaza los valores de muestra de la siguiente manera:

• YOUR-TOKEN: El valor de access_token que usas para autenticarte en Looker
• YOUR-LOOKER-INSTANCE-URI: La URL completa de tu instancia de Looker
• YOUR-LOOKER-MODEL: El nombre del modelo de Looker que deseas usar
• YOUR-LOOKER-EXPLORE: El nombre de la exploración de Looker que deseas usar

HTTP con JavaScript

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

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

Reemplaza los valores de muestra de la siguiente manera:

• YOUR-LOOKER-INSTANCE-URI: La URL completa de tu instancia de Looker
• YOUR-LOOKER-MODEL: El nombre del modelo de LookML que deseas usar
• YOUR-LOOKER-EXPLORE: Nombre de la función Explorar dentro del modelo especificado que deseas usar
• YOUR-TOKEN: Es el valor de access_token que generas para autenticarte en Looker.

Conéctate a BigQuery con la API de Conversational Analytics

Para conectarte a BigQuery con la API de Conversational Analytics, debes autenticarte en tu proyecto de BigQuery y proporcionar la siguiente información:

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

Con la API de Conversational Analytics, puedes conectarte a un máximo de 10 tablas de BigQuery y realizar consultas en ellas al mismo tiempo.

Nota: Las consultas que requieren uniones complejas en varias tablas pueden generar respuestas menos precisas.

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.

HTTP con Python

Después de autenticarte en tu proyecto de BigQuery, puedes configurar la API de Conversational Analytics para acceder a los datos en BigQuery realizando solicitudes HTTP directas. En el siguiente código de ejemplo, se muestra cómo especificar los detalles de tu fuente de datos de BigQuery dentro del cuerpo de tu solicitud HTTP.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "amy_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        # Up to 10 total tables may be included
      ]
    }
}

Reemplaza los valores de muestra de la siguiente manera:

• my_project_id: Es el ID del proyecto 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.
• my_dataset_id: el ID del conjunto de datos de BigQuery.
• my_table_id: el ID de la tabla de BigQuery.

Python SDK

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

En el siguiente ejemplo de código en Python, se muestra cómo autenticar tu Cuenta de Google en BigQuery desde Colaboratory y configurar la API de Conversational Analytics para acceder a una fuente de datos de BigQuery.

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"

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2] # Up to 10 tables

Reemplaza los valores de muestra de la siguiente manera:

• my_project_id: Es el ID del proyecto 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.
• my_dataset_id: el 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

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

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

Habilita la API de Looker Studio

Para habilitar la API de Looker Studio, sigue las instrucciones en Habilita la API.

Autenticación en Looker Studio

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

HTTP con Python

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

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

Reemplaza your_studio_datasource_id por el ID real de la fuente de datos de Looker Studio que deseas usar.

Python SDK

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

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