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 中控制和管理用于保护数据的对称密钥加密密钥 (KEK)，而不是由 Google 拥有和管理这些密钥。

使用 CMEK 设置资源后，访问 Gemini Data Analytics 资源的体验与使用 Google 默认加密功能类似。如需详细了解加密选项，请参阅客户管理的加密密钥 (CMEK)。

本页面介绍了如何使用客户管理的加密密钥 (CMEK) 来保护由 Conversational Analytics API 与 Looker 数据源一起使用的数据。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 资源，us-east4 区域支持 CMEK。
对于 Conversational Analytics API 资源，CMEK 仅适用于 Looker 数据源。
对于项目和区域内的所有 Conversation 资源，每个项目和区域只能使用一个 CMEK。

准备工作

在将 CMEK 与 Conversational Analytics API 搭配使用之前，请完成以下步骤：

在 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。
将您的项目添加到许可名单中。

您的 Google Cloud 项目必须添加到许可名单中，才能将 CMEK 与 Gemini 数据分析搭配使用。如需申请将您的项目添加到许可名单，请通过 GDA CMEK 许可名单表单提交您的项目 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 Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) 角色，以使 Gemini 数据分析服务能够使用您的 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 配额和 Conversational Analytics API

在 Conversational Analytics API 中使用 CMEK 时，您的项目可能会消耗 Cloud KMS 加密请求配额。例如，读取受 CMEK 保护的 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 对数据源进行身份验证并连接到数据源。
了解如何使用 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` 资源