Developers can use the Conversational Analytics API, accessed through geminidataanalytics.googleapis.com
, to build an artificial intelligence (AI)-powered chat interface, or data agent, that answers questions about structured data in BigQuery, Looker, and Looker Studio using natural language.
This page describes how to authenticate to the Conversational Analytics API and configure connections to your data in Looker, BigQuery, and Looker Studio by using either direct HTTP requests or the SDK. The Conversational Analytics API uses standard Google Cloud authentication methods.
Before you begin
Before you can authenticate to the Conversational Analytics API and configure connections to your data, you must complete the prerequisites and enable the required APIs for your Google Cloud project, as described in Enable the Conversational Analytics API.
Authenticate to the Conversational Analytics API
This section describes how to authenticate to the Conversational Analytics API (through geminidataanalytics.googleapis.com
) by using HTTP and Python methods to obtain the necessary authorization tokens.
The following sample curl
command sends a request to the Conversational Analytics API. The gcloud auth print-identity-token
command provides an access token that is used for authorization. In the code sample, replace
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://geminidataanalytics.googleapis.com/
The following sample Python code demonstrates how to obtain an access token for HTTP authentication by using the Google Cloud CLI and Python.
billing_project = 'YOUR_BILLING_PROJECT '
access_token = !gcloud auth application-default print-access-token
url = f"https://geminidataanalytics.googleapis.com/v1alpha/projects/{billing_project}:method "
headers = {"Authorization": f'Bearer {access_token[0]}'}
Replace the sample values as follows:
- YOUR_BILLING_PROJECT: The ID of your billing project that has the required APIs enabled.
- method: The resource path for the target endpoint. For example:
- To create a data agent, use the
POST
method and the resource path/v1alpha/projects/{billing_project}/locations/global/dataAgents
. - To list existing data agents, use the
GET
method and the resource path/v1alpha/projects/{billing_project}/locations/global/dataAgents
.
- To create a data agent, use the
The following sample Python code demonstrates how to authenticate your Google Account for access to the Conversational Analytics API within Colaboratory:
from google.colab import auth
auth.authenticate_user()
Connect to Looker with the Conversational Analytics API
To connect to Looker with the Conversational Analytics API, you must provide the following information:
- The URL of your Looker instance
- The specific LookML model and Looker Explore that you want to use as a data source
You can then chose to authenticate using either Looker API keys (client ID and client secret) or an access token.
Authentication with Looker API keys
This section describes how to generate the API keys and configure the Conversational Analytics API to connect to Looker by using either direct HTTP requests or the SDK.
To establish a connection with a Looker instance, you need valid Looker API keys, which are created by Looker and consist of a client ID and a client secret. Looker uses these keys to authorize requests to the Looker API.
To learn more about generating new Looker API keys, see Admin settings - Users. To learn more about authentication methods and managing Looker API keys, see Looker API authentication.
After you generate the API keys (client ID and secret), you can configure the Conversational Analytics API to connect to Looker by making direct HTTP requests. The following sample code demonstrates how to specify your Looker data source details and your API keys within the body of your HTTP request.
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 ",
}
}
}
Replace the sample values as follows:
- your_looker_client_id: The client ID of your generated Looker API key
- your_looker_client_secret: The client secret of your generated Looker API key
- https://your_company.looker.com: The complete URL of your Looker instance
- your_model: The name of the LookML model that you want to use
- your_explore: The name of the Explore within the specified model that you want to use
After you generate the API keys (client ID and secret), you can configure the Conversational Analytics API to connect to Looker by using Python. The following sample Python code demonstrates how to specify your Looker data source details and your API keys to the Conversational Analytics API.
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]
Replace the sample values as follows:
- YOUR-LOOKER-CLIENT-ID: The client ID of your generated Looker API key
- YOUR-LOOKER-CLIENT-SECRET: The client secret of your generated Looker API key
- YOUR-LOOKER-INSTANCE-URI: The complete URL of your Looker instance
- YOUR-LOOKER-MODEL: The name of the Looker model that you want to use
- YOUR-LOOKER-EXPLORE: The name of the Looker Explore that you want to use
Authentication with an access token
This section describes how to configure the Conversational Analytics API to connect to Looker using an access token.
To establish a connection with a Looker instance, you need a valid OAuth2 access_token
value, which is created by a successful request to the login
Looker API endpoint.
To learn more about generating an access token, see Looker API authentication and how to present client credentials to obtain an authorization token.
The following sample code demonstrates how to specify your Looker data source details and your access token within the body of your HTTP request.
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 ",
}
}
}
Replace the sample values as follows:
- YOUR-TOKEN: The
access_token
value you generate to authenticate to Looker. - https://your_company.looker.com: The complete URL of your Looker instance
- your_model: The name of the LookML model that you want to use
- your_explore: The name of the Explore within the specified model that you want to use
The following sample Python code demonstrates how to define your Looker data source details and your access token to authenticate using the Python SDK.
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]
Replace the sample values as follows:
- YOUR-TOKEN: The
access_token
value you use to authenticate to Looker - YOUR-LOOKER-INSTANCE-URI: The complete URL of your Looker instance
- YOUR-LOOKER-MODEL: The name of the Looker model that you want to use
- YOUR-LOOKER-EXPLORE: The name of the Looker Explore that you want to use
The following sample code demonstrates how to specify your Looker data source details and your access token within the body of your HTTP request.
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 ,
},
},
},
},
},
},
}
Replace the sample values as follows:
- YOUR-LOOKER-INSTANCE-URI: The complete URL of your Looker instance
- YOUR-LOOKER-MODEL: The name of the LookML model that you want to use
- YOUR-LOOKER-EXPLORE: The name of the Explore within the specified model that you want to use
- YOUR-TOKEN: The
access_token
value you generate to authenticate to Looker.
Connect to BigQuery with the Conversational Analytics API
To connect to BigQuery with the Conversational Analytics API, you must authenticate to your BigQuery project and provide the following information:
- The BigQuery project ID
- The BigQuery dataset ID
- The BigQuery table ID
With the Conversational Analytics API, you can connect to and query up to 10 BigQuery tables at a time.
This section describes how to configure the Conversational Analytics API to connect to BigQuery by using either direct HTTP requests or an SDK.
After you authenticate to your BigQuery project, you can configure the Conversational Analytics API to access data in BigQuery by making direct HTTP requests. The following sample code demonstrates how to specify your BigQuery data source details and within the body of your HTTP request.
bigquery_data_sources = {
"bq": {
"tableReferences": [
{
"projectId": "bigquery-public-data ",
"datasetId": "san_francisco ",
"tableId": "street_trees "
}
]
}
}
Replace the sample values as follows:
- bigquery-public-data: The ID of your BigQuery project
- san_francisco: The ID of the BigQuery dataset
- street_trees: The ID of the BigQuery table
You can use the auth
SDK from Colaboratory to authenticate to BigQuery by using the credentials of your user that is authenticated to Colaboratory.
The following sample Python code demonstrates how to authenticate your Google Account to BigQuery within Colaboratory and configure the Conversational Analytics API to access a BigQuery data source.
from google.colab import auth
auth.authenticate_user()
bq_project_id = "YOUR-PROJECT-ID " # @param {type:"string"}
bq_dataset_id = "YOUR-DATASET-ID " # @param {type:"string"}
bq_table_id = "YOUR-TABLE-ID " # @param {type:"string"}
# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = bq_project_id
bigquery_table_reference.dataset_id = bq_dataset_id
bigquery_table_reference.table_id = bq_table_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference]
Replace the sample values as follows:
- YOUR-PROJECT-ID: The ID of your BigQuery project
- YOUR-DATASET-ID: The ID of your BigQuery dataset
- YOUR-TABLE-ID: The ID of your BigQuery table
Connect to Looker Studio with the Conversational Analytics API
To connect to Looker Studio with the Conversational Analytics API, you must first enable the Looker Studio API. This section describes how to configure the Conversational Analytics API to connect to Looker Studio by using either direct HTTP requests or an SDK.
Enable Looker Studio API
To enable the Looker Studio API, follow the instructions in Enable the API.
Authenticate to Looker Studio
To connect to Looker Studio with the Conversational Analytics API, you must authenticate to Looker Studio and provide the Looker Studio data source ID.
After you enable the Looker Studio API, you can authenticate to Looker Studio by making HTTP curl requests with Python. The following sample code demonstrates how to specify your Looker data source details within the body of your HTTP request.
You can authenticate to Looker Studio by making direct HTTP requests. A sample HTTP call is shown in the following code block.
looker_studio_data_source = {
"studio":{
"studio_references":
[
{
"datasource_id": "your_studio_datasource_id "
}
]
}
}
Replace your_studio_datasource_id with the actual data source ID of the Looker Studio data source that you want to use.
After you enable the Looker Studio API, you can authenticate to Looker Studio by using an SDK. The following sample Python code demonstrates how to specify your Looker data source details and authenticate to 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]
Replace STUDIO-DATASOURCE-ID with the actual data source ID of the Looker Studio data source that you want to use.