数据驻留

本页面介绍了 Conversational Analytics API 如何支持数据驻留。数据驻留是指数据的实际位置，以及在特定地理区域内存储和处理数据的承诺，以满足法规或政策要求。如需控制数据的位置，您可以为 API 请求指定区域服务端点。

在本文档中，位置是指数据所在的 Google Cloud 单区域或多区域，“您的数据”的含义与《服务专用条款》的“数据位置”部分中的“客户数据”相同。

Conversational Analytics API 的数据驻留承诺因智能体是连接到 BigQuery 还是 Looker 而异。

数据驻留范围

Conversational Analytics API 可让您控制不同状态的客户数据的位置，从而帮助您满足数据驻留要求：

  • 当数据存储在永久性存储空间中，而不是处于主动处理或传输状态时，数据处于“静态”状态 。
  • 当数据位于内存中时，数据处于“使用中”状态 ，例如机器学习 (ML) 模型处理数据以生成响应时，或者服务执行查询时。对于 Conversational Analytics API，使用中的数据的数据驻留承诺特定于管辖范围内的机器学习处理，并且不为所有使用中的数据状态提供全面的驻留。
  • 当数据进入或退出 Google 网络边界时，数据处于“传输中”状态 。

Conversational Analytics API 的数据驻留承诺适用于 DataAgent 资源（包括客户配置、上下文、系统说明和示例查询）和 Conversation 资源（包括消息内容和状态历史记录）。这些承诺不适用于服务数据（例如资源标识符和标签）或传输中的数据。

支持的数据位置

Conversational Analytics API 支持全球、区域和多区域位置。使用区域或多区域端点时，您可以控制静态数据的存储位置。

在下表中，管辖范围内的机器学习 (ML) 处理（标识为使用中（管辖范围内） ）是指针对您的数据的机器学习处理承诺。如《服务专用条款》中所述，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 客户端时传递带有区域 api_endpoint 参数的 client_options，如配置设置和初始化客户端中的以下示例所示。

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。

限制

使用区域端点时，请考虑以下几点：

后续步骤