根據預設,Agent Search 會加密靜態客戶內容。Agent Search 會為您處理加密作業,您不必採取其他動作。這項做法稱為「Google 預設加密機制」。
如要控管加密金鑰,可以在 Cloud KMS 中使用客戶自行管理的加密金鑰 (CMEK),並搭配整合 CMEK 的服務,包括 Agent Search。使用 Cloud KMS 金鑰,即可控管金鑰的保護等級、位置、輪替時間表、使用權限和存取權,以及加密範圍。 使用 Cloud KMS 還可追蹤金鑰使用情形、查看稽核記錄,以及控管金鑰生命週期。 您可以在 Cloud KMS 中控管及管理用於保護資料的對稱金鑰加密金鑰 (KEK),而非由 Google 擁有及管理。
使用 CMEK 設定資源後,存取 Agent Search 資源的體驗與使用 Google 預設加密機制類似。如要進一步瞭解加密選項,請參閱「客戶自行管理的加密金鑰 (CMEK)」。
註冊 CMEK 金鑰後,Agent Search 會定期呼叫 Cloud KMS,維護資料的邏輯隔離執行個體。即使 CMEK 設定並非預設,且沒有應用程式或資料連接器使用該設定,也會發生這種情況。用量取決於執行個體的設定和執行,而非資料量或存取資料的使用者人數。請參閱 Cloud Key Management Service 定價。
如要完全停止使用 Cloud KMS,您必須取消註冊 Cloud KMS 金鑰、停用金鑰,或撤銷金鑰權限。停用 Agent Search API 不會刪除 CmekConfig 或資料,系統會繼續向您收取 CMEK 使用費。
Agent Search 的 Cloud KMS 限制
Agent Search 的 CMEK (Cloud KMS) 金鑰有下列限制:
- 已套用至應用程式或資料連接器的金鑰無法變更,但金鑰版本可以輪替。
- Agent Search 的 CMEK 保護機制不會與 Cloud Asset Inventory 搜尋功能整合。
- 您必須使用美國或歐盟多區域應用程式和資料儲存庫 (而非全球)。如要進一步瞭解多區域和資料落地,包括使用非全域位置的相關限制,請參閱「位置」。
如需為專案註冊多組金鑰,請與 Google 帳戶團隊聯絡,要求提高 CMEK 設定配額,並說明需要多組金鑰的原因。
EKM 或 HSM 搭配 CMEK 時,有下列限制:
加密和解密呼叫的 EKM 和 HSM 配額應至少有 1,000 QPM 的餘裕。如要瞭解如何查看配額,請參閱「查看 Cloud KMS 配額」。
如果使用 EKM,金鑰在任何超過 30 秒的時間範圍內,都必須有 90% 以上的時間可供存取。如果在這段時間內無法連上金鑰,可能會對索引和搜尋時效性造成負面影響。
如果發生帳單問題、持續超出配額,或持續無法連線超過 12 小時,服務會自動關閉與 EKM 或 HSM 金鑰相關聯的 CmekConfig。
- 如果應用程式或資料連接器是在金鑰註冊到專案前建立,就無法受到金鑰保護。
- 您無法為受金鑰保護的應用程式和資料連接器調整搜尋模型。
- 如果應用程式有多個資料連接器,且其中一個資料連接器使用 CMEK 設定,則所有其他資料連接器也必須使用相同的 CMEK 設定。
如要使用代理搜尋功能,必須採用 Enterprise 版本。如要瞭解 Enterprise 版本,請參閱「關於進階功能」。
第一方連接器不符合 CMEK 規定,但 BigQuery 和 Cloud Storage 的「一次性匯入」和「定期」應用程式與資料連接器除外。
醫療照護搜尋應用程式和資料連接器,以及第三方連接器,皆符合 CMEK 規定。 如要進一步瞭解醫療照護應用程式和資料連接器,請參閱「建立醫療照護搜尋應用程式或資料連接器」。如要瞭解如何讓第三方連接器符合 CMEK 規定,請參閱「第三方連接器的單一區域金鑰簡介」。
金鑰不適用於下列 RAG API,因為這些 API 不會儲存靜態內容:check grounding、grounded generation 和 ranking。
- 您可以使用 Terraform 為 Agent Search 設定 CMEK。請參閱 google_discovery_engine_cmek_config。
第三方連接器的單一區域金鑰
如果您使用第三方連接器,並想使用自己的金鑰保護連結的資料,除了多區域金鑰外,還需要建立三個補充的單一區域金鑰。建立金鑰的指令請見下方程序:註冊 Cloud KMS 金鑰。
請為下列區域建立單一金鑰:
| 多區域 | 單一區域 | ||
|---|---|---|---|
eu |
europe-west1 |
europe-west4 |
europe-north1 |
us |
us-east1 |
us-central1 |
us-west1 |
事前準備
請確認您符合下列必要條件:
建立多區域對稱 Cloud KMS 金鑰。請參閱 Cloud KMS 說明文件中的「建立金鑰環」和「建立金鑰」。
將輪替週期設為「Never (Manual rotation)」(永不 (手動輪替))。
在「Location」(位置) 部分,選取「Multi-region」(多區域),然後從下拉式選單中選取「europe」(歐洲) 或「us」(美國)。
金鑰的 CryptoKey 加密者/解密者 IAM 角色 (
roles/cloudkms.cryptoKeyEncrypterDecrypter) 已授予 Discovery Engine 服務代理。服務代理帳戶的電子郵件地址格式如下:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com。如需為服務代理人新增角色的一般操作說明,請參閱「授予或撤銷單一角色」。金鑰的 CryptoKey 加密者/解密者 IAM 角色 (
roles/cloudkms.cryptoKeyEncrypterDecrypter) 已授予 Cloud Storage 服務代理。如果未授予這項角色,Discovery Engine 就無法建立匯入所需的受 CMEK 保護臨時 bucket 和目錄,因此受 CMEK 保護的應用程式和資料連結器將無法匯入資料。請先完成本頁的金鑰註冊操作說明,再建立要由金鑰管理的應用程式或資料連接器。
- 應用程式已啟用 Enterprise 版功能。請參閱「開啟或關閉 Enterprise 版」。
註冊 Cloud KMS 金鑰
如要使用 CMEK 加密資料,必須註冊多區域金鑰。如果資料需要單一區域金鑰 (例如使用第三方連接器時),您也可以選擇註冊單一區域金鑰。
事前準備
請確認您做到了以下各項:
- 該區域尚未受到金鑰保護。如果已透過 REST 指令為區域註冊金鑰,下列程序會失敗。如要判斷代理程式搜尋中是否有某個位置的使用中金鑰,請參閱「查看 Cloud KMS 金鑰」。
- 您具備 Discovery Engine 管理員 (
roles/discoveryengine.admin) 角色。
程序
REST
如要註冊 Agent Search 的專屬金鑰,請按照下列步驟操作:
使用要註冊的金鑰呼叫
UpdateCmekConfig方法。curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{"kmsKey":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"更改下列內容:
KMS_PROJECT_ID:金鑰所在專案的 ID。專案編號將無法使用。KMS_LOCATION:金鑰的多區域:us或europe。KEY_RING:金鑰所屬金鑰環的名稱。KEY_NAME:金鑰名稱。PROJECT_ID:專案 ID,用於存放應用程式或資料連接器。LOCATION:應用程式或資料連接器的多區域:us或eu。CMEK_CONFIG_ID:為 CmekConfig 資源設定專屬 ID,例如default_cmek_config。SET_DEFAULT:設為true,將金鑰設為預設金鑰,用於在多區域中建立的後續應用程式和資料連接器。
-
建立任何應用程式或資料連接器之前,請先確認金鑰是否可供使用。註冊金鑰必須準備就緒,才能保護資源。註冊金鑰通常需要幾分鐘。請參閱「確認 Cloud KMS 金鑰已可使用」。
如要追蹤註冊作業,您可以記錄方法傳回的
name值,並按照「取得長時間執行作業的詳細資料」一節的說明操作。金鑰準備就緒後,該多區域中的新應用程式和資料連接器就會受到金鑰保護。如需建立應用程式的一般資訊,請參閱「關於應用程式和資料儲存庫」。
-
建立應用程式。如需各種應用程式的建立操作說明連結,請參閱「關於應用程式和資料儲存庫」。
控制台
程序
如要註冊自己的 Agent Search 金鑰,請按照下列步驟操作:
前往 Google Cloud 控制台的「AI Applications」頁面。
按一下「設定」,然後選取「CMEK」分頁標籤。
按一下 us 或 eu 地點的「Add key」。
按一下「新增金鑰」。 按一下「選取 Cloud KMS 金鑰」下拉式選單,然後選取金鑰。
如果金鑰位於其他專案,請按一下「Switch project」(切換專案),然後點選專案名稱,輸入您建立的金鑰名稱,並選取該金鑰。
如果您知道金鑰的資源名稱,請按一下「手動輸入」,貼上金鑰資源名稱,然後按一下「儲存」。
依序點選「確定」和「儲存」。
-
建立任何應用程式或資料連接器之前,請先確認金鑰已可使用。已註冊的金鑰必須準備就緒,才能保護資源。請參閱「確認 Cloud KMS 金鑰已可使用」。
-
建立應用程式。如需建立各種應用程式的操作說明連結,請參閱「應用程式和資料儲存庫簡介」。
這會註冊金鑰,並建立名為 default_cmek_config 的 CmekResource。
擷取的資料可能需要幾小時才會顯示在搜尋結果中。
查看 Cloud KMS 金鑰
如要查看 Agent Search 的已註冊金鑰,請執行下列其中一項操作:
如果您有 CmekConfig 資源名稱,請呼叫
GetCmekConfig方法:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"更改下列內容:
LOCATION:應用程式或資料連接器的多區域:us或eu。PROJECT_ID:包含資料的專案 ID。CMEK_CONFIG_ID:CmekConfig 資源的 ID。如果您是使用控制台註冊金鑰,ID 為default_cmek_config。
以下是 curl 呼叫和回應的範例:
$ curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config"
{ "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config", "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key", "kmsKeyVersion": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/2", "state": "ACTIVE", "isDefault": true, "lastRotationTimestampMicros": "1788220800000000" }如果沒有 CmekConfig 資源名稱,請呼叫
ListCmekConfigs方法:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"更改下列內容:
LOCATION:應用程式或資料連接器的多區域:us或eu。PROJECT_ID:包含資料的專案 ID。
以下是 curl 呼叫和回應範例:
$ curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs"
{ "cmek_configs": [ { "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config", "kmsKey": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key", "kmsKeyVersion": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/2", "state": "ACTIVE", "isDefault": true, "lastRotationTimestampMicros": "1788220800000000" } ] }
確認 Cloud KMS 金鑰已可使用
註冊金鑰後,您必須先確認金鑰已可使用,才能保護任何資源:
查看已註冊的 Cloud KMS 金鑰。請參閱「查看 Cloud KMS 金鑰」。
查看指令輸出內容。如果輸出內容包含下列所有值,表示 CmekConfig 已可使用:
"state": "ACTIVE""isDefault": true
如果
"isDefault": true,系統會自動套用金鑰,保護新的應用程式和資料連接器。
您也可以使用 Google Cloud 控制台,確認是否已設定預設 CMEK 設定 (即
"isDefault": true):
前往 Google Cloud 控制台的「AI Applications」頁面。
按一下「設定」,然後選取「CMEK」分頁標籤。
確認位置的設定狀態顯示已註冊的金鑰。
取消註冊 Cloud KMS 金鑰
如要從 Agent Search 取消註冊金鑰,請按照下列步驟操作:
使用要取消註冊的 CmekConfig 資源名稱呼叫
DeleteCmekConfig方法。curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"更改下列內容:
LOCATION:應用程式或資料連接器的多區域:us或eu。PROJECT_ID:包含應用程式或資料連接器的專案 ID。CMEK_CONFIG_ID:CmekConfig 資源的 ID。如果您使用控制台註冊金鑰,ID 為default_cmek_config。
以下是 curl 呼叫和回應的範例:
$ curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/cmekConfigs/default_cmek_config" { "name": "projects/my-ai-app-project-123/locations/us/operations/delete-cmek-config-56789", "metadata": { "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.DeleteCmekConfigMetadata" } }選用:記錄方法傳回的
name值,並按照「取得長時間執行的作業的詳細資料」中的操作說明,查看作業何時完成。刪除 CmekConfig 是長時間執行的作業,最多可能需要幾天才能完成。這是因為在移除 CmekConfig 之前,基礎加密資源已完全取消佈建。
確認應用程式或資料連接器是否受金鑰保護
註冊金鑰後建立的應用程式和資料連接器,都會受到金鑰保護。如要確認特定應用程式或資料連接器是否受金鑰保護,請按照下列步驟操作:
使用 Google Cloud 控制台驗證
如要確認資料連接器是否受金鑰保護,請按照下列步驟操作:
前往 Google Cloud 控制台的「AI Applications」頁面。
按一下「資料儲存庫」,然後選取資料連接器。
確認「KMS key」(KMS 金鑰) 欄位顯示已註冊的金鑰。
使用 CLI / API 驗證
如要驗證資料儲存庫,請按照下列步驟操作:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"更改下列內容:
LOCATION:專案的多區域:us或eu。PROJECT_ID:應用程式或資料連接器所在專案的 ID。DATA_STORE_ID:與應用程式或資料連接器相關聯的資料儲存庫 ID。
curl 呼叫範例如下:
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H "x-goog-user-project: my-ai-app-project-123" "https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"
如要驗證應用程式,請按照下列步驟操作:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/ENGINE_ID"更改下列內容:
LOCATION:專案的多區域:us或eu。PROJECT_ID:應用程式所在專案的 ID。ENGINE_ID:應用程式 ID。
以下是 curl 呼叫範例:
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" -H "x-goog-user-project: my-ai-app-project-123" "https://us-discoveryengine.googleapis.com/v1/projects/my-ai-app-project-123/locations/us/collections/default_collection/engines/my-app"
查看指令的輸出內容:如果輸出內容中包含
cmekConfig欄位,且kmsKey欄位顯示您註冊的金鑰,則表示應用程式或資料連接器受到金鑰保護。資料儲存庫的回應範例如下:
{ "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1", "displayName": "my-data-store-1", "industryVertical": "GENERIC", "createTime": "2023-09-05T21:20:21.520552Z", "solutionTypes": [ "SOLUTION_TYPE_SEARCH" ], "defaultSchemaId": "default_schema", "cmekConfig": { "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config", "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key" } }應用程式的回應範例如下:
{ "name": "projects/969795412903/locations/us/collections/default_collection/engines/my-app", "displayName": "my-app", "dataStoreIds": [ "my-data-store-1" ], "solutionType": "SOLUTION_TYPE_SEARCH", "searchEngineConfig": { "searchTier": "SEARCH_TIER_STANDARD" }, "industryVertical": "GENERIC", "appType": "APP_TYPE_INTRANET", "cmekConfig": { "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/default_cmek_config", "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key" } }
受 Cloud KMS 金鑰保護的其他資料
除了應用程式和資料連接器中的資料,金鑰還可保護 Agent Search 持有的其他類型應用程式專屬核心資訊,例如後續追問搜尋期間產生的工作階段資料。如果應用程式和資料連接器受到 CMEK 保護,這類核心資訊也會受到 CMEK 保護。
雖然無法執行特定指令來驗證工作階段是否受到保護,但可以驗證應用程式是否受到保護。對應用程式執行「確認應用程式或資料連接器受金鑰保護」指令,即可在 cmekConfig 資源中查看金鑰。這樣您就會知道工作階段資料受到保護。
輪替 Cloud KMS 金鑰
您無法變更保護現有應用程式或資料連接器的金鑰,但可以將該金鑰輪替為新金鑰版本。當您建立已註冊金鑰的新版本 (主要版本) 時,Agent Search 會偵測到這項變更,並自動使用新金鑰版本重新加密資料。您不需要呼叫 Agent Search 方法來啟動輪替。
如需輪替金鑰的一般資訊,請參閱 Cloud KMS 指南中的「金鑰輪替」。
重要事項:請勿輪替與建議或任何需要數據分析的應用程式相關聯的應用程式或資料連接器金鑰,也不要輪替用於第三方連接器的單一區域金鑰。請參閱「Agent Search 中的 Cloud KMS 限制」。
如要輪替金鑰,請按照下列步驟操作:
建立新的金鑰版本,並設為主要版本。如需相關操作說明,請參閱 Cloud KMS 指南中的「輪替金鑰」。
請勿停用先前的金鑰版本。Agent Search 偵測到新的主要版本後,就會自動開始重新加密。
確認 Agent Search 偵測到新的金鑰版本。如要查看 CmekConfig,請參閱「查看 Cloud KMS 金鑰」。請查看輸出內容中的下列欄位:
kmsKeyVersion會顯示新的金鑰版本。state為ACTIVE。lastRotationTimestampMicros會顯示旋轉開始時間。
kmsKeyVersion顯示新的金鑰版本後,請將先前的金鑰版本保持啟用狀態至少 30 天。停用先前的金鑰版本,並確認一切運作如常。請參閱 Cloud KMS 指南中的「啟用及停用金鑰版本」。
確定停用先前的金鑰版本不會造成任何問題後,請將其刪除。請參閱 Cloud KMS 指南中的「刪除與還原金鑰版本」。
如果 Cloud KMS 金鑰遭到停用或撤銷
如果金鑰停用或金鑰權限遭到撤銷,應用程式或資料連接器會在 15 分鐘內停止擷取資料,並停止提供資料。您可以在 30 天內重新啟用金鑰,在 CMEK 設定過期和任何相關資料永久刪除前,繼續執行作業。 不過,重新啟用金鑰或還原權限需要很長時間。應用程式或資料連接器最多可能需要 24 小時,才能恢復提供資料。
因此,除非必要,否則請勿停用金鑰。在應用程式或資料連接器上停用及啟用金鑰,是相當耗時的操作。舉例來說,如果反覆切換金鑰的停用和啟用狀態,應用程式或資料連接器就需要很長時間才能進入受保護狀態。如果停用金鑰後立即重新啟用,可能會導致數天的停機時間,因為系統會先從應用程式或資料連接器停用金鑰,然後再重新啟用。
疑難排解:找不到 KMS 金鑰專案錯誤
症狀:嘗試使用 KMS 金鑰建立應用程式或資料連接器時,收到類似下列的錯誤訊息:
KMS key projects/[...] not found for location: [...] and project number: [...]
問題:這則錯誤訊息可能會誤導使用者。這不一定表示該鍵不存在。這可能表示 KMS 金鑰尚未註冊,無法在指定位置搭配 Agent Search 使用。
解決方案:如要解決這個問題,請按照「註冊 Cloud KMS 金鑰」中的步驟註冊金鑰。完成註冊後,您就能建立受該金鑰保護的應用程式或資料連接器。