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

客戶自行管理的加密金鑰 (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 使用的資料，以及 BigQuery 和 Looker 資料來源。對話式數據分析 API 是 Gemini Data Analytics 服務 (geminidataanalytics.googleapis.com) 內的一項產品。

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

為 Conversational Analytics API 資源設定 CMEK 時，系統會使用指定的 Cloud KMS 金鑰加密靜態敏感資料。您可以分別為 DataAgent 和 Conversation 資源設定 CMEK。

對話式數據分析 API 的 CMEK 適用於 us-east4 區域，以及 us 和 eu 多區域。系統不支援「global」位置。如要進一步瞭解區域端點和資料位置，請參閱「資料落地」。

如要規定在專案或資料夾中建立的所有資源都必須使用 CMEK，請參閱「使用組織政策強制執行 CMEK 用法」。

CMEK 保護的內容

對話式數據分析 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 建立資源，並限制哪些 Cloud KMS 金鑰可用於 CMEK 保護。舉例來說，您可以使用 constraints/gcp.restrictNonCmekServices 和 constraints/gcp.restrictCmekCryptoKeyProjects 限制，確保整個機構的資料保護機制一致。

詳情請參閱「組織政策限制」。

限制

對話式數據分析 API 的 CMEK 有下列限制：

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

事前準備

如要在 Conversational Analytics 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。
在與 Conversational Analytics API 資源相同的位置，建立 Cloud KMS 金鑰環和金鑰。詳情請參閱「建立金鑰」一文。
如果 Google 代管的服務代理程式 (又稱每項產品和專案的服務帳戶 (P4SA)) 尚未建立，請建立這些帳戶。您必須允許這些服務代理存取 Cloud KMS 金鑰，才能使用 CMEK 保護 Conversational Analytics 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 金鑰，加密及解密 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 金鑰，藉此使用 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 配額和對話式數據分析 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 配額」。

後續步驟

瞭解如何啟用對話式數據分析 API。
瞭解資料落地設定。
瞭解如何透過 Conversational Analytics API 驗證及連結資料來源。
進一步瞭解 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` 資源