Menyambungkan layanan pencarian ke sumber daya Azure lainnya menggunakan identitas terkelola

Anda dapat mengonfigurasi azure AI layanan Pencarian untuk menyambungkan ke sumber daya Azure lainnya menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna dan penetapan peran Azure. Identitas terkelola dan penetapan peran menghilangkan kebutuhan untuk meneruskan rahasia dan kredensial dalam string koneksi atau kode.

Prasyarat

• Layanan pencarian di tingkat Dasar atau di atasnya.

• Sumber daya Azure yang menerima permintaan masuk dari login Microsoft Entra yang memiliki penetapan peran yang valid.

Skenario yang didukung

Pencarian Azure AI dapat menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna pada koneksi keluar ke sumber daya Azure. Identitas terkelola sistem ditunjukkan ketika string koneksi adalah ID sumber daya unik dari layanan atau aplikasi sadar ID Microsoft Entra. Identitas terkelola yang ditetapkan pengguna ditentukan melalui properti "identitas".

Layanan pencarian menggunakan Azure Storage sebagai sumber data pengindeks dan sebagai sink data untuk sesi debug, penembolokan pengayaan, dan penyimpanan pengetahuan. Untuk fitur pencarian yang menulis kembali ke penyimpanan, identitas terkelola memerlukan penetapan peran kontributor seperti yang dijelaskan di bagian "Tetapkan peran" .

Skenario	Identitas terkelola sistem	Identitas terkelola yang ditetapkan pengguna (pratinjau)
Koneksi pengindeks ke sumberdata Azure yang didukung 1,3	Ya	Ya
Azure Key Vault untuk kunci yang dikelola pelanggan	Ya	Ya
Sesi debug (dihosting di Azure Storage)1	Ya	Tidak
Cache pengayaan (dihosting di Azure Storage)1,2	Ya	Ya
Penyimpanan Pengetahuan (dihosting di Azure Storage)1	Ya	Ya
Keterampilan kustom (dihosting di Azure Functions atau setara)	Ya	Ya
Keterampilan penyematan Azure OpenAI	Ya	Ya
Vektorizer Azure OpenAI	Ya	Ya

¹ Untuk konektivitas antara pencarian dan penyimpanan, konfigurasi keamanan jaringan Anda memberlakukan batasan jenis identitas terkelola yang dapat Anda gunakan. Hanya identitas terkelola sistem yang dapat digunakan untuk koneksi wilayah yang sama ke penyimpanan melalui pengecualian layanan tepercaya atau aturan instans sumber daya. Lihat Akses ke akun penyimpanan yang dilindungi jaringan untuk detailnya.

² Satu metode untuk menentukan cache pengayaan ada di wizard Impor data. Saat ini, wizard tidak menerima identitas terkelola string koneksi untuk cache pengayaan. Namun, setelah wizard selesai, Anda dapat memperbarui string koneksi dalam definisi JSON pengindeks untuk menentukan sistem atau identitas terkelola yang ditetapkan pengguna, lalu menjalankan ulang pengindeks.

³ Perhatikan bahwa menonaktifkan kunci di akun penyimpanan Azure saat ini tidak didukung untuk Azure Table yang digunakan sebagai sumber data. Meskipun identitas terkelola digunakan untuk tidak menyediakan kunci penyimpanan secara eksplisit, layanan pencarian AI masih menggunakan kunci untuk implementasi ini.

Membuat identitas terkelola sistem

Saat identitas terkelola yang ditetapkan sistem diaktifkan, Azure membuat identitas untuk layanan pencarian Anda yang dapat digunakan untuk melakukan autentikasi ke layanan Azure lainnya dalam penyewa dan langganan yang sama. Anda kemudian dapat menggunakan identitas ini dalam penetapan kontrol akses berbasis peran Azure (Azure RBAC) yang memungkinkan akses ke data selama pengindeksan.

Identitas terkelola yang ditetapkan sistem bersifat unik untuk layanan pencarian Anda dan terikat ke layanan selama masa pakainya.

Portal Azure

1. Masuk ke portal Azure dan temukan layanan pencarian Anda.

2. Di Pengaturan, pilih Identitas.

3. Pada tab Sistem yang ditetapkan, di bawah Status, pilih Aktif.

4. Pilih Simpan.

   

   Setelah menyimpan, Anda akan melihat pengidentifikasi objek yang telah ditetapkan ke layanan pencarian Anda.

   

REST API

Lihat Membuat atau Memperbarui Layanan (Management REST API).

Anda dapat menggunakan REST API Manajemen alih-alih portal untuk menetapkan identitas terkelola yang ditetapkan pengguna.

1. Merumuskan permintaan untuk Membuat atau Memperbarui layanan pencarian.

   PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
   {
     "location": "[region]",
     "sku": {
       "name": "[sku]"
     },
     "properties": {
       "replicaCount": [replica count],
       "partitionCount": [partition count],
       "hostingMode": "default"
     },
     "identity": {
       "type": "SystemAssigned"
     }
   } 
   

2. Konfirmasi dan pengidentifikasi objek untuk identitas terkelola sistem dikembalikan dalam respons.

Azure PowerShell

Lihat Membuat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure PowerShell.

Azure CLI

Lihat Membuat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure CLI).

Membuat identitas terkelola yang ditetapkan pengguna (pratinjau)

Identitas terkelola yang ditetapkan pengguna adalah sumber daya di Azure. Ini berguna jika Anda membutuhkan lebih banyak granularitas dalam penetapan peran karena Anda dapat membuat identitas terpisah untuk aplikasi dan skenario yang berbeda.

Penting

Fitur ini berada di pratinjau publik dalam ketentuan penggunaan tambahan. Identitas terkelola yang ditetapkan pengguna saat ini tidak didukung untuk koneksi ke akun penyimpanan yang dilindungi jaringan. Permintaan pencarian saat ini memerlukan alamat IP publik.

Portal Azure

1. Masuk ke portal Microsoft Azure.

2. Pilih + Buat sumber daya.

3. Di bilah pencarian "Cari layanan dan marketplace", cari "Identitas Terkelola Yang Ditetapkan Pengguna" lalu pilih Buat.

   

4. Pilih langganan, grup sumber daya, dan wilayah. Beri nama yang deskriptif pada identitas tersebut.

5. Pilih Buat dan tunggu hingga sumber daya selesai disebarkan.

   Dalam beberapa langkah berikutnya, Anda akan menetapkan identitas terkelola yang ditetapkan pengguna ke layanan pencarian Anda.

6. Di halaman layanan pencarian Anda, di bawah Pengaturan, pilih Identitas.

7. Pada tab Ditetapkan pengguna, pilih Tambahkan.

8. Pilih langganan lalu pilih sumber daya terkelola yang ditetapkan pengguna yang Anda buat di langkah sebelumnya.

REST API

Anda dapat menggunakan REST API Manajemen alih-alih portal untuk menetapkan identitas terkelola yang ditetapkan pengguna. Pastikan untuk menggunakan versi pratinjau 2021-04-01 untuk tugas ini.

1. Merumuskan permintaan untuk Membuat atau Memperbarui layanan pencarian.

   PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
   {
     "location": "[region]",
     "sku": {
       "name": "[sku]"
     },
     "properties": {
       "replicaCount": [replica count],
       "partitionCount": [partition count],
       "hostingMode": "default"
     },
     "identity": {
       "type": "UserAssigned",
       "userAssignedIdentities": {
         "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
       }
     }
   } 
   

2. Atur properti "identitas" untuk menentukan identitas terkelola yang sepenuhnya memenuhi syarat:

   • "type" adalah jenis identitas. Nilai yang valid adalah "SystemAssigned", "UserAssigned", atau "SystemAssigned, UserAssigned" jika Anda ingin menggunakan keduanya. Nilai "Tidak Ada" akan menghapus identitas yang ditetapkan sebelumnya dari layanan pencarian.

   • "userAssignedIdentities" menyertakan detail identitas terkelola yang ditetapkan pengguna. Identitas ini harus sudah ada sebelum Anda dapat menentukannya dalam permintaan Buat atau Perbarui Layanan.

Perbolehkan akses firewall

Jika sumber daya Azure Anda berada di belakang firewall, pastikan ada aturan masuk yang mengakui permintaan dari layanan pencarian Anda.

• Untuk koneksi wilayah yang sama ke Azure Blob Storage atau Azure Data Lake Storage Gen2, gunakan identitas terkelola sistem dan pengecualian layanan tepercaya. Secara opsional, Anda dapat mengonfigurasi aturan instans sumber daya untuk mengakui permintaan.

• Untuk semua sumber daya dan koneksi lainnya, konfigurasikan aturan firewall IP yang mengakui permintaan dari Pencarian. Lihat Akses pengindeks ke konten yang dilindungi oleh fitur keamanan jaringan Azure untuk detailnya.

Menetapkan peran

Identitas terkelola harus dipasangkan dengan peran Azure yang menentukan izin pada sumber daya Azure.

• Izin pembaca data diperlukan untuk koneksi data pengindeks dan untuk mengakses kunci yang dikelola pelanggan di Azure Key Vault.

• Izin kontributor (tulis) diperlukan untuk fitur pengayaan AI yang menggunakan Azure Storage untuk menghosting data sesi debug, penembolokan pengayaan, dan penyimpanan konten jangka panjang di penyimpanan pengetahuan.

Langkah-langkah berikut adalah untuk Azure Storage. Jika sumber daya Anda adalah Azure Cosmos DB atau Azure SQL, langkah-langkahnya serupa.

1. Masuk ke portal Azure dan temukan sumber daya Azure Anda yang harus diakses oleh layanan pencarian.

2. Di Azure Storage, pilih Kontrol akses (AIM) di panel navigasi kiri.

3. Pilih Tambahkan penetapan peran.

4. Pada halaman Peran , pilih peran yang diperlukan untuk layanan pencarian Anda:

   Tugas	Penetapan peran
   Pengindeksan blob menggunakan pengindeks	Menambahkan Pembaca Data Blob Penyimpanan
   Pengindeksan ADLS Gen2 menggunakan pengindeks	Menambahkan Pembaca Data Blob Penyimpanan
   Pengindeksan tabel menggunakan pengindeks	Menambahkan Pembaca dan Akses Data
   Pengindeksan file menggunakan pengindeks	Menambahkan Pembaca dan Akses Data
   Menulis ke penyimpanan pengetahuan	Tambahkan Storage Blob DataContributor untuk proyeksi objek dan file, serta Pembaca dan Akses Data untuk proyeksi tabel.
   Menulis ke cache pengayaan	Menambahkan Kontributor Data Blob Penyimpanan
   Simpan status sesi debug	Menambahkan Kontributor Data Blob Penyimpanan
   Menyematkan data (vektorisasi) menggunakan model penyematan Azure OpenAI	Menambahkan Pengguna OpenAI Cognitive Services

5. Pada halaman Anggota , pilih Identitas Terkelola.

6. Pilih anggota. Di halaman Pilih identitas terkelola, pilih langganan Anda lalu filter menurut jenis layanan, lalu pilih layanan. Hanya layanan yang memiliki identitas terkelola yang akan tersedia untuk dipilih.

   

7. Pilih Tinjau + tetapkan.

Contoh string koneksi

Setelah identitas terkelola didefinisikan untuk layanan pencarian dan diberi penetapan peran, koneksi keluar dapat dimodifikasi untuk menggunakan ID sumber daya unik dari sumber daya Azure lainnya. Berikut adalah beberapa contoh string koneksi untuk berbagai skenario.

Sumber data blob (sistem):

Sumber data pengindeks menyertakan properti "info masuk" yang menentukan bagaimana koneksi dibuat ke sumber data. Contoh berikut menunjukkan string koneksi menentukan ID sumber daya unik dari akun penyimpanan. ID Microsoft Entra akan mengautentikasi permintaan menggunakan identitas terkelola sistem dari layanan pencarian. Perhatikan bahwa string koneksi tidak menyertakan kontainer. Dalam definisi sumber data, nama kontainer ditentukan dalam properti "kontainer" (tidak ditampilkan), bukan string koneksi.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Sumber data blob (pengguna):

Permintaan pencarian ke Azure Storage juga dapat dibuat di bawah identitas terkelola yang ditetapkan pengguna, saat ini dalam pratinjau. Identitas pengguna layanan pencarian ditentukan dalam properti "identitas". Anda dapat menggunakan portal atau pratinjau REST API versi 2021-04-30-Preview untuk mengatur identitas.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Penyimpanan pengetahuan:

Definisi penyimpanan pengetahuan menyertakan string koneksi ke Azure Storage. Di Azure Storage, penyimpanan pengetahuan akan membuat proyeksi sebagai blob dan tabel. string koneksi adalah ID sumber daya unik dari akun penyimpanan Anda. Perhatikan bahwa string tidak menyertakan kontainer atau tabel di jalur. Ini didefinisikan dalam definisi proyeksi yang disematkan, bukan string koneksi.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Cache pengayaan:

Pengindeks membuat, menggunakan, dan mengingat kontainer yang digunakan untuk pengayaan cache. Tidak perlu menyertakan kontainer dalam cache string koneksi. Anda dapat menemukan ID objek di halaman Identitas layanan pencarian Anda di portal.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sesi debug:

Sesi debug berjalan di portal dan mengambil string koneksi saat Anda memulai sesi. Anda dapat menempelkan string yang mirip dengan contoh berikut.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Keterampilan kustom:

Keterampilan kustom menargetkan titik akhir fungsi Azure atau kode kustom hosting aplikasi. Titik akhir ditentukan dalam definisi keterampilan kustom. Kehadiran "authResourceId" memberi tahu layanan pencarian untuk terhubung menggunakan identitas terkelola, meneruskan ID aplikasi fungsi atau aplikasi target di properti .

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Keterampilan penyematan Azure OpenAI dan vektorizer Azure OpenAI:

Keterampilan dan vektorizer penyematan Azure OpenAI di Pencarian AI menargetkan titik akhir layanan Azure OpenAI yang menghosting model penyematan. Titik akhir ditentukan dalam definisi keterampilan penyematan Azure OpenAI dan/atau dalam definisi vektorizer Azure OpenAI. Identitas yang dikelola sistem digunakan jika dikonfigurasi dan jika "apikey" dan "authIdentity" kosong. Properti "authIdentity" hanya digunakan untuk identitas terkelola yang ditetapkan pengguna.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]

Lihat juga

• Ringkasan keamanan
• Ringkasan pengayaan AI
• Ringkasan pengindeks
• Autentikasi dengan Microsoft Entra ID
• Tentang identitas terkelola (ID Microsoft Entra)