データ所在地

このページでは、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 リソース（メッセージ コンテンツと状態履歴など）に適用されます。これらのコミットメントは、リソース識別子やラベルなどのサービスデータや、転送中のデータには適用されません。

サポートされているデータのロケーション

Conversational Analytics API は、グローバル、リージョン、マルチリージョンのロケーションをサポートしています。リージョン エンドポイントまたはマルチリージョン エンドポイントを使用すると、保存時にデータが保存される場所を制御できます。

次の表では、管轄区域の機械学習（ML）処理（使用中（管轄区域） と表示）は、データの ML 処理に関するコミットメントを指します。サービス固有の条件で定義されているように、Google は選択したリージョンまたはマルチリージョンでのみデータの ML 処理を行います。

以降のセクションでは、BigQuery データソースと Looker データソースを使用するエージェントと会話のデータ所在地サポートについて詳しく説明します。

BigQuery データ

BigQuery に接続するデータ エージェントの場合、リージョン エンドポイントとマルチリージョン エンドポイントは、保存中のデータのデータ所在地と、使用中のデータの管轄区域の ML 処理をサポートします。指定したエンドポイントのロケーションに関係なく、エージェントは任意のロケーションまたはロケーションの組み合わせで BigQuery データセットに接続できます。

場所 ロケーションの説明 エンドポイントのタイプ エンドポイント URL データセットの場所 データ所在地のサポート
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 に接続するデータ エージェントの場合、リージョン エンドポイントとマルチリージョン エンドポイントは、保存中のデータのデータ所在地をサポートします。指定したエンドポイントのロケーションに関係なく、エージェントは任意のロケーションまたはロケーションの組み合わせでデータソースに接続できます。

場所 ロケーションの説明 エンドポイントのタイプ エンドポイント URL データセットの場所 データ所在地のサポート
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 リソースのデータ所在地を適用するには、リソースの作成時とアクセス時にリージョン エンドポイントを使用します。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 でリージョン エンドポイントを使用するには、リージョン ベース URL を使用してリクエスト URL を作成します。まず、選択したリージョン エンドポイントを使用するように 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"

次に、base_url 変数を、ステートフル チャットとステートレス チャットで質問するの例に示すように、API リクエストの 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 を指定します。

制限事項

リージョン エンドポイントを使用する場合は、次の点に注意してください。

  • Conversational Analytics API で顧客管理の暗号鍵（CMEK）を使用する場合、Cloud KMS 鍵はリージョン エンドポイントと同じロケーションに存在する必要があります。

次のステップ