資料落地

本頁說明 Conversational Analytics API 如何支援資料落地。資料落地是指資料的實體位置，以及在特定地理區域內儲存及處理資料的承諾，以符合法規或政策要求。如要控管資料位置，請為 API 要求指定地區服務端點。

本文中的「位置」是指資料所在的 Google Cloud 區域或多區域，「您的資料」與《服務專屬條款》「資料位置」一節中的「客戶資料」意義相同。

對話式數據分析 API 的資料落地承諾會因代理程式連結至 BigQuery 或 Looker 而異。

資料落地範圍

對話式數據分析 API 提供多種控制選項，可讓您控管不同狀態的顧客資料位置，進而符合資料落地規定：

  • 資料「靜態」是指儲存在永久儲存空間中，而非主動處理或傳輸。
  • 資料使用中是指資料位於記憶體中，例如機器學習 (ML) 模型處理資料以生成回覆，或是服務執行查詢時。對話式數據分析 API 的資料落地承諾適用於管轄區的機器學習處理作業，不適用於所有使用中資料狀態的全面落地。
  • 資料進入或離開 Google 網路邊界時，即為傳輸中。

對話式 Analytics API 的資料落地承諾適用於 DataAgent 資源 (包括客戶設定、背景資訊、系統指令和查詢範例) 和 Conversation 資源 (包括訊息內容和狀態記錄)。這些承諾不適用於服務資料 (例如資源 ID 和標籤) 或傳輸中的資料。

支援的資料位置

Conversational Analytics API 支援全球、單一區域和多區域位置。使用區域或多區域端點時，您可以控管靜態資料的儲存位置。

下表中的「使用中 (管轄區)」是指我們對您資料的機器學習處理承諾。如《服務專屬條款》所述，Google 只會在您選取的區域或多區域，對您的資料執行機器學習處理作業。

以下各節將詳細說明，使用 BigQuery 和 Looker 資料來源的代理程式和對話，如何支援資料落地。

BigQuery 資料

如果資料代理程式連線至 BigQuery，地區和多地區端點會支援靜態資料的資料駐留，以及使用中資料的管轄區機器學習處理。無論您指定哪個端點位置，代理程式都能連線至任何位置或位置組合的 BigQuery 資料集：

位置 地點說明 端點類型 端點網址 資料集位置 資料落地支援
global 全球 全球 geminidataanalytics.googleapis.com 任何單一區域或多區域 不支援
eu 歐盟 多區域 geminidataanalytics.eu.rep.googleapis.com 任何單一區域或多區域 休息狀態、使用中 (管轄範圍)
us 美國 多區域 geminidataanalytics.us.rep.googleapis.com 任何單一區域或多區域 休息狀態、使用中 (管轄範圍)
us-east4 北維吉尼亞州 區域 geminidataanalytics-us-east4.googleapis.com 任何單一區域或多區域 休息狀態、使用中 (管轄範圍)

Looker 資料

如果資料代理程式連線至 Looker，區域和多區域端點會支援靜態資料的資料落地權。無論您指定哪個端點位置，代理程式都可以連線至任何位置或位置組合的資料來源：

位置 地點說明 端點類型 端點網址 資料集位置 資料落地支援
global 全球 全球 geminidataanalytics.googleapis.com 任何單一區域或多區域 不支援
eu 歐盟 多區域 geminidataanalytics.eu.rep.googleapis.com 任何單一區域或多區域 休息狀態
us 美國 多區域 geminidataanalytics.us.rep.googleapis.com 任何單一區域或多區域 休息狀態
us-east4 北維吉尼亞州 區域 geminidataanalytics-us-east4.googleapis.com 任何單一區域或多區域 休息狀態

如需可用的區域和多區域端點完整清單，請參閱「Conversational Analytics API 地點」。

透過地區端點強制執行資料落地權

如要對 DataAgent 和 Conversation 資源強制執行資料落地權，請在建立及存取這些資源時使用區域端點。呼叫區域端點時，要求路徑或要求父項中的位置必須與您呼叫的端點位置相符。舉例來說，如果您呼叫 geminidataanalytics.us.rep.googleapis.com 端點，就必須在要求路徑或要求父項 (例如 /locations/us 或 projects/PROJECT_ID/locations/us) 中指定 us。

視位置類型而定，Conversational Analytics API 的服務端點會採用下列格式：

  • 全球：geminidataanalytics.googleapis.com
  • 多區域：geminidataanalytics.LOCATION.rep.googleapis.com
  • 區域：geminidataanalytics-LOCATION.googleapis.com

將 LOCATION 預留位置替換為支援的單一或多個區域，例如 eu、us 或 us-east4。

下列範例說明如何為 HTTP 和 Python SDK 要求設定區域端點：

HTTP

如要透過 HTTP 使用區域端點，請使用區域基準網址建構要求網址。首先，請設定 base_url，使用您選擇的區域端點，如下列「設定初始設定和驗證」範例所示：

project_id = "PROJECT_ID"
location = "LOCATION"

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

然後，在建構 API 要求網址時使用 base_url 變數，例如在「使用具狀態和無狀態的即時通訊功能提問」一文中的這個範例：

# Example API request URL construction using base_url:
chat_url = f"{base_url}/v1beta/projects/{project_id}/locations/{location}:chat"

Python SDK

如要搭配 Python SDK 使用區域端點，請在初始化 API 用戶端時，將 client_options 連同區域 api_endpoint 參數一併傳遞，如「設定設定並初始化用戶端」一文中的下列範例所示。

from google.cloud import geminidataanalytics
from google.api_core import client_options

project_id = "PROJECT_ID"
location = "LOCATION"

# Set client options based on location.
if not location or location == "global":
  endpoint = "geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  endpoint = f"geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  endpoint = f"geminidataanalytics.{location}.rep.googleapis.com"
opts = client_options.ClientOptions(api_endpoint=endpoint)

# Use client options when initializing API clients.
data_agent_client = geminidataanalytics.DataAgentServiceClient(client_options=opts)
data_chat_client = geminidataanalytics.DataChatServiceClient(client_options=opts)

# Use clients to make API requests. For example:
# response = data_chat_client.chat(request=request)

請依下列方式替換範例值：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：要建立資源的區域或多區域。如要使用其中一個區域端點，請指定 eu、us 或 us-east4。

限制

使用區域端點時，請注意下列事項：

後續步驟