Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

客戶自行管理的加密金鑰 (CMEK)

Gemini 資料分析預設會加密靜態客戶內容。Gemini 資料分析會為您處理加密作業，您不必採取其他動作。這個選項稱為「Google 預設加密機制」。

如要控管加密金鑰，您可以在 Cloud KMS 中使用客戶自行管理的加密金鑰 (CMEK)，並搭配整合 CMEK 的服務，包括 Gemini 資料分析。使用 Cloud KMS 金鑰，即可控管金鑰的保護等級、位置、輪替時間表、使用權限和存取權，以及加密範圍。使用 Cloud KMS 還能查看稽核記錄及控管金鑰生命週期。您可以在 Cloud KMS 中控管及管理用於保護資料的對稱金鑰加密金鑰 (KEK)，而非由 Google 擁有及管理。

使用 CMEK 設定資源後，存取 Gemini 資料分析資源的體驗與使用 Google 預設加密機制類似。如要進一步瞭解加密選項，請參閱「客戶自行管理的加密金鑰 (CMEK)」。

本頁面說明如何使用客戶自行管理的加密金鑰 (CMEK)，保護 Conversational Analytics API 使用的資料。Conversational Analytics API 是 Gemini 資料分析服務 (geminidataanalytics.googleapis.com) 中的產品。

Conversational Analytics API 資源的 CMEK

為 Conversational Analytics API 資源設定 CMEK 後，指定的 Cloud KMS 金鑰會加密靜態機密資料。您可以分別為 DataAgent 和 Conversation 資源設定 CMEK。

Conversational Analytics API 的 CMEK 僅適用於區域和多區域位置，不適用於 global 位置。如要瞭解各資料來源支援的位置，請參閱「支援的資料位置」。

CMEK 保護的內容

Conversational Analytics API 的 CMEK 會保護下列靜態資料：

對於 DataAgent 資源，data_analytics_agent 欄位中的所有客戶核心內容都會受到保護。這類內容包括 staging_context、published_context 和 last_published_context 欄位，以及 system_instruction 和 example_queries 欄位。
Conversation 資源的所有訊息和狀態歷來資料都會受到保護。

下列資料不會以客戶的 CMEK 金鑰加密，而是由 Google 預設加密機制保護：

對於 DataAgent 資源，Google 預設加密機制會保護中繼資料欄位，例如 name、display_name、description、labels、create_time、update_time、delete_time、purge_time 和 kms_key。
如果是 Conversation 資源，Google 預設加密機制會保護中繼資料欄位，例如 name、agents、labels、create_time、last_used_time 和 kms_key。

限制

Conversational Analytics API 的 CMEK 有下列限制：

建立資源時，必須設定 CMEK。無法新增或變更現有資源。
不支援 CMEK 組織政策。
Cloud KMS 金鑰和 Conversational Analytics API 資源必須位於相同位置。
不支援「global」區域。
在每個專案和區域中，所有 Conversation 資源只能使用一個 CMEK。

事前準備

您必須先完成下列步驟，才能在 Conversational Analytics API 使用 CMEK：

在 Google Cloud 控制台或 Google Cloud CLI 中啟用必要的 API。
控制台
在 Google Cloud 控制台中，為 Google Cloud 專案啟用下列 API。

啟用 Gemini 資料分析 API

啟用 Gemini for Google Cloud API

啟用 Cloud Key Management Service API

提示： 啟用 API 後，您可能需要重新整理 Google Cloud 控制台頁面，確認 API 已啟用。
gcloud
使用 Google Cloud CLI 執行下列 gcloud services enable 指令，分別啟用 Gemini 資料分析 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。
在 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 加密者/解密者 (roles/cloudkms.cryptoKeyEncrypterDecrypter) 角色授予您在上一步建立的兩個服務代理，讓 Gemini Data Analytics 服務能使用 Cloud KMS 金鑰，加密及解密 Conversational Analytics 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 資源。

只有在建立 DataAgent 或 Conversation 資源時，才能啟用 CMEK。

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 金鑰名稱。

疑難排解

本節說明將 CMEK 與 Conversational Analytics API 搭配使用時，常見的問題和重要考量。

重要狀態變更

如果保護 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 加密要求配額。舉例來說，如要讀取 DataAgent 資源或存取受 CMEK 保護的 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 驗證及連線至資料來源。
進一步瞭解 Cloud KMS。

客戶自行管理的加密金鑰 (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` 資源