Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

顧客管理の暗号鍵（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 データソースで Conversational Analytics API で使用されるデータを保護する方法について説明します。Conversational Analytics API は、Gemini Data Analytics サービス（geminidataanalytics.googleapis.com）内のプロダクトです。

Conversational Analytics API リソースの CMEK

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

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

CMEK による保護対象

Conversational Analytics 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 などのメタデータフィールド

制限事項

Conversational Analytics API の CMEK には次の制限があります。

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

始める前に

Conversational Analytics API で CMEK を使用する前に、次の手順を完了してください。

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

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 Data Analytics で CMEK を使用するには、プロジェクトを許可リストに追加する必要があります。 Google Cloud プロジェクトを許可リストに追加するようリクエストするには、GDA CMEK 許可リスト登録フォームからプロジェクト ID を送信します。プロジェクトを許可リストに追加するには、1 ～ 2 営業日ほどかかります。
Conversational Analytics API リソースと同じロケーションに Cloud KMS キーリングと鍵を作成します。詳細については、鍵を作成するをご覧ください。
Google マネージドサービスエージェント（プロジェクトごとのサービスアカウント（P4SA）とも呼ばれます）が存在しない場合は作成します。これらのサービスエージェントは、CMEK で Conversational Analytics 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 Encrypter/Decrypter（roles/cloudkms.cryptoKeyEncrypterDecrypter）ロールを付与して、Gemini Data Analytics サービスが Cloud KMS 鍵を使用して Conversational Analytics API データの暗号化と復号を行えるようにします。

Gemini Data Analytics サービスエージェントに権限を付与します。
```
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 鍵を指定することで、新しい DataAgent リソースまたは Conversation リソースを CMEK で保護する方法について説明します。

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

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

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

新しい DataAgent リソースを CMEK で保護するには、データエージェントの作成時に 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` リソースを保護する

新しい Conversation リソースを CMEK で保護するには、会話の作成時に 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 鍵の名前。

トラブルシューティング

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

鍵の状態の変更

Conversational Analytics 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 の割り当てと Conversational Analytics API

Conversational Analytics 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 の割り当てをご覧ください。

次のステップ

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

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

Conversational Analytics API リソースの CMEK

CMEK による保護対象

制限事項

始める前に

コンソール

gcloud

CMEK でリソースを保護する

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

Python SDK

HTTP

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

Python SDK

HTTP

トラブルシューティング

鍵の状態の変更

Cloud KMS の割り当てと Conversational Analytics API

次のステップ

顧客管理の暗号鍵（CMEK）

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

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