このページでは、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 やラベルなどのサービスデータ、または転送中のデータには適用されません。
サポートされているデータのロケーション
会話分析 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 |
任意のリージョンまたはマルチリージョン | 保存時、使用中（管轄区域） |
asia-northeast1 |
東京 | リージョン | geminidataanalytics-asia-northeast1.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 に接続するデータ エージェントの場合、リージョン エンドポイントとマルチリージョン エンドポイントは、保存データのデータ所在地をサポートします。指定したエンドポイントの場所に関係なく、エージェントは任意の場所または場所の組み合わせのデータソースに接続できます。
| ロケーション | ロケーションの説明 | エンドポイントのタイプ | エンドポイント 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 リソースのデータ所在地を適用するには、リソースの作成時とアクセス時にリージョン エンドポイントを使用します。リージョン エンドポイントを呼び出す場合、リクエストパスまたはリクエストの親のロケーションは、呼び出すエンドポイントのロケーションと一致する必要があります。たとえば、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 でリージョン エンドポイントを使用するには、リージョン ベース 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"
次に、ステートフル チャットとステートレス チャットで質問するの例のように、API リクエストの URL を作成するときに 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: リソースを作成するリージョンまたはマルチリージョン。各データソースがサポートするロケーションについては、サポートされているデータのロケーションをご覧ください。
制限事項
リージョン エンドポイントを使用する場合は、次の点を考慮してください。
- Conversational Analytics API で顧客管理の暗号鍵（CMEK）を使用する場合、Cloud KMS 鍵はリージョン エンドポイントと同じロケーションに存在する必要があります。
次のステップ
- Conversational Analytics API でサポートされているロケーションのリストを確認する。
- 顧客管理の暗号鍵（CMEK）について学習する。
- 詳しくは、Google Cloud のロケーションをご覧ください。
- 一般的なデータ ロケーションのコミットメントについては、サービス固有の規約をご覧ください。