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 与 BigQuery 和 Looker 数据源搭配使用的数据。Conversational Analytics API 是 Gemini Data Analytics 服务 (geminidataanalytics.googleapis.com) 中的产品。

Conversational Analytics API 资源的 CMEK

为 Conversational Analytics API 资源配置 CMEK 后，指定的 Cloud KMS 密钥会加密静态敏感数据。您可以为 DataAgent 和 Conversation 资源单独配置 CMEK。

Conversational Analytics API 的 CMEK 在 us-east4 区域以及 us 和 eu 多区域中提供。不支持 global 位置。如需详细了解区域级端点和数据位置，请参阅数据驻留。

如需要求在您的项目或文件夹中创建的所有资源都使用 CMEK，请参阅使用组织政策强制执行 CMEK 使用。

受 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，并限制哪些 Cloud KMS 密钥可用于 CMEK 保护。例如，您可以使用 constraints/gcp.restrictNonCmekServices 和 constraints/gcp.restrictCmekCryptoKeyProjects 限制条件来确保组织内的数据保护一致。

如需了解详情，请参阅组织政策限制条件。

限制

Conversational Analytics API 的 CMEK 具有以下限制：

必须在创建资源时配置 CMEK。无法在现有资源上添加或更改 CMEK。
Cloud KMS 密钥和 Conversational Analytics API 资源必须位于同一位置。
不支持 global 区域。
对于项目和区域中的所有 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。
在与 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 密钥，以使用 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 组织政策。

客户管理的加密密钥 (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` 资源