在 Azure AI 搜索 中为数据加密配置客户管理的密钥

可以使用 Azure 门户、Azure CLI或 Azure PowerShell 创建密钥保管库。

1. 登录到 Azure 门户并打开密钥保管库概述页。

2. 在左侧选择“对象”“密钥”，然后选择“生成/导入”。>

3. 在“创建密钥”窗格的“选项”列表中，选择“生成”以创建新密钥。

4. 输入密钥的“名称”，并接受其他密钥属性的默认值。

5. 可以选择设置密钥轮换策略以启用自动轮换。

6. 选择“创建”以开始部署。

7. 创建密钥后，获取其密钥标识符。 选择密钥，选择当前版本，然后复制密钥标识符。 它由键值 URI、密钥名称和密钥版本组成。 你需要标识符来在Azure AI 搜索中定义加密索引。 回想一下，所需的作是 Wrap、 Unwrap、 Encrypt 和 Decrypt。

   

可以在 Azure 门户中创建和激活托管 HSM、Azure CLI 或 Azure PowerShell。

若要生成或导入密钥，请使用 Azure CLI。

为搜索服务启用系统分配的托管标识。 这是一项两次点击操作：点击启用并保存。

可以使用Azure门户或搜索管理 REST API 创建用户分配的托管标识并将标识分配给搜索服务。 有关详细信息，请参阅创建用户分配的托管标识。

如果您无法使用角色分配来为搜索服务访问加密密钥，请按照以下说明进行操作。

1. 在 Azure 门户中，找到与您订阅相关的 Microsoft Entra 资源。

2. 在左侧的 Manage 下，选择 应用注册，然后选择 New registration。

3. 为注册提供一个名称，该名称可以是与搜索应用程序名称类似的名称。 选择“注册”。

4. 创建应用注册后，复制应用程序 ID。 需要将此字符串提供给应用程序。

   如果要单步执行 DotNetHowToEncryptionUsingCMK，请将此值粘贴到 appsettings.json 文件中。

   

5. 接下来，选择 “证书和机密”。

6. 选择“新建客户端机密”。 为机密指定显示名称并选择“添加”。

7. 复制应用程序密钥。 如果要逐步执行此示例，请将以下值粘贴到 appsettings.json 文件中。

   

在 Azure 门户中创建新对象时，可以在密钥保管库中指定预定义的客户管理的密钥。 Azure门户允许为以下项启用 CMK 加密：

• 索引
• 数据源
• 索引器

使用 Azure 门户的要求是密钥保管库和密钥必须存在，并且你已完成先前的步骤，以便获得对密钥的授权访问。

在Azure门户中，技能集在 JSON 视图中定义。 使用 REST API 示例中提供的 JSON 为技能集配置一个客户管理密钥。

1. 登录到 Azure 门户并打开搜索服务页。

2. 在 “搜索管理”下，选择 “索引”、“ 索引器”或 “数据源”。

3. 添加新对象。 在对象定义中，选择Azure托管加密。

4. 选择 客户管理的密钥 ，然后选择订阅、保管库、密钥和版本。

<博览会>Azure 门户中的加密密钥页面的屏幕截图。

1. 调用创建 API 以指定 encryptionKey 属性：

   • 创建索引
   • 创建同义词映射
   • 创建索引器
   • 创建数据源
   • 创建技能组

2. 将 encryptionKey 构造插入到对象定义中。 此属性是一级属性，其级别与名称和说明相同。 如果使用的是相同的保管库、密钥和版本，则可以将相同的 encryptionKey 构造粘贴到每个对象定义中。

   如果密钥标识符为 https://contoso-keyvault.vault.azure.cn/keys/contoso-cmk/aaaaaaaa-0b0b-1c1c-2d2d-333333333333，则 URI 为 https://contoso-keyvault.vault.azure.cn，密钥名称为 contoso-cmk，版本为 aaaaaaaa-0b0b-1c1c-2d2d-333333333333。

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
       "identity" : { 
           "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
           "userAssignedIdentity" : "/subscriptions/<your-subscription-ID>/resourceGroups/<your-resource-group-name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<your-managed-identity-name>"
       }
     }
   }
   

   第一个示例展示了通过托管身份进行连接的搜索服务的加密密钥：

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>"
     }
   }
   

   第二个示例包括 accessCredentials，在Microsoft Entra ID中注册应用程序时是必需的：

   {
     "encryptionKey": {
       "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
       "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
       "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
       "accessCredentials": {
         "applicationId": "<YOUR-APPLICATION-ID>",
         "applicationSecret": "<YOUR-APPLICATION-SECRET>"
       }
     }
   }
   

3. 通过在对象上发出 GET 来验证加密密钥是否存在。

   • GET 索引
   • 执行GET Synonym Map命令
   • GET 索引器
   • GET 数据源
   • GET 技能集合

4. 通过执行任务（例如查询已加密的索引）来验证对象是否正常运行。

在搜索服务上创建加密对象后，可以像使用其类型的任何其他对象一样使用它。 加密对于用户和开发人员是透明的。

这些密钥保管库详细信息都不被视为机密，可以通过浏览到Azure门户中的相关Azure 密钥保管库页轻松检索这些密钥保管库详细信息。

此示例显示对象定义中encryptionKey的Python表示形式。 相同的定义适用于索引、数据源、技能组、索引器和同义词映射。 若要在搜索服务和密钥保管库上试用此示例，请从 azure-search-python-samples 下载笔记本。

1. 安装一些包。

   ! pip install python-dotenv
   ! pip install azure-core
   ! pip install azure-search-documents==11.5.1
   ! pip install azure-identity
   

2. 创建具有加密密钥的索引。

   from azure.search.documents.indexes import SearchIndexClient
   from azure.search.documents.indexes.models import (
   SimpleField,
   SearchFieldDataType,
   SearchableField,
   SearchIndex,
   SearchResourceEncryptionKey
   )
   from azure.identity import DefaultAzureCredential
   
   endpoint="<PUT YOUR AZURE SEARCH SERVICE ENDPOINT HERE>"
   credential = DefaultAzureCredential()
   
   index_name = "test-cmk-index"
   index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
   fields = [
   SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
   SearchableField(name="Description", type=SearchFieldDataType.String)
   ]
   
   scoring_profiles = []
   suggester = []
   encryption_key = SearchResourceEncryptionKey(
   key_name="<PUT YOUR KEY VAULT NAME HERE>",
   key_version="<PUT YOUR ALPHANUMERIC KEY VERSION HERE>",
   vault_uri
   )
   
   index = SearchIndex(name=index_name, fields=fields, encryption_key=encryption_key)
   result = index_client.create_or_update_index(index)
   print(f' {result.name} created')
   

3. 获取索引定义以验证加密密钥配置是否存在。

   index_name = "test-cmk-index-qs"
   index_client = SearchIndexClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)  
   
   result = index_client.get_index(index_name)  
   print(f"{result}")  
   

4. 用几个文档来加载索引。 所有字段内容将被视为敏感内容，并使用客户管理的密钥在磁盘上加密。

   from azure.search.documents import SearchClient
   
   # Create a documents payload
   documents = [
       {
       "@search.action": "upload",
       "Id": "1",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of Beijing. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make Beijing one of America's most attractive and cosmopolitan cities."
       },
       {
       "@search.action": "upload",
       "Id": "2",
       "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts."
       },
       {
       "@search.action": "upload",
       "Id": "3",
       "Description": "The hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services."
       },
       {
       "@search.action": "upload",
       "Id": "4",
       "Description": "The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace."
       }
   ]
   
   search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, index_name=index_name, credential=credential)
   try:
       result = search_client.upload_documents(documents=documents)
       print("Upload of new document succeeded: {}".format(result[0].succeeded))
   except Exception as ex:
       print (ex.message)
   
       index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
   

5. 运行查询以确认索引是否正常运行。

   from azure.search.documents import SearchClient
   
   query = "historic"  
   
   search_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential, index_name=index_name)
   
   results = search_client.search(  
       query_type='simple',
       search_text=query, 
       select=["Id", "Description"],
       include_total_count=True
       )
   
   for result in results:  
       print(f"Score: {result['@search.score']}")
       print(f"Id: {result['Id']}")
       print(f"Description: {result['Description']}")
   

   查询的输出应生成类似于以下示例的结果。

   Score: 0.6130029
   Id: 4
   Description: The hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.
   Score: 0.26286605
   Id: 1
   Description: The hotel is ideally located on the main commercial artery of the city in the heart of Beijing. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make Beijing one of America's most attractive and cosmopolitan cities.
   

   由于加密内容是在数据刷新或查询之前解密的，因此不会看到加密的可视证据。 要验证加密是否正常工作，请检查资源日志。

该示例改编自使用 REST API 管理 Azure AI 搜索服务，并包含 SearchEncryptionWithCmk 属性。

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "China North",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default",
            "encryptionWithCmk": {
                "enforcement": "Enabled"
        }
      }
    }

PATCH https://management.chinacloudapi.cn/subscriptions/<your-subscription-Id>/resourceGroups/<your-resource-group-name>/providers/Microsoft.Search/searchServices/<your-search-service-name>?api-version=2025-05-01

{
  "properties": {
      "encryptionWithCmk": {
          "enforcement": "Enabled"
      }
  }
}

运行以下命令，替换搜索服务和资源组的有效值。

az resource update --name SEARCH-SERVICE-PLACEHOLDER --resource-group RESOURCE-GROUP-PLACEHOLDER --resource-type searchServices --namespace Microsoft.Search --set properties.encryptionWithCmk.enforcement=Enabled

响应应包含以下语句：

"encryptionWithCmk": {
      "encryptionComplianceStatus": "NonCompliant",
      "enforcement": "Enabled"
    }
...

“不符合”意味着搜索服务具有未加密 CMK 的现有对象。 若要实现合规性，请重新创建每个对象，并指定加密密钥。