本指南說明主要差異,以及將應用程式從 Data QnA API (dataqna.googleapis.com) 遷移至對話式數據分析 API (geminidataanalytics.googleapis.com) 的步驟。
提供意見回饋
如果在遷移過程中發現任何不一致之處,請與 conversational-analytics-api-feedback@google.com 聯絡。
主要異動總覽
對話式數據分析 API 導入了 API 端點、API 使用的服務,以及 API 要求結構的變更。下表摘要列出 Data QnA API 和對話式數據分析 API 的主要差異,以及遷移所需的步驟。
| Data QnA API | Conversational Analytics API | 必要異動 |
|---|---|---|
dataqna.googleapis.com 個端點 |
geminidataanalytics.googleapis.com 個端點 |
更新要求中的 API 端點。 |
DataQuestionService 項服務 |
DataChatService 項服務 |
請更新要求中的服務名稱。 |
AskQuestionRequest 訊息中的 project 欄位 |
ChatRequest 訊息中的 parent 欄位 |
請將要求中的 project 欄位替換為 parent 欄位。詳情請參閱「將 project 替換為 parent 以進行要求轉送」。 |
datasource_ids 欄位 |
studio_references 欄位 |
在要求中,請將 datasource_ids 欄位替換為 studio_references 欄位。詳情請參閱「更新數據分析資料來源 ID 的參照」。 |
AgentConfig 個物件 |
ConversationOptions 個物件 |
在要求中,將 AgentConfig 物件替換為 ConversationOptions 物件。詳情請參閱「使用 ConversationOptions 啟用 Python 分析」。 |
AskQuestionRequest 訊息中的 context 欄位 |
ChatRequest 訊息中的 inline_context 欄位 |
在要求中,請將 context 欄位替換為 inline_context 欄位。詳情請參閱「將 context 替換為 inline_context」。 |
如需更新 API 要求結構的範例,請參閱「範例:更新 API 要求結構」。
將 project 替換為 parent,以便轉送要求
在 Data QnA API 中,您可以使用 AskQuestionRequest 訊息中的 project 欄位指定 Google Cloud 專案。在對話式數據分析 API 中,ChatRequest 訊息內的 project 欄位已淘汰。而是使用 parent 欄位同時指定專案和位置。
以下範例說明指定 parent 欄位的格式:
parent: "projects/BILLING_PROJECT/locations/global"
在上述範例中,請將 BILLING_PROJECT 替換為計費專案 ID。
更新數據分析資料來源 ID 的參照
在 Data QnA API 中,您可以使用 datasource_ids 欄位提供數據分析資料來源 ID 清單。在對話式數據分析 API 中,您可以使用 studio_references 欄位提供 StudioDatasourceReference 物件清單,每個物件都包含一個資料來源 ID。詳情請參閱「StudioDatasourceReference」。
啟用 Python 分析功能,並使用 ConversationOptions
AgentConfig 物件在 Data QnA API 中用於啟用工具,但 Conversational Analytics API 中的 DataChatService 服務不會使用該物件。如要在對話式數據分析 API 中啟用 Python 分析等功能,請在建立或設定資料代理時使用 ConversationOptions 物件。BigQuery 資料來源不支援 Python 分析。詳情請參閱「ConversationOptions」。
將 context 替換為 inline_context
在 Data QnA API 中,AskQuestionRequest 訊息包含 context 欄位,用於內嵌情境資訊。在對話式數據分析 API 中,ChatRequest 訊息的 context 欄位已重新命名為 inline_context。這項異動有助於區分內嵌背景資訊,以及可透過資料代理提供的其他類型背景資訊。
範例:更新 API 要求結構
以下範例說明如何從 Data QnA API 遷移至對話式數據分析 API,並根據新的 API 結構調整要求。這些範例涵蓋 BigQuery、Looker 和數據分析資料來源。
BigQuery 資料來源
本節提供範例,說明如何更新 BigQuery 資料來源的 API 要求。這個範例說明如何更新要求,要求提供長條圖,顯示機場總數前五多的州。
下列程式碼範例顯示 Data QnA API 的要求結構:
project: "projects/BILLING_PROJECT"
messages {
user_message {
text: "Create a bar graph showing the top 5 states by the total number of airports."
}
}
context {
datasource_references {
bq {
table_references {
project_id: "PROJECT_ID"
dataset_id: "DATASET_ID"
table_id: "TABLE_ID"
}
}
}
}
下列程式碼範例顯示 Conversational Analytics API 的更新要求結構:
messages {
user_message {
text: "Create a bar graph showing the top 5 states by the total number of airports."
}
}
parent: "projects/BILLING_PROJECT/locations/global"
inline_context {
datasource_references {
bq {
table_references {
project_id: "PROJECT_ID"
dataset_id: "DATASET_ID"
table_id: "TABLE_ID"
}
}
}
}
在上述範例中,您可以按照下列方式替換範例值:
BILLING_PROJECT:計費專案的 ID。PROJECT_ID:BigQuery 專案 ID。如要連結公開資料集,請指定bigquery-public-data。DATASET_ID:BigQuery 資料集的 ID。例如:faa。TABLE_ID:BigQuery 資料表的 ID。例如:us_airports。
Looker 資料來源
本節提供範例,說明如何更新 Looker 資料來源的 API 要求。這個範例說明如何更新要求,依訂單狀態取得訂單數量。
下列程式碼範例顯示 Data QnA API 的要求結構:
project: "projects/BILLING_PROJECT"
messages {
user_message {
text: "Show the count of orders by order status."
}
}
context {
datasource_references {
looker {
explore_references {
looker_instance_uri: "INSTANCE_URI"
lookml_model: "MODEL_NAME"
explore: "EXPLORE_NAME"
}
credentials {
oauth {
secret {
client_id: "CLIENT_ID"
client_secret: "CLIENT_SECRET"
}
}
}
}
}
}
下列程式碼範例顯示 Conversational Analytics API 的更新要求結構:
messages {
user_message {
text: "Show the count of orders by order status."
}
}
parent: "projects/BILLING_PROJECT/locations/global"
credentials {
oauth {
secret {
client_id: "CLIENT_ID"
client_secret: "CLIENT_SECRET"
}
}
}
inline_context {
datasource_references {
looker {
explore_references {
lookml_model: "MODEL_NAME"
explore: "EXPLORE_NAME"
looker_instance_uri: "INSTANCE_URI"
}
}
}
}
在上述範例中,您可以按照下列方式替換範例值:
BILLING_PROJECT:計費專案的 ID。CLIENT_ID:產生的 Looker API 金鑰用戶端 ID。CLIENT_SECRET:產生的 Looker API 金鑰用戶端密鑰。MODEL_NAME:LookML 模型的名稱。EXPLORE_NAME:LookML 探索的名稱。INSTANCE_URI:Looker 執行個體的 URI。
數據分析資料來源
本節提供範例,說明如何更新數據分析資料來源的 API 要求。這個範例說明如何更新要求,請 Gemini 製作長條圖,顯示前五大電信業者。
下列程式碼範例顯示 Data QnA API 的要求結構:
project: "projects/BILLING_PROJECT"
messages {
user_message {
text: "Create a bar graph showing the top 5 carriers."
}
}
context {
datasource_references {
studio {
datasource_ids: "DATA_SOURCE_ID"
}
}
}
下列程式碼範例顯示 Conversational Analytics API 的更新要求結構:
messages {
user_message {
text: "Create a bar graph showing the top 5 carriers."
}
}
parent: "projects/BILLING_PROJECT/locations/global"
inline_context {
datasource_references {
studio {
studio_references {
datasource_id: "DATA_SOURCE_ID"
}
}
}
}
在上述範例中,您可以按照下列方式替換範例值:
BILLING_PROJECT:計費專案的 ID。DATA_SOURCE_ID:數據分析資料來源的 ID。