資料落地

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

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

Conversational Analytics API 的資料落地承諾，會因代理連結至 BigQuery 或 Looker 而異。

資料落地範圍

Conversational Analytics API 可讓您控管不同狀態下的客戶資料位置，協助您符合資料落地要求：

  • 資料儲存在永久儲存空間，而非主動處理或傳輸時，即為靜態資料。
  • 資料在記憶體中時，即為使用中狀態，例如機器學習 (ML) 模型處理資料以生成回覆，或服務執行查詢時。Conversational Analytics API 的使用中資料落地承諾，僅適用於管轄區內的 ML 處理作業，並未涵蓋所有使用中的資料。
  • 資料進入或離開 Google 網路邊界時，即為傳輸中。

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

支援的資料位置

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

在下表中，管轄區機器學習 (ML) 處理 (標示為「使用中 (管轄區)」) 是指資料的 ML 處理承諾。根據《服務專屬條款》的定義，Google 只會在您選取的區域或多區域，對資料執行機器學習處理。

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

BigQuery 資料

對於連至 BigQuery 的資料代理，區域和多區域端點支援靜態資料的資料落地，以及使用中資料的管轄區 ML 處理。無論您指定的端點位置為何，代理都能連線至任何位置或位置組合中的 BigQuery 資料集：

位置 位置說明 端點類型 端點網址 資料集位置 資料落地支援
global 全球 全球 geminidataanalytics.googleapis.com 任何區域或多區域 不支援
eu 歐盟 多區域 geminidataanalytics.eu.rep.googleapis.com 任何區域或多區域 靜態、使用中 (管轄區)
us 美國 多區域 geminidataanalytics.us.rep.googleapis.com 任何區域或多區域 靜態、使用中 (管轄區)
northamerica-northeast1 蒙特婁 區域 geminidataanalytics-northamerica-northeast1.googleapis.com 任何區域或多區域 靜態、使用中 (司法管轄區)
northamerica-northeast2 多倫多 區域 geminidataanalytics-northamerica-northeast2.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 預留位置替換為資料來源支援的地區或多區域。詳情請參閱「支援的資料位置」。

以下範例說明如何為 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：要建立資源的區域或多區域。如要瞭解各資料來源支援的位置，請參閱「支援的資料位置」。

限制

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

後續步驟