验证用户身份并连接到数据源

本页面介绍了如何向对话式分析 API 进行身份验证。此外,还介绍了如何使用直接 HTTP 请求或 SDK 配置与 Looker、BigQuery、数据洞察和数据库(AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL)中数据的连接。对话式分析 API 使用标准 Google Cloud 身份验证方法。

准备工作

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

如果您计划使用客户管理的加密密钥 (CMEK) 来保护对话式分析 API 资源,则必须向该 API 的服务账号授予使用 Cloud Key Management Service 密钥的权限。如需了解详情,请参阅 CMEK 文档中的准备工作。

向对话式分析 API 进行身份验证

本部分介绍了如何使用 HTTP 和 Python 方法获取必要的授权令牌,以便向对话式分析 API 进行身份验证。以下示例使用基于资源位置的区域端点逻辑。如需详细了解区域级端点,请参阅数据驻留。

HTTP curl

以下示例 curl 命令以 API 端点方法为目标,演示了如何使用 Google Cloud CLI 生成的身份令牌发送经过身份验证的请求:

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

按如下所示替换示例值:

  • ENDPOINT_URL:与您的位置对应的服务端点网址,例如,global 默认位置的 geminidataanalytics.googleapis.com,或 us 多区域的 geminidataanalytics.us.rep.googleapis.com。
  • PROJECT_ID:启用了所需 API 的 Google Cloud 项目的 ID。
  • LOCATION:资源的存储位置(例如 global 或 us-east4)。

  • METHOD:目标端点方法或资源路径(例如,dataAgents 用于创建智能体,或 dataAgents/AGENT_ID 用于获取特定智能体)。

使用 Python 进行 HTTP 通信

以下 Python 代码示例以 API 端点方法为例,演示了如何获取访问令牌并发送经过身份验证的 HTTP 请求。代码会根据指定的位置类型动态构建端点网址。

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

按如下所示替换示例值:

  • PROJECT_ID:启用了所需 API 的 Google Cloud 项目的 ID。
  • LOCATION:资源的存储位置(例如 global 或 us-east4)。

  • METHOD:目标端点方法或资源路径。例如:

    • 如需创建数据智能体,请使用 POST 方法并指定 dataAgents。
    • 如需列出现有数据智能体,请使用 GET 方法并指定 dataAgents。

Python SDK

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

from google.colab import auth
auth.authenticate_user()

使用 Conversational Analytics API 连接到 Looker

如需了解连接到 Looker 探索所需的角色和权限、授权选项以及示例代码,请参阅连接到 Looker。对于仅使用专用连接的实例,请参阅连接到使用专用连接的 Looker (Google Cloud Core) 实例。

使用 Conversational Analytics API 连接到 BigQuery

本部分介绍了如何配置对话式分析 API 以使用直接 HTTP 请求或 SDK 连接到 BigQuery。对话式分析 API 支持连接到 BigQuery 表,以及通过 BigQuery Graph 连接到图。

借助对话式分析 API,您可以连接的 BigQuery 表的数量没有硬性限制。不过,连接到大量表格可能会降低准确率,或者导致您超出 Gemini 的输入 token 限制。需要跨多个表进行复杂联接的查询也可能会导致回答不太准确。

连接到表

如需连接到一个或多个 BigQuery 表,请提供每个表的项目 ID、数据集 ID 和表 ID。

以下示例展示了如何使用 HTTP 请求或 Python SDK 连接到一个或多个 BigQuery 表。

使用 Python 进行 HTTP 通信

以下示例代码定义了与多个 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"
        },
      ]
    }
}

按如下所示替换示例值:

  • PROJECT_ID、PROJECT_ID_2、PROJECT_ID_3:包含您要连接到的 BigQuery 数据集和表的 Google Cloud 项目的 ID。如需连接到公共数据集,请指定 bigquery-public-data。
  • DATASET_ID、DATASET_ID_2、DATASET_ID_3:BigQuery 数据集的 ID(对于 Lakehouse 运行时目录表,则为 catalog.namespace)。
  • TABLE_ID、TABLE_ID_2、TABLE_ID_3:BigQuery 表的 ID(或 Lakehouse 运行时目录表的表名称)。

Python SDK

您可以使用 Colaboratory 中的 auth SDK,通过您的 Google 账号凭证进行身份验证,并授权 Colab 客户端使用您的凭证访问 BigQuery。

以下 Python 代码示例定义了与多个 BigQuery 表的连接,并演示了如何在 Colaboratory 中使用 Google 账号凭证进行身份验证,以便为请求授权。

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]

按如下所示替换示例值:

  • PROJECT_ID、PROJECT_ID_2、PROJECT_ID_3:包含您要连接到的 BigQuery 数据集和表的 Google Cloud 项目的 ID。如需连接到公共数据集,请指定 bigquery-public-data。
  • DATASET_ID、DATASET_ID_2、DATASET_ID_3:BigQuery 数据集的 ID(对于 Lakehouse 运行时目录表,则为 catalog.namespace)。例如 san_francisco。
  • TABLE_ID、TABLE_ID_2、TABLE_ID_3:BigQuery 表的 ID(或 Lakehouse 运行时目录表的表名称)。例如 street_trees。

连接到 BigQuery Graph

以下示例展示了如何使用 HTTP 请求或 Python SDK 通过 BigQuery Graph 连接到一个或多个图。

如需了解 BigQuery 版本要求和图查询限制,请参阅连接到 BigQuery Graph。

使用 Python 进行 HTTP 通信

以下示例代码定义了与 BigQuery 图的连接:

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

按如下所示替换示例值:

  • GRAPH_PROJECT_ID:包含 BigQuery 图的 Google Cloud 项目的 ID。
  • GRAPH_DATASET_ID:包含图的 BigQuery 数据集的 ID。
  • GRAPH_ID:BigQuery 图的 ID。

Python SDK

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

以下 Python 代码示例定义了与 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]

按如下所示替换示例值:

  • GRAPH_PROJECT_ID:包含 BigQuery 图的 Google Cloud 项目的 ID。
  • GRAPH_DATASET_ID:包含图的 BigQuery 数据集的 ID。
  • GRAPH_ID:BigQuery 图的 ID。

使用 Conversational Analytics API 连接到数据洞察

如需使用 Conversational Analytics API 连接到数据洞察,您必须先启用数据洞察 API。本部分介绍了如何通过直接 HTTP 请求或 SDK 配置对话式分析 API 以连接到数据洞察。

如需将对话式分析 API 与数据洞察 Pro 搭配使用,您的 Pro 订阅必须位于 VPC-SC 边界之外。

启用 Data Studio API

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

向数据洞察进行身份验证

如需使用对话式分析 API 连接到数据洞察,您必须确保经过身份验证的用户或服务账号有权访问数据洞察数据源,然后提供数据源 ID。

使用 Python 进行 HTTP 通信

启用 Data Studio API 后,您可以通过使用 Python 发出 HTTP curl 请求来连接到数据洞察。以下示例代码演示了如何在 HTTP 请求的正文中指定数据洞察数据源详细信息。

您可以通过发出直接 HTTP 请求来连接到数据洞察。以下代码块中演示了一个 HTTP 调用示例。

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

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

Python SDK

启用 Data Studio API 后,您可以使用 SDK 连接到数据洞察。以下 Python 代码示例演示了如何指定数据洞察数据源详细信息。


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]

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

使用 Conversational Analytics API 连接到数据库

如需使用对话式分析 API 连接到数据库,您必须拥有数据库实例所需的 IAM 权限。(可选)如果您将上下文集(预览版)与数据库数据源搭配使用,则如需创建、上传或管理上下文集,您还必须启用 Knowledge Catalog API,并授予对项目的 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情,请参阅上下文集权限。

连接到 AlloyDB for PostgreSQL

用户或服务账号必须具有 alloydb.databaseUser 角色。如需了解详情,请参阅 AlloyDB IAM 数据库身份验证。

使用 Python 进行 HTTP 通信

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

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

按如下所示替换示例值:

  • your_table_id:以英文逗号分隔的表 ID 列表。如果未设置,系统会考虑数据库中的所有表。
  • your_context_set_id(可选):要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 AlloyDB 文档。

Python SDK

以下 Python 代码示例演示了如何使用 Python SDK 定义 AlloyDB 数据源详细信息。

# 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

按如下所示替换示例值:

  • your_table_id_1:AlloyDB 实例中第一个表的 ID。
  • your_table_id_2:AlloyDB 实例中第二个表的 ID。
  • your_context_set_id:要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 AlloyDB 文档。

连接到 GoogleSQL for Spanner

用户或服务账号必须具有 spanner.databaseReader 角色。如需了解详情,请参阅应用 IAM 角色。

使用 Python 进行 HTTP 通信

以下示例代码演示了如何在 HTTP 请求的正文中指定 GoogleSQL for Spanner 数据源详细信息。

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

按如下所示替换示例值:

  • your_table_id_1:GoogleSQL for Spanner 实例中第一个表的 ID。
  • your_table_id_2:GoogleSQL for Spanner 实例中第二个表的 ID。
  • your_context_set_id:要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 Spanner 文档。

Python SDK

以下 Python 代码示例演示了如何使用 Python SDK 定义 GoogleSQL for Spanner 数据源详细信息。

# 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

按如下所示替换示例值:

  • your_table_id_1:GoogleSQL for Spanner 实例中第一个表的 ID。
  • your_table_id_2:GoogleSQL for Spanner 实例中第二个表的 ID。
  • your_context_set_id:要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 Spanner 文档。

连接到 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL

以下部分提供了有关连接到 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 的说明。用户或服务账号必须具有 cloudsql.studioUser 和 cloudsql.instanceUser 角色。如需了解详情,请参阅使用 IAM 数据库身份验证管理 Cloud SQL for MySQL 用户和使用 IAM 数据库身份验证管理 Cloud SQL for PostgreSQL 用户。

使用 Python 进行 HTTP 通信

以下示例代码演示了如何在 HTTP 请求的正文中指定 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 数据源详细信息。

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\"
        # }
    }
}

按如下所示替换示例值:

  • your_table_id_1:Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 实例中第一个表的 ID。
  • your_table_id_2:Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 实例中第二个表的 ID。
  • your_context_set_id:要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 的文档。

Python SDK

以下 Python 代码示例演示了如何使用 Python SDK 定义 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 数据源详细信息。

# 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

按如下所示替换示例值:

  • your_table_id_1:Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 实例中第一个表的 ID。
  • your_table_id_2:Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 实例中第二个表的 ID。
  • your_context_set_id:要检索的上下文集的完整 ID。如需详细了解如何查找上下文集 ID,请参阅 Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 的文档。