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

根據預設，Gemini Data Analytics 會加密靜態客戶內容。Gemini Data Analytics 會為您處理加密作業，您不必採取其他動作。這項做法稱為「Google 預設加密機制」。

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

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

本頁說明如何使用客戶自行管理的加密金鑰 (CMEK)，保護 Conversational Analytics API 搭配 Looker 資料來源使用的資料。對話式數據分析 API 是 Gemini Data Analytics 服務 (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 資源，us-east4 區域支援 CMEK。
對於對話式數據分析 API 資源，CMEK 僅支援 Looker 資料來源。
在專案和區域中，您只能為所有 Conversation 資源使用一個 CMEK。

事前準備

如要搭配對話式數據分析 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 控制台頁面，確認 API 已啟用。
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。將專案加入許可清單的作業大約需要一到兩個工作天才能完成。
在與對話式數據分析 API 資源相同的位置，建立 Cloud KMS 金鑰環和金鑰。詳情請參閱「建立金鑰」一文。
如果還沒有 Google 代管的服務代理 (也稱為每項產品和專案的服務帳戶，即 P4SA)，請建立這類帳戶。您必須允許這些服務代理存取 Cloud KMS 金鑰，才能使用客戶自行管理的加密金鑰保護對話式數據分析 API 資源。

執行下列 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」(Cloud KMS 加密編譯金鑰加密者/解密者) (roles/cloudkms.cryptoKeyEncrypterDecrypter) 角色授予您在上一個步驟中建立的兩個服務代理程式，讓 Gemini Data Analytics 服務能使用您的 Cloud KMS 金鑰，加密及解密對話式數據分析 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 金鑰，藉此以 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 金鑰的名稱。

疑難排解

本節將說明搭配 Conversational Analytics 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 配額」。

客戶自行管理的加密金鑰 (CMEK) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

對話式數據分析 API 資源的 CMEK

CMEK 保護的內容

限制

事前準備

控制台

gcloud

使用 CMEK 保護資源

使用 CMEK 保護 DataAgent 資源

Python SDK

HTTP

使用 CMEK 保護 Conversation 資源

Python SDK

HTTP

疑難排解

金鑰狀態變更

Cloud KMS 配額和對話式數據分析 API

後續步驟

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

使用 CMEK 保護 `DataAgent` 資源

使用 CMEK 保護 `Conversation` 資源