開發人員可以透過 geminidataanalytics.googleapis.com 或區域端點存取 Conversational Analytics API，建構採用人工智慧 (AI) 技術的對話介面或資料代理。這項 API 會使用自然語言，回答有關 BigQuery、Looker、數據分析和資料庫資料來源 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL，v1beta 預先發布版) 中結構化資料的問題。除了多輪對話，您也可以使用 QueryData 方法執行單輪查詢。
透過 Conversational Analytics API，您可以為資料代理提供業務資訊和資料 (背景資訊)，並授予 SQL、Python 和視覺化程式庫等工具的存取權。這些代理回覆會呈現給使用者，並可由用戶端應用程式記錄，打造流暢且可稽核的資料對話體驗。
瞭解 Gemini for Google Cloud 如何使用您的資料。
開始使用 Conversational Analytics API
如要開始使用 Conversational Analytics API，請參閱下列說明文件，瞭解可用的整合方法和核心概念：
- 架構和重要概念：瞭解資料代理如何處理要求、代理建立者和使用者的工作流程、對話模式，以及必要的 Identity and Access Management (IAM) 角色。
- 資料代理的整合模式：比較架構方法，判斷最適合應用程式的連線方式。
- 狀態管理：瞭解有狀態和無狀態對話模式、API 如何管理對話記錄，以及 ADK 工作階段狀態範圍。
- 安全性、隱私權、風險和法規遵循：瞭解 Conversational Analytics API 的安全性和法規遵循選項。
- Conversational Analytics API 位置：提供區域或多區域 API 端點的總覽，讓您控管代理資源、設定和資料的地理位置。
如要開始建構資料代理，請完成設定和必要條件說明文件中的步驟。如需逐步操作說明、範例應用程式、SDK 和其他開發人員工具，請參閱「Conversational Analytics API 教學課程、示範和工具」。
設定和必要條件
使用 API 或範例前，請先完成下列步驟：
- 啟用 Conversational Analytics API：說明啟用 Conversational Analytics API 的必要條件。
- 使用 IAM 控管存取權：說明如何使用 Identity and Access Management 共用及管理資料代理存取權。
- 驗證並連線至資料來源：提供操作說明，協助您驗證 API，並設定與 BigQuery、Lakehouse、Looker、數據分析和資料庫資料來源 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 的連線。
- 連線至 BigQuery：說明必要角色，以及如何將資料代理連結至 BigQuery 資料表和圖表。
- 連線至 Looker：說明如何將資料代理連結至 Looker 探索，並驗證 Looker 執行個體。
- 客戶自行管理的加密金鑰 (CMEK)：說明如何在 Cloud Key Management Service 使用自己的加密金鑰，保護資料代理和對話。
- 組織政策限制：說明如何使用預先定義的組織政策限制，在組織、資料夾或專案層級控管資源。
建構資料代理並與其互動
完成上述步驟後，請按照下列步驟，使用 Conversational Analytics API 建構資料代理並與其互動：
- 使用 HTTP 建構資料代理：提供已完成樣本，說明如何使用 Python 直接傳送 HTTP 要求，建構資料代理並與其互動。
- 使用 Python SDK 建構資料代理：提供已完成樣本，說明如何使用 Python SDK 建構資料代理並與其互動。
- 使用 A2A 自動化調度管理資料代理：瞭解如何探索代理能力、委派數據分析查詢，以及在多代理系統中串流 SQL 查詢和圖表視覺化。
- 使用編寫的背景資訊引導代理行為：瞭解如何提供編寫的背景資訊，引導代理行為並提高回覆準確度。您也可以查看 BigQuery 資料來源和 Looker 資料來源的編寫情境範例。
將 Conversational Analytics API 代理回覆轉為圖表：提供範例，說明如何使用 Python SDK 和 Vega-Altair 程式庫，處理 API 回應中的圖表規格，並轉為圖表。
最佳做法
請參閱下列指南，瞭解使用 Conversational Analytics API 的最佳做法：
- 管理代理的 BigQuery 費用：瞭解如何設定專案層級、使用者層級和查詢層級的支出上限，監控及管理 Conversational Analytics API 代理的 BigQuery 費用。
- 提出有效問題：瞭解如何為代理設計有效問題，充分發揮 Conversational Analytics API 的效益。
- 資料保留與刪除：瞭解 Conversational Analytics API 資料代理和對話的資料保留與刪除。
- 配額與限制：瞭解 Conversational Analytics API 的配額與限制。
- 排解 Conversational Analytics API 錯誤：排解常見的 Conversational Analytics API 錯誤。
- 已知限制：詳細說明 Conversational Analytics API 的已知限制，包括查詢、資料、圖表和問題的限制。
- 為 Looker 資料來源轉譯代理回覆：瞭解使用 Looker 資料來源時，在使用者介面轉譯 Conversational Analytics API 回應的最佳做法。
API 參考資料和用戶端程式庫
- Gemini Data Analytics REST 參考資料：提供 API 版本、方法、端點和類型定義的詳細說明。
- SDK 和開發人員工具：列出特定語言的用戶端程式庫。
重要 API 作業
API 提供下列核心端點，用於管理資料代理和對話。下表中的 v1 端點支援 BigQuery、Looker 和數據分析資料來源。由於資料庫資料來源在 v1beta 中處於預先發布版，請指定資料庫來源的對應 /v1beta/ 路徑。
建構這些路徑 (或對應的 SDK 資源名稱) 時，請將萬用字元 (*) 替換為專案 ID、位置 ID (例如 global 或 us) 和資源 ID (例如代理 ID 或對話 ID) (如適用)。
| 作業 | HTTP 方法 | 端點 | 說明 |
|---|---|---|---|
| 建立虛擬服務專員 | POST |
/v1/projects/*/locations/*/dataAgents |
建立新的資料代理。 |
| 同步建立代理 | POST |
/v1/projects/*/locations/*/dataAgents:createSync |
同步建立新的資料代理。 |
| 取得代理 | GET |
/v1/projects/*/locations/*/dataAgents/* |
擷取特定資料代理程式的詳細資料。 |
| 取得 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:getIamPolicy |
取得指派給每位使用者的特定資料代理 Identity and Access Management 權限。具備資料代理擁有者角色的使用者，可以呼叫這個端點來查看資料代理的 Identity and Access Management 政策，然後再使用 setIAMpolicy 端點與其他使用者共用資料代理。 |
| 設定 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:setIamPolicy |
設定特定資料代理的 Identity and Access Management 政策。具備資料代理擁有者角色的使用者應呼叫這個端點，與其他使用者共用資料代理，這會有效更新這些使用者的 Identity and Access Management 權限。 |
| 更新代理 | PATCH |
/v1/projects/*/locations/*/dataAgents/* |
修改現有的資料代理。 |
| 同步更新代理 | PATCH |
/v1/projects/*/locations/*/dataAgents/*:updateSync |
同步修改現有資料代理。 |
| 列出代理程式 | GET |
/v1/projects/*/locations/*/dataAgents |
列出專案中可用的資料代理。 |
| 列出可存取的代理 | GET |
/v1/projects/*/locations/*/dataAgents:listaccessible |
列出專案中可存取的資料代理。如果叫用這個 API 的使用者具備代理的 get 權限，則視為可存取資料代理。您可以使用 creator_filter 欄位，管理這個方法傳回的代理：
|
| 刪除代理程式 | DELETE |
/v1/projects/*/locations/*/dataAgents/* |
移除資料代理。 |
| 同步刪除代理 | DELETE |
/v1/projects/*/locations/*/dataAgents/*:deleteSync |
同步移除資料代理。 |
| 建立對話 | POST |
/v1/projects/*/locations/*/conversations |
發起新的永久對話。 |
| 使用對話參考資料進行即時通訊 | POST |
/v1/projects/*/locations/*:chat |
傳送即時通訊訊息，參照現有對話和相關聯的代理結構定義，繼續進行有狀態的對話。如果是多輪對話， Google Cloud 會儲存及管理對話記錄。 |
| 使用資料代理參考資料進行對話 | POST |
/v1/projects/*/locations/*:chat |
傳送無狀態即時通訊訊息，並參照已儲存的資料代理做為背景資訊。如果是多輪對話，應用程式必須管理並提供每項要求的對話記錄。 |
| 使用內嵌內容進行對話 | POST |
/v1/projects/*/locations/*:chat |
直接在要求中提供所有情境資訊，傳送無狀態即時通訊訊息，不使用已儲存的資料代理。如果是多輪對話，應用程式必須管理並提供每項要求的對話記錄。 |
| 取得對話 | GET |
/v1/projects/*/locations/*/conversations/* |
擷取特定對話的詳細資料。 |
| 列出對話 | GET |
/v1/projects/*/locations/*/conversations |
列出特定專案中的對話。 |
| 列出對話中的訊息 | GET |
/v1/projects/*/locations/*/conversations/*/messages |
列出特定對話中的訊息。 |
| 刪除對話 | DELETE |
/v1/projects/*/locations/*/conversations/* |
刪除特定對話。您必須具備主題管理員 Identity and Access Management 角色，或至少具備 cloudaicompanion.topics.delete Identity and Access Management 權限，才能呼叫這個端點。 |
| 查詢資料 | POST |
/v1beta/projects/*/locations/*/conversations:queryData |
使用自然語言查詢 AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 資料庫。 |
| 取得代理資訊卡 (A2A) | GET |
/v1/a2a/projects/*/locations/*/agents/*/v1/card |
使用 A2A 通訊協定，擷取內建或自訂資料代理的功能、技能和支援的擴充功能。 |
| 傳送訊息 (A2A) | POST |
/v1/a2a/projects/*/locations/*/agents/*/v1/message:send |
使用 A2A 通訊協定，將訊息傳送至資料代理。 |
| 傳送串流訊息 (A2A) | POST |
/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream |
使用 A2A 通訊協定，將串流訊息傳送至資料代理，傳回即時推論進度和結構化構件 (例如 SQL 查詢和圖表視覺化)。 |
支援和意見回饋
如需協助或回報問題，請與客戶服務團隊聯絡。請按照「建立及管理客服案件」一文的指引，開啟客服案件。建立案件時，請遵循下列規範：
- 如需 Conversational Analytics API 搭配 BigQuery 的支援服務，請在「選取產品」清單中選取「BigQuery」，並在「功能」欄位中選取「AI 與機器學習::BigQuery 中的 Conversational Analytics API」。
- 如需 Looker 的 Conversational Analytics API 支援，請在「選取產品」清單中選取「Looker (原始)」，並在「功能」欄位中選取「Gemini in Looker::Conversational Analytics API」。
如果您對 Conversational Analytics API 有一般意見或疑問，請傳送電子郵件至 conversational-analytics-api-feedback@google.com。我們不保證會回覆電子郵件，但會閱讀電子郵件，並在規劃藍圖時參考這些意見。
您也可以提交功能要求，申請新的 Conversational Analytics API 功能。