顧客管理の暗号鍵（CMEK）

デフォルトでは、Gemini Data Analytics はお客様のコンテンツを保存時に暗号化します。Gemini Data Analytics では、ユーザーが追加で操作を行わなくても、暗号化が行われます。このオプションは、Google のデフォルトの暗号化と呼ばれます。

暗号鍵を管理する場合は、Gemini Data Analytics などの CMEK 統合サービスで Cloud KMS の顧客管理の暗号鍵（CMEK）を使用できます。Cloud KMS 鍵を使用すると、保護レベル、ロケーション、ローテーションスケジュール、使用とアクセスの権限、暗号境界を制御できます。Cloud KMS を使用すると、監査ログを表示し、鍵のライフサイクルを管理することもできます。データを保護する対称鍵暗号鍵（KEK）は Google が所有して管理するのではなく、ユーザーが Cloud KMS でこれらの鍵の制御と管理を行います。

CMEK を使用してリソースを設定した後は、Gemini Data Analytics リソースへのアクセスは、Google のデフォルトの暗号化を使用する場合と同様です。暗号化オプションの詳細については、顧客管理の暗号鍵（CMEK）をご覧ください。

このページでは、顧客管理の暗号鍵（CMEK）を使用して、Looker データソースで会話型分析 API が使用するデータを保護する方法について説明します。Conversational Analytics API は、Gemini データ分析サービス（geminidataanalytics.googleapis.com）内のプロダクトです。

会話型分析 API リソースの CMEK

会話型分析 API リソースに CMEK を構成すると、指定された Cloud KMS 鍵によってセンシティブデータが保存時に暗号化されます。DataAgent リソースと Conversation リソースに個別に CMEK を構成できます。

CMEK を構成できるのは、リソースの作成時のみです。CMEK を使用するには、DataAgent リソースまたは Conversation リソースを作成するときに kms_key フィールドを指定する必要があります。既存のリソースで Cloud KMS 鍵を追加または変更することはできません。

CMEK による保護対象

会話型分析 API の CMEK は、次の保存データを保護します。

DataAgent リソース: data_analytics_agent の staging_context、published_context、last_published_context フィールド内のすべての顧客コアコンテンツ。これには、system_instruction や example_queries などのフィールドが含まれます。
Conversation リソース: すべてのメッセージと状態の履歴。

次のデータは、顧客の CMEK 鍵で暗号化されません。このデータは、Google のデフォルトの暗号化によって保護されます。

DataAgent リソース: name、display_name、description、labels、create_time、update_time、delete_time、purge_time、kms_key などのメタデータフィールド
Conversation リソース: name、agents、labels、create_time、last_used_time、kms_key などのメタデータフィールド

制限事項

会話型分析 API の CMEK には次の制限があります。

CMEK は、リソースの作成時に構成する必要があります。既存のリソースに追加したり、変更したりすることはできません。
Cloud KMS 鍵と会話型分析 API リソースは同じロケーションに存在する必要があります。global リージョンはサポートされていません。
会話型分析 API リソースの場合、CMEK は us-east4 リージョンでサポートされています。
会話型分析 API リソースの場合、CMEK は Looker データソースでのみサポートされます。
プロジェクトとリージョン内のすべての Conversation リソースに使用できる CMEK は、プロジェクトとリージョンごとに 1 つだけです。

始める前に

会話型分析 API で CMEK を使用する前に、次の手順を完了します。

Google Cloud コンソールまたは Google Cloud CLI で必要な API を有効にします。
コンソール
Google Cloud コンソールで、 Google Cloud プロジェクトに対して次の API を有効にします。

Gemini Data Analytics API を有効にする

Gemini for Google Cloud API を有効にする

Cloud Key Management Service API を有効にする

ヒント: API を有効にする際は、有効になっていることを確認するために Google Cloud コンソールページの更新が必要になる場合があります。
gcloud
Google Cloud CLI で、次の gcloud services enable コマンドを実行して、Gemini Data Analytics API、Gemini for Google Cloud API、Cloud Key Management Service API をそれぞれ有効にします。
```
gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id
```
前のサンプル gcloud CLI コマンドで、project_id を Google Cloud プロジェクト ID に置き換えます。
プロジェクトを許可リストに追加します。

Gemini データ分析で CMEK を使用するには、 Google Cloud プロジェクトを許可リストに追加する必要があります。プロジェクトを許可リストに追加するようリクエストするには、GDA CMEK 許可リスト登録フォームからプロジェクト ID を送信します。プロジェクトを許可リストに追加するには、約 1 ～ 2 営業日かかります。
会話型分析 API リソースと同じロケーションに Cloud KMS キーリングと鍵を作成します。詳細については、鍵を作成するをご覧ください。
Google 管理のサービスエージェント（プロダクトごと、プロジェクトごとのサービスアカウント（P4SA）とも呼ばれます）が存在しない場合は作成します。これらのサービスエージェントは、CMEK を使用して会話型分析 API リソースの保護に関与するサービスが Cloud KMS 鍵にアクセスできるようにするために必要です。

次の gcloud コマンドを実行して、サービスエージェントを作成します。
```
gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
```
PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。
前の手順で作成した両方のサービスエージェントに Identity and Access Management（IAM）の Cloud KMS CryptoKey 暗号化/復号（roles/cloudkms.cryptoKeyEncrypterDecrypter）ロールを付与して、Gemini データ分析サービスが Cloud KMS 鍵を使用して会話型分析 API データの暗号化と復号を行えるようにします。

Gemini データ分析サービスエージェントに権限を付与します。
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Gemini for Google Cloud API サービスエージェントに権限を付与します。
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
前のコード例では、サンプル値を次のように置き換えます。
- KEY_NAME: Cloud KMS 鍵の名前。
- KEY_LOCATION: キーリングのリージョン（us-east4 など）。
- KEY_RING_NAME: キーリングの名前。
- PROJECT_NUMBER: API リソースを作成する Google Cloud プロジェクト番号。
- KMS_PROJECT_ID: 鍵が作成されたプロジェクト ID。これは、API リソースを作成するプロジェクトと同じにできます。

CMEK でリソースを保護する

このセクションでは、REST API を使用してリソースの作成時に kms_key フィールドで Cloud KMS 鍵を指定し、CMEK で新しい DataAgent または Conversation リソースを保護する方法について説明します。

CMEK は、DataAgent リソースまたは Conversation リソースの作成時にのみ有効にできます。

CMEK 鍵は、保護するリソースと同じリージョンに存在する必要があります。詳細については、制限事項をご覧ください。

CMEK で `DataAgent` リソースを保護する

CMEK で新しい DataAgent リソースを保護するには、データエージェントの作成時に kms_key フィールドで Cloud KMS 鍵を指定します。

Python SDK

次の例は、Python SDK で DataAgent リソースを作成するときに Cloud KMS 鍵を指定する方法を示しています。完全な create リクエストの例については、Python SDK を使用してデータエージェントを構築するをご覧ください。

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

前の例では、次のように値を置き換えます。

BILLING_PROJECT_ID: 課金プロジェクト ID。
KEY_RING_NAME: Cloud KMS キーリングの名前。
KEY_NAME: Cloud KMS 鍵の名前。
KMS_PROJECT_ID: 鍵が作成されたプロジェクト ID。空白のままにすると、billing_project が使用されます。
LOCATION: キーリングのリージョン。

HTTP

次の例は、HTTP と Python を使用して DataAgent リソースを作成するときに、リクエスト本文で Cloud KMS 鍵を指定する方法を示しています。完全な create リクエストの例については、HTTP と Python を使用してデータエージェントを構築するをご覧ください。

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

前の例では、次のように値を置き換えます。

KMS_PROJECT_ID: 鍵が作成されたプロジェクト ID。
LOCATION: キーリングのリージョン。
KEY_RING_NAME: Cloud KMS キーリングの名前。
KEY_NAME: Cloud KMS 鍵の名前。

CMEK で `Conversation` リソースを保護する

CMEK で新しい Conversation リソースを保護するには、会話を作成するときに kms_key フィールドで Cloud KMS 鍵を指定します。

Python SDK

次の例は、Python SDK で Conversation リソースを作成するときに Cloud KMS 鍵を指定する方法を示しています。完全な create リクエストの例については、Python SDK を使用してデータエージェントを構築するをご覧ください。

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

前の例では、次のように値を置き換えます。

BILLING_PROJECT_ID: 課金プロジェクト ID。
KEY_RING_NAME: Cloud KMS キーリングの名前。
KEY_NAME: Cloud KMS 鍵の名前。
KMS_PROJECT_ID: 鍵が作成されたプロジェクト ID。空白のままにすると、billing_project が使用されます。
LOCATION: キーリングのリージョン。

HTTP

次の例は、HTTP と Python を使用して Conversation リソースを作成するときに、リクエスト本文で Cloud KMS 鍵を指定する方法を示しています。完全な create リクエストの例については、HTTP と Python を使用してデータエージェントを構築するをご覧ください。

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

前の例では、次のように値を置き換えます。

KMS_PROJECT_ID: 鍵が作成されたプロジェクト ID。
LOCATION: キーリングのリージョン。
KEY_RING_NAME: Cloud KMS キーリングの名前。
KEY_NAME: Cloud KMS 鍵の名前。

トラブルシューティング

このセクションでは、会話型分析 API で CMEK を使用する際の一般的な問題と重要な考慮事項について説明します。

キーの状態の変更

会話型分析 API リソースを保護する Cloud KMS 鍵バージョンが使用できなくなると、その鍵で暗号化されたデータにアクセスできなくなります。鍵が使用できないときに、DataAgent リソースのコンテキストの読み取りや Conversation 履歴へのアクセスなどによって保護されたデータにアクセスしようとすると、リクエストは失敗します。返されるエラーは、鍵を使用できない理由によって異なります。

鍵バージョンが無効または破棄されている場合、通常、オペレーションは FAILED_PRECONDITION エラーで失敗します。
gcp-sa-geminidataanalytics または gcp-sa-cloudaicompanion サービスエージェントから cloudkms.cryptoKeyEncrypterDecrypter IAM ロールが取り消されると、通常、オペレーションは PERMISSION_DENIED または NOT_FOUND エラーで失敗します。

鍵が使用できない場合でも、DataAgent リソースや Conversation リソースの削除など、コンテンツの復号を必要としないオペレーションは実行できます。

暗号化されたデータへのアクセスを復元するには、始める前にで説明したように、鍵を再度有効にして、サービスエージェントに必要な IAM 権限があることを確認します。

Cloud KMS の割り当てと会話型分析 API

会話型分析 API で CMEK を使用すると、プロジェクトで Cloud KMS 暗号リクエストの割り当てが消費されることがあります。たとえば、CMEK で保護された DataAgent リソースの読み取りや Conversation 履歴へのアクセスには、Cloud KMS によるデータの復号が必要です。

CMEK 鍵を使用する暗号化と復号のオペレーションは、次のように Cloud KMS の割り当てに影響します。

Cloud KMS で生成されたソフトウェア CMEK 鍵の場合、Cloud KMS の割り当ては消費されません。
ハードウェア CMEK 鍵（Cloud HSM 鍵とも呼ばれる）の場合、暗号化と復号のオペレーションは、その鍵が含まれるプロジェクトの Cloud HSM の割り当てにカウントされます。
外部 CMEK 鍵（Cloud EKM 鍵とも呼ばれる）の場合、暗号化と復号のオペレーションは、その鍵が含まれるプロジェクトの Cloud EKM の割り当てにカウントされます。

詳細については、Cloud KMS の割り当てをご覧ください。

次のステップ

会話型分析 API を有効にする方法を確認する。
会話型分析 API を使用してデータソースの認証と接続を行う方法を確認する。
Python SDK を使用してデータエージェントを構築する方法を学習する。
HTTP と Python を使用してデータエージェントを構築する方法を学習する。
Cloud KMS の詳細を確認する。
CMEK の組織ポリシーについて学習する。

顧客管理の暗号鍵（CMEK） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

会話型分析 API リソースの CMEK

CMEK による保護対象

制限事項

始める前に

コンソール

gcloud

CMEK でリソースを保護する

CMEK で DataAgent リソースを保護する

Python SDK

HTTP

CMEK で Conversation リソースを保護する

Python SDK

HTTP

トラブルシューティング

キーの状態の変更

Cloud KMS の割り当てと会話型分析 API

次のステップ

顧客管理の暗号鍵（CMEK）

CMEK で `DataAgent` リソースを保護する

CMEK で `Conversation` リソースを保護する