本頁面說明如何向對話式數據分析 API 進行驗證。此外,也會說明如何使用直接 HTTP 要求或 SDK,設定 Looker、BigQuery、數據分析和資料庫 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 的資料連線。對話式數據分析 API 採用標準Google Cloud 驗證方式。
事前準備
您必須先完成必要條件,並為 Google Cloud 專案啟用必要的 API,才能向對話式數據分析 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: Google Cloud 專案的 ID,您已在該專案啟用必要的 API。
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: Google Cloud 專案的 ID,您已在該專案啟用必要的 API。
LOCATION:資源的儲存位置 (例如
global或us-east4)。METHOD::目標端點方法或資源路徑。例如:
- 如要建立資料代理,請使用
POST方法並指定dataAgents。 - 如要列出現有的資料代理,請使用
GET方法並指定dataAgents。
- 如要建立資料代理,請使用
Python SDK
下列 Python 程式碼範例示範如何驗證 Google 帳戶,以便在 Colaboratory 中存取對話式數據分析 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 連至圖表。
Conversational Analytics API 對可連結的 BigQuery 資料表數量沒有硬性限制。不過,如果連結大量資料表,可能會降低準確度,或導致超出 Gemini 的輸入權杖限制。如果查詢需要跨多個資料表進行複雜的彙整,也可能導致回覆準確度降低。
連結至資料表
如要連結至一或多個 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: Google Cloud 專案 ID,該專案包含您要連結的 BigQuery 資料集和資料表。如要連結公開資料集,請指定
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: Google Cloud 專案 ID,該專案包含您要連結的 BigQuery 資料集和資料表。如要連結公開資料集,請指定
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 連結至數據分析
如要透過對話式數據分析 API 連結至數據分析,您必須先啟用 Data Studio API。本節說明如何設定對話式數據分析 API,透過直接 HTTP 要求或 SDK 連線至數據分析。
如要搭配使用對話式數據分析 API 和數據分析 Pro,Pro 訂閱方案必須位於 VPC-SC 範圍外。
啟用 Data Studio API
如要啟用 Data Studio API,請按照「啟用 API」一節的說明操作。
向數據分析驗證
如要使用對話式數據分析 API 連結至數據分析,請務必確認已驗證的使用者或服務帳戶有權存取數據分析資料來源,然後提供資料來源 ID。
使用 Python 建立 HTTP
啟用 Data Studio API 後,您可以使用 Python 提出 HTTP curl 要求,連線至 Data Studio。下列程式碼範例示範如何在 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 連線至 Data Studio。下列 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 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (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 要求主體中,指定 Spanner 適用的 GoogleSQL 資料來源詳細資料。
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 說明文件。
連線至 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL
下列各節將說明如何連線至 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL。使用者或服務帳戶必須具備 cloudsql.studioUser 和 cloudsql.instanceUser 角色。詳情請參閱「使用 MySQL 適用的 Cloud SQL IAM 資料庫驗證機制管理使用者」和「使用 PostgreSQL 適用的 Cloud SQL IAM 資料庫驗證機制管理使用者」。
使用 Python 建立 HTTP
下列程式碼範例說明如何在 HTTP 要求主體中,指定 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 資料來源詳細資料。
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:MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 執行個體中,第一個資料表的 ID。
- your_table_id_2:MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 執行個體中,第二個資料表的 ID。
- your_context_set_id:要擷取的完整情境集 ID。如要進一步瞭解如何找出情境集 ID,請參閱 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 說明文件。
Python SDK
下列 Python 程式碼範例示範如何使用 Python SDK,定義 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 資料來源詳細資料。
# 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:MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 執行個體中,第一個資料表的 ID。
- your_table_id_2:MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 執行個體中,第二個資料表的 ID。
- your_context_set_id:要擷取的完整情境集 ID。如要進一步瞭解如何找出情境集 ID,請參閱 MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 說明文件。