使用 Conversational Analytics API 对数据源进行身份验证并连接到数据源

开发者可以使用通过 geminidataanalytics.googleapis.com 访问的 Conversational Analytics API 构建由人工智能 (AI) 提供支持的对话界面或数据代理，以便使用自然语言回答有关 BigQuery、Looker 和 Looker Studio 中结构化数据的问题。

本页介绍了如何使用直接 HTTP 请求或 SDK 向 Conversational Analytics API 进行身份验证，以及如何在 Looker、BigQuery 和 Looker Studio 中配置与数据的连接。Conversational Analytics API 使用标准的Google Cloud 身份验证方法。

准备工作

在向 Conversational Analytics API 进行身份验证并配置与数据的连接之前，您必须满足前提条件并为 Google Cloud 项目启用所需的 API，如启用 Conversational Analytics API 中所述。

向 Conversational Analytics API 进行身份验证

本部分介绍了如何使用 HTTP 和 Python 方法获取必要的授权令牌，以便（通过 geminidataanalytics.googleapis.com）向 Conversational Analytics API 进行身份验证。

HTTP curl

以下示例 curl 命令会向 Conversational Analytics API 发送请求。gcloud auth print-identity-token 命令会提供用于授权的访问令牌。在代码示例中，将 替换为相应的 API 资源路径。

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

使用 Python 进行 HTTP 通信

以下 Python 代码示例演示了如何使用 Google Cloud CLI 和 Python 获取用于 HTTP 身份验证的访问令牌。

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

按如下所示替换示例值：

  • YOUR_BILLING_PROJECT：已启用所需 API 的结算项目的 ID。
  • method：目标端点的资源路径。例如：
    • 如需创建数据代理，请使用 POST 方法和资源路径 /v1alpha/projects/{billing_project}/locations/global/dataAgents。
    • 如需列出现有数据代理，请使用 GET 方法和资源路径 /v1alpha/projects/{billing_project}/locations/global/dataAgents。

Python SDK

以下 Python 代码示例演示了如何在 Colaboratory 中对您的 Google 账号进行身份验证，以便访问 Conversational Analytics API：

from google.colab import auth
auth.authenticate_user()

使用 Conversational Analytics API 连接到 Looker

如需使用 Conversational Analytics API 连接到 Looker，您必须提供以下信息：

然后，您可以选择使用 Looker API 密钥（客户端 ID 和客户端密钥）或访问令牌进行身份验证。 使用 Looker (Google Cloud Core) 专用 IP 选项的客户必须使用访问令牌进行身份验证。

您一次只能使用 Conversational Analytics API 连接到一个 Looker 探索。

使用 Looker API 密钥进行身份验证

本部分介绍了如何生成 API 密钥，以及如何配置 Conversational Analytics API 以使用直接 HTTP 请求或 SDK 连接到 Looker。 使用 Looker (Google Cloud Core) 专用 IP 选项的客户无法使用此方法，而应使用访问令牌进行身份验证。

如需与 Looker 实例建立连接，您需要有效的 Looker API 密钥，这些密钥由 Looker 创建，包含客户端 ID 和客户端密钥。Looker 使用这些密钥来授权对 Looker API 的请求。

如需详细了解如何生成新的 Looker API 密钥，请参阅管理员设置 - 用户。如需详细了解身份验证方法和如何管理 Looker API 密钥，请参阅 Looker API 身份验证。

使用 Python 进行 HTTP 通信

生成 API 密钥（客户端 ID 和客户端密钥）后，您可以配置 Conversational Analytics API 以通过发出直接 HTTP 请求来连接到 Looker。以下示例代码演示了如何在 HTTP 请求的正文中指定 Looker 数据源详细信息和 API 密钥。


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

按如下所示替换示例值：

  • your_looker_client_id：您生成的 Looker API 密钥的客户端 ID
  • your_looker_client_secret：您生成的 Looker API 密钥的客户端密钥
  • https://your_company.looker.com：Looker 实例的完整网址
  • your_model：您要使用的 LookML 模型的名称
  • your_explore：您要使用的指定模型中的探索名称

Python SDK

生成 API 密钥（客户端 ID 和客户端密钥）后，您可以配置 Conversational Analytics API 以使用 Python 连接到 Looker。以下 Python 代码示例演示了如何向 Conversational Analytics API 指定 Looker 数据源详细信息和 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]

按如下所示替换示例值：

  • YOUR-LOOKER-CLIENT-ID：您生成的 Looker API 密钥的客户端 ID
  • YOUR-LOOKER-CLIENT-SECRET：您生成的 Looker API 密钥的客户端密钥
  • YOUR-LOOKER-INSTANCE-URI：Looker 实例的完整网址
  • YOUR-LOOKER-MODEL：您要使用的 Looker 模型的名称
  • YOUR-LOOKER-EXPLORE：您要使用的 Looker 探索的名称

使用访问令牌进行身份验证

本部分介绍了如何配置 Conversational Analytics API 以使用访问令牌连接到 Looker。

如需与 Looker 实例建立连接，您需要有效的 OAuth2 access_token 值，该值是通过成功向 login Looker API 端点发出请求而创建的。

如需详细了解如何生成访问令牌，请参阅 Looker API 身份验证以及如何提供客户端凭证以获取授权令牌。

使用 Python 进行 HTTP 通信

以下示例代码演示了如何在 HTTP 请求的正文中指定 Looker 数据源详细信息和访问令牌。

建议将 Looker 访问令牌 (access_token) 存储为环境变量，以提高安全性。

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

按如下所示替换示例值：

  • YOUR-TOKEN：您生成的用于向 Looker 进行身份验证的 access_token 值。
  • https://your_company.looker.com：Looker 实例的完整网址
  • your_model：您要使用的 LookML 模型的名称
  • your_explore：您要使用的指定模型中的探索名称

Python SDK

以下 Python 代码示例演示了如何使用 Python SDK 定义 Looker 数据源详细信息和访问令牌以进行身份验证。

建议将 Looker 访问令牌 (access_token) 存储为环境变量，以提高安全性。

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]

按如下所示替换示例值：

  • YOUR-TOKEN：用于向 Looker 进行身份验证的 access_token 值
  • YOUR-LOOKER-INSTANCE-URI：Looker 实例的完整网址
  • YOUR-LOOKER-MODEL：您要使用的 Looker 模型的名称
  • YOUR-LOOKER-EXPLORE：您要使用的 Looker 探索的名称

使用 JavaScript 进行 HTTP 通信

以下示例代码演示了如何在 HTTP 请求的正文中指定 Looker 数据源详细信息和访问令牌。

建议将 Looker 访问令牌 (access_token) 存储为环境变量，以提高安全性。

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

按如下所示替换示例值：

  • YOUR-LOOKER-INSTANCE-URI：Looker 实例的完整网址
  • YOUR-LOOKER-MODEL：您要使用的 LookML 模型的名称
  • YOUR-LOOKER-EXPLORE：您要使用的指定模型中的探索名称
  • YOUR-TOKEN：您生成的用于向 Looker 进行身份验证的 access_token 值。

使用 Conversational Analytics API 连接到 BigQuery

如需使用 Conversational Analytics API 连接到 BigQuery，您必须向 BigQuery 项目进行身份验证并提供以下信息：

  • BigQuery 项目 ID
  • BigQuery 数据集 ID
  • BigQuery 表 ID

借助 Conversational Analytics API，您可以一次性连接和查询最多 10 个 BigQuery 表。

本部分介绍了如何配置 Conversational Analytics API 以使用直接 HTTP 请求或 SDK 连接到 BigQuery。

使用 Python 进行 HTTP 通信

向 BigQuery 项目进行身份验证后，您可以配置 Conversational Analytics API，以通过发出直接 HTTP 请求来访问 BigQuery 中的数据。以下代码示例演示了如何在 HTTP 请求的正文中指定 BigQuery 数据源详细信息。

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "bigquery-public-data",
          "datasetId": "san_francisco",
          "tableId": "street_trees"
        }
      ]
    }
}

按如下所示替换示例值：

  • bigquery-public-data：BigQuery 项目的 ID。
  • san_francisco：BigQuery 数据集的 ID。
  • street_trees：BigQuery 表的 ID

Python SDK

您可以使用 Colaboratory 中的 auth SDK，通过用户的凭据（已向 Colaboratory 进行了身份验证）向 BigQuery 进行身份验证。

以下 Python 代码示例演示了如何在 Colaboratory 中向 BigQuery 进行 Google 账号身份验证，以及如何配置 Conversational Analytics API 以访问 BigQuery 数据源。

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]

按如下所示替换示例值：

  • YOUR-PROJECT-ID：BigQuery 项目的 ID。
  • YOUR-DATASET-ID：BigQuery 数据集的 ID。
  • YOUR-TABLE-ID：BigQuery 表的 ID

使用 Conversational Analytics API 连接到 Looker Studio

如需使用 Conversational Analytics API 连接到 Looker Studio，您必须先启用 Looker Studio API。本部分介绍了如何通过直接 HTTP 请求或 SDK 配置 Conversational Analytics API 以连接到 Looker Studio。

启用 Looker Studio API

如需启用 Looker Studio API，请按照启用 API 中的说明操作。

向 Looker Studio 进行身份验证

如需使用 Conversational Analytics API 连接到 Looker Studio，您必须向 Looker Studio 进行身份验证并提供 Looker Studio 数据源 ID。

使用 Python 进行 HTTP 通信

启用 Looker Studio API 后，您可以通过使用 Python 发出 HTTP curl 请求来向 Looker Studio 进行身份验证。以下示例代码演示了如何在 HTTP 请求的正文中指定 Looker 数据源详细信息。

您可以通过发出直接 HTTP 请求来向 Looker Studio 进行身份验证。以下代码块中演示了一个 HTTP 调用示例。

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

将 your_studio_datasource_id 替换为您要使用的 Looker Studio 数据源的实际 ID。

Python SDK

启用 Looker Studio API 后，您可以使用 SDK 向 Looker Studio 进行身份验证。以下 Python 代码示例演示了如何指定 Looker 数据源详细信息并向 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]

将 STUDIO-DATASOURCE-ID 替换为您要使用的 Looker Studio 数据源的实际 ID。