Mengonfigurasi kunci yang dikelola pelanggan untuk data terenkripsi Pencarian Azure AI

Anda dapat buat brankas kunci menggunakan portal Azure, Azure CLI, atau Azure PowerShell.

1. Buka brankas kunci Anda di portal Azure.

2. PilihKunci> di sebelah kiri, lalu pilih Hasilkan/Impor.

3. Di panel Buat kunci , dari daftar Opsi, pilih Buat untuk membuat kunci baru.

4. Masukkan Nama untuk kunci Anda, dan terima default untuk properti kunci lainnya.

5. Secara opsional, atur kebijakan rotasi kunci untuk mengaktifkan rotasi otomatis.

6. Pilih Buat untuk memulai penyebaran.

7. Setelah kunci dibuat, dapatkan pengidentifikasi kuncinya. Pilih kunci, pilih versi saat ini, lalu salin pengidentifikasi kunci. Ini terdiri dari nilai kunci Uri, nama kunci, dan versi kunci. Anda memerlukan pengidentifikasi untuk menentukan indeks terenkripsi di Pencarian Azure AI. Ingat bahwa operasi yang diperlukan adalah Bungkus, Buka Bungkus, Enkripsi, dan Dekripsi.

   

Anda dapat membuat dan mengaktifkan HSM Terkelola di portal Azure, Azure CLI, atau Azure PowerShell.

Untuk menghasilkan atau mengimpor kunci, gunakan Azure CLI.

Aktifkan identitas terkelola yang ditetapkan sistem untuk layanan pencarian Anda. Ini adalah operasi dua klik: aktifkan dan simpan.

Anda dapat menggunakan portal Azure atau REST API Manajemen Pencarian untuk membuat identitas terkelola yang ditetapkan pengguna dan menetapkan identitas ke layanan pencarian Anda. Untuk informasi selengkapnya, lihat Membuat identitas terkelola yang ditetapkan pengguna.

Ikuti instruksi ini jika Anda tidak dapat menggunakan penetapan peran untuk akses layanan pencarian ke kunci enkripsi.

1. Di portal Azure, temukan sumber daya Microsoft Entra untuk langganan Anda.

2. Di sebelah kiri, di bawah Kelola, pilih Pendaftaran aplikasi, lalu pilih Pendaftaran baru.

3. Masukkan nama untuk pendaftaran, seperti nama yang mirip dengan nama aplikasi pencarian. Pilih Daftar.

4. Setelah pendaftaran aplikasi dibuat, salin ID Aplikasi. Berikan string ini ke aplikasi Anda.

   Jika Anda menelusuri DotNetHowToEncryptionUsingCMK, tempelkan nilai ini ke file appsettings.json.

   

5. Selanjutnya, pilih Sertifikat & rahasia.

6. Pilih Rahasia klien baru. Masukkan nama tampilan untuk rahasia dan pilih Tambahkan.

7. Salin kunci rahasia aplikasi. Jika Anda mengikuti langkah-langkah menjalankan sampel, tempelkan nilai ini ke dalam file appsettings.json.

   

Saat membuat objek baru di portal Azure, Anda dapat menentukan kunci yang dikelola pelanggan yang telah ditentukan sebelumnya di brankas kunci. Portal Azure memungkinkan Anda mengaktifkan enkripsi dengan CMK untuk:

• Indeks
• Sumber data
• Pengindeks

Untuk menggunakan portal Azure, brankas kunci dan kunci harus ada, dan Anda harus menyelesaikan langkah-langkah sebelumnya untuk akses resmi ke kunci.

Di portal Azure, kumpulan keahlian didefinisikan dalam tampilan JSON. Gunakan JSON yang ditampilkan dalam contoh REST API untuk menyediakan kunci yang dikelola pelanggan pada set keterampilan.

1. Buka layanan pencarian Anda di portal Azure.

2. Di bawah Manajemen pencarian, pilih Indeks, Pengindeks, atau Sumber Data.

3. Tambahkan objek baru. Dalam definisi objek, pilih enkripsi yang dikelola Microsoft.

4. Pilih Kunci yang dikelola pelanggan dan pilih langganan, vault, kunci, dan versi Anda.

1. Panggil API pembuatan untuk menentukan properti encryptionKey :

   • Buat Indeks
   • Buat Peta Sinonim
   • Buat Pengindeks
   • Buat Sumber Data
   • Membuat Keterampilan

2. Sisipkan konstruksi encryptionKey ke dalam definisi objek. Properti ini adalah properti tingkat pertama, pada tingkat yang sama dengan nama dan deskripsi. Jika Anda menggunakan vault, kunci, dan versi yang sama, Anda dapat menempelkan konstruksi encryptionKey yang sama ke dalam setiap definisi objek.

   Jika pengidentifikasi kunci Anda adalah https://contoso-keyvault.vault.azure.net/keys/contoso-cmk/aaaaaaaa-0b0b-1c1c-2d2d-333333333333, maka URI adalah https://contoso-keyvault.vault.azure.net, nama kuncinya adalah contoso-cmk, dan versinya adalah 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>"
       }
     }
   }
   

   Contoh pertama menunjukkan encryptionKey untuk layanan pencarian yang terhubung menggunakan identitas terkelola:

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

   Contoh kedua mencakup accessCredentials, diperlukan jika Anda mendaftarkan aplikasi di 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. Verifikasi bahwa kunci enkripsi ada dengan mengeluarkan GET pada objek.

   • Indeks GET
   • Peta Sinonim (GET)
   • GET Indexer
   • GET Sumber Data
   • GET Skillset

4. Verifikasi objek beroperasi dengan melakukan tugas, seperti mengkueri indeks yang dienkripsi.

Setelah Anda membuat objek terenkripsi pada layanan pencarian, Anda dapat menggunakannya seperti yang Anda lakukan pada objek lain dari jenisnya. Enkripsi transparan untuk pengguna dan pengembang.

Tidak satu pun dari detail brankas kunci ini dianggap rahasia dan dapat dengan mudah diambil dengan menjelajah ke halaman Azure Key Vault yang relevan di portal Azure.

Konfigurasi CMK pada objek pencarian didukung dalam paket Azure SDK, termasuk Azure SDK untuk .NET, Azure SDK untuk Java, Azure SDK untuk JavaScript, dan Azure SDK untuk Python.

Contoh berikut menunjukkan representasi Python dari sebuah encryptionKey dalam definisi objek. Definisi yang sama berlaku untuk indeks, sumber data, set keterampilan, pengindeks, dan peta sinonim. Untuk mencoba contoh ini pada layanan penelusuran dan Key Vault Anda, unduh notebook dari azure-search-python-samples.

1. Instal beberapa paket.

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

2. Buat indeks yang memiliki kunci enkripsi.

   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=AZURE_SEARCH_SERVICE, credential=credential)
   fields = [
     SimpleField(name="Id", type=SearchFieldDataType.String, key=True),
     SearchableField(name="Description", type=SearchFieldDataType.String),
   ]
   
   encryption_key = SearchResourceEncryptionKey()
   encryption_key.vault_uri = "<PUT YOUR KEY VAULT URI HERE>"
   encryption_key.key_name = "<PUT YOUR KEY VAULT KEY NAME HERE>"
   encryption_key.key_version = "<PUT YOUR ALPHANUMERIC KEY VERSION HERE>"
   
   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. Dapatkan definisi indeks untuk memverifikasi konfigurasi kunci enkripsi ada.

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

4. Muat indeks dengan beberapa dokumen. Semua konten data dianggap sensitif dan dienkripsi pada disk dengan kunci yang dikelola oleh pelanggan.

   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 New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York 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)
   
       index_client = SearchClient(endpoint=AZURE_SEARCH_SERVICE, credential=credential)
   

5. Jalankan kueri untuk mengonfirmasi bahwa indeks beroperasi.

   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']}")
   

   Output dari kueri harus menghasilkan hasil yang mirip dengan contoh berikut.

   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 New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
   

   Karena konten terenkripsi didekripsi sebelum refresh atau kueri data, Anda tidak akan melihat bukti visual enkripsi. Untuk memverifikasi enkripsi berfungsi, periksa log sumber daya.

Saat ini, portal Azure tidak mendukung enkripsi tingkat layanan. Gunakan REST API secara langsung.

Untuk mengonfigurasi enkripsi dengan CMK di tingkat layanan pada layanan pencarian Anda, gunakan Layanan - Buat Atau Perbarui dengan PATCH untuk memperbarui layanan pencarian yang ada atau PUT untuk membuat yang baru. Versi API harus 2026-03-01-preview atau yang lebih baru untuk mendukung konfigurasi tingkat layanan.

Dalam contoh ini, pastikan untuk mengganti {{subscription-id}}, , {{resource-group}}{{search-service}}, dan {{token}} dengan ID langganan Anda, nama grup sumber daya, nama layanan pencarian, dan token akses. Definisi kunci menggunakan skema yang sama dengan CMK tingkat objek, dan ketiga opsi identitas didukung (identitas terkelola yang ditetapkan sistem, identitas terkelola yang ditetapkan pengguna, atau aplikasi terdaftar).

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2026-03-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

Lihat contoh berikut untuk mengetahui cara menyisipkan konstruksi serviceLevelEncryptionKey pada tingkat layanan untuk berbagai jenis identitas.

Contoh menggunakan identitas terkelola yang ditetapkan sistem:

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

Contoh menggunakan identitas yang dikelola pengguna:

{
  "encryptionWithCmk": {
    "serviceLevelEncryptionKey": {
      "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>"
      }
    }
  }
}

Contoh menggunakan ID aplikasi:

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

Konfigurasi CMK tingkat layanan didukung dalam paket Azure SDK yang menargetkan Search Management REST API versi 2026-03-01-preview atau yang lebih baru. Untuk mengonfirmasi dukungan, periksa changelog untuk paket Anda:

• .NET: Azure. ResourceManager.Search changelog
• Java: daftar perubahan azure-resourcemanager-search
• JavaScript: @azure/arm-search catatan perubahan
• Python: azure-mgmt-search catatan perubahan

Saat ini, portal Azure tidak mendukung enkripsi tingkat layanan. Gunakan REST API secara langsung.

Dalam data plane API versi 2026-05-01-preview dan yang lebih baru, gunakan panggilan objek GET untuk memeriksa encryptionKey.isServiceLevelKey.

Cuplikan kode di bawah ini adalah contohnya. Anda harus memperbaruinya dengan nilai khusus untuk kasus penggunaan Anda.

GET https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}

{
  "name": "hotels-cmk",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": true
  }
}

Ketika isServiceLevelKey bernilai true, objek mewarisi kunci level layanan dan tidak memiliki penggantian di level objek secara eksplisit.

Untuk memisahkan siklus hidup untuk objek tertentu, atur kunci tingkat objek eksplisit dan atur isServiceLevelKey ke false dalam PUT permintaan yang memperbarui objek.

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "keyVaultUri": "<YOUR-KEY-VAULT-URI>",
    "keyVaultKeyName": "<YOUR-ENCRYPTION-KEY-NAME>",
    "keyVaultKeyVersion": "<YOUR-ENCRYPTION-KEY-VERSION>",
    "isServiceLevelKey": false
  }
}

Dengan penggantian ini, siklus hidup kunci di tingkat objek tidak lagi bergantung pada setelan bawaan tingkat layanan. Anda dapat memutar kunci tingkat objek secara independen tanpa mengubah kunci tingkat layanan yang digunakan oleh objek lain.

Saat Anda mengaktifkan CMK tingkat layanan, permintaan pembuatan dapat tidak menyertakan encryptionKey, dan objek akan mewarisi kunci tingkat layanan tersebut secara default. Untuk mengalihkan objek yang ada dari kunci tingkat objek eksplisit ke pewarisan CMK tingkat layanan, atur isServiceLevelKey ke true dalam permintaan pembaruan.

Dalam API data plane versi 2026-05-01-preview dan yang lebih baru, validasi permintaan berlaku untuk objek encryptionKey. Jika Anda menyediakan encryptionKey, keyVaultUri dan keyVaultKeyName merupakan bidang string yang diperlukan, terlepas dari apakah isServiceLevelKey ada atau nilai apa yang dimilikinya. Validasi ini memeriksa keberadaan field, bukan keberadaan key. Nilai string placeholder memenuhi skema validasi ini, dan jika field yang wajib tidak ada, hasilnya adalah HTTP 400.

Ketika isServiceLevelKey adalah true, layanan menerapkan kunci tingkat layanan yang dikonfigurasi ke objek. Jika Anda memberikan keyVaultUri, keyVaultKeyName, atau keyVaultKeyVersion dalam permintaan yang sama, layanan mengabaikan nilai-nilai tersebut untuk pemilihan kunci dalam operasi tersebut.

Untuk kejelasan dan kepertahanan, berikan nilai kunci tingkat layanan saat ini dalam permintaan dan verifikasi kunci yang efektif dengan operasi GET pada objek.

PUT https://{{search-service}}.search.windows.net/indexes/{{index-name}}?api-version=2026-08-01-preview
api-key: {{admin-api-key}}
Content-Type: application/json

{
  "name": "regulated-index",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "searchable": false,
      "retrievable": true
    }
  ],
  "encryptionKey": {
    "isServiceLevelKey": true,
    "keyVaultUri": "<SERVICE-LEVEL-KEY-VAULT-URI>",
    "keyVaultKeyName": "<SERVICE-LEVEL-KEY-NAME>",
    "keyVaultKeyVersion": "<SERVICE-LEVEL-KEY-VERSION>"
  }
}

Setelah pembaruan ini, objek pencarian mewarisi kunci tingkat layanan. Verifikasi kunci yang efektif dengan mengeluarkan permintaan GET dan mengonfirmasi isServiceLevelKey adalah true.

Untuk mengatur kunci tingkat objek, berikan encryptionKey nilai kunci tingkat objek dan atur isServiceLevelKey ke false atau hilangkan isServiceLevelKey. Jika isServiceLevelKey adalah true, permintaan tidak mengalihkan objek ke kunci tingkat objek. Tidak menyertakan encryptionKey dalam permintaan pembaruan akan mempertahankan konfigurasi kunci enkripsi saat ini.

Konfigurasi CMK tingkat layanan didukung dalam paket Azure SDK yang menargetkan Search Management REST API versi 2026-03-01-preview atau yang lebih baru. Untuk mengonfirmasi dukungan, periksa changelog untuk paket Anda:

• .NET: Azure. ResourceManager.Search changelog
• Java: daftar perubahan azure-resourcemanager-search
• JavaScript: @azure/arm-search catatan perubahan
• Python: azure-mgmt-search catatan perubahan

Contoh ini berasal dari Kelola layanan Pencarian Azure AI Anda dengan REST API, dimodifikasi untuk menyertakan properti SearchEncryptionWithCmk.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/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": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default",
            "encryptionWithCmk": {
                "enforcement": "Enabled"
        }
      }
    }

PATCH https://management.azure.com/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"
      }
  }
}

Jalankan perintah berikut, ganti nilai yang valid untuk layanan pencarian dan grup sumber daya.

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

Respons harus mencakup pernyataan berikut:

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

"Tidak patuh" berarti layanan pencarian memiliki objek yang ada yang tidak dienkripsi CMK. Untuk mencapai kepatuhan, buat ulang setiap objek, tentukan kunci enkripsi.