Mengonfigurasi layanan pencarian untuk menyambungkan menggunakan identitas terkelola

Note

Pencarian Azure AI tersedia melalui portal Azure, REST API, dan Azure SDK. Ini juga mendukung Foundry IQ, lapisan pengetahuan terkelola yang mengubah konten perusahaan menjadi pangkalan pengetahuan yang dapat digunakan kembali dan sadar izin untuk agen di portal Microsoft Foundry.

Anda dapat menggunakan prinsipal keamanan dan penetapan peran Microsoft Entra ID untuk membuat koneksi keluar dari Pencarian Azure AI ke sumber daya Azure lain yang menyediakan data, AI terapan, atau vektorisasi ketika pengindeksan atau kueri berlangsung.

Untuk menggunakan peran pada koneksi keluar, pertama-tama konfigurasikan layanan pencarian Anda untuk menggunakan identitas terkelola yang ditetapkan secara sistem atau pengguna sebagai prinsip keamanan untuk layanan pencarian Anda di penyewa Microsoft Entra. Setelah Anda memiliki identitas terkelola, Anda dapat menetapkan peran untuk akses resmi. Identitas terkelola dan penetapan peran menghilangkan kebutuhan untuk meneruskan rahasia dan kredensial di dalam string koneksi atau kode.

Prasyarat

Layanan Pencarian Azure AI di wilayah mana pun pada tingkat Basic atau yang lebih tinggi.
Sumber daya Azure yang menerima permintaan masuk dari entitas keamanan Microsoft Entra yang memiliki penugasan peran yang valid.
Untuk membuat identitas terkelola, Anda harus menjadi Pemilik atau Administrator Akses Pengguna. Untuk menetapkan peran, Anda harus menjadi Pemilik, Administrator Akses Pengguna, Administrator Kontrol Akses berbasis Peran, atau anggota peran kustom dengan izin Microsoft.Authorization/roleAssignments/write.

Skenario yang didukung

Anda dapat menggunakan identitas terkelola untuk skenario berikut.

Skenario	Sistem ditetapkan	Pengguna yang ditetapkan
Menyambungkan ke sumber data pengindeks¹	Ya	Ya
Sambungkan ke model penyematan dan penyelesaian obrolan di Azure OpenAI, Microsoft Foundry, dan Azure Functions melalui keterampilan/vektorizer ²	Ya	Ya
Hubungkan ke Azure Key Vault untuk kunci yang dikelola pelanggan	Ya	Ya
Hubungkan ke sesi Debug (dihosting di Azure Storage)¹	Ya	Tidak
Sambungkan ke cache pengayaan, yang di-host di Azure Storage (pratinjau)^1,³	Ya	Ya ⁴
Hubungkan ke Penyimpanan Pengetahuan (dihosting di Azure Storage)¹	Ya	Ya

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

² Koneksi ke Azure OpenAI, Foundry, dan Azure Functions melalui keterampilan/vektorizer meliputi: Keterampilan kustom, Vektorizer kustom, Keterampilan penyematan Azure OpenAI, Vektorizer Azure OpenAI, Keterampilan AML dan Vektorizer katalog model Microsoft Foundry.

³ Layanan pencarian AI saat ini tidak dapat tersambung ke tabel pada akun penyimpanan yang telah menonaktifkan akses kunci bersama.

⁴ Identitas terkelola yang ditetapkan pengguna untuk koneksi cache pengayaan memerlukan pratinjau REST API (pratinjau 2025-11-01 atau yang lebih baru) atau pratinjau paket SDK. Semua skenario identitas terkelola lain yang ditetapkan pengguna dalam tabel ini didukung di REST API versi 2026-04-01 dan yang lebih baru.

Membuat identitas terkelola sistem

Identitas terkelola yang ditetapkan sistem adalah prinsip keamanan Microsoft Entra ID yang secara otomatis dibuat dan ditautkan ke sumber daya Azure, seperti layanan Pencarian Azure AI.

Anda dapat memiliki satu identitas terkelola yang ditetapkan sistem untuk setiap layanan pencarian. Ini unik untuk layanan pencarian Anda dan terikat ke layanan selama masa pakainya.

Saat Anda mengaktifkan identitas terkelola yang ditetapkan sistem, Microsoft Entra ID membuat entitas keamanan untuk layanan pencarian Anda yang digunakan untuk mengautentikasi ke sumber daya Azure lain. Anda kemudian dapat menggunakan identitas ini dalam penetapan peran untuk akses resmi ke data dan operasi.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Pengaturan>Identitas.
Pada tab Sistem yang ditetapkan , di bawah Status, pilih Aktif.
Pilih Simpan.

Setelah Anda menyimpan pengaturan, halaman diperbarui untuk menampilkan pengidentifikasi objek yang ditetapkan ke layanan pencarian Anda.

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Untuk informasi selengkapnya, lihat Buat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure PowerShell.

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Untuk informasi selengkapnya, lihat Buat layanan pencarian dengan identitas terkelola yang ditetapkan sistem (Azure CLI).

Gunakan Layanan - Buat Atau Perbarui (REST API) untuk merumuskan permintaan.

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

Respons mencakup konfirmasi dan pengidentifikasi objek untuk identitas terkelola yang ditetapkan sistem.

Membuat identitas terkelola yang ditetapkan pengguna

Identitas terkelola yang ditetapkan pengguna adalah sumber daya Azure yang dapat dilingkup ke langganan, grup sumber daya, atau jenis sumber daya.

Anda dapat membuat beberapa identitas terkelola yang ditetapkan pengguna untuk lebih banyak granularitas dalam penetapan peran. Misalnya, Anda mungkin menginginkan identitas terpisah untuk aplikasi dan skenario yang berbeda. Sebagai sumber daya yang dibuat dan dikelola secara independen, sumber daya tersebut tidak terikat dengan layanan itu sendiri.

Langkah-langkah untuk menyiapkan identitas terkelola yang ditetapkan pengguna adalah sebagai berikut:

Di langganan Azure Anda, buat identitas terkelola yang ditetapkan pengguna.
Pada layanan pencarian Anda, kaitkan identitas terkelola yang ditetapkan pengguna dengan layanan pencarian Anda.
Di layanan Azure lain yang ingin Anda sambungkan, buat penetapan peran untuk identitas tersebut.

Mengaitkan identitas terkelola yang ditetapkan pengguna dengan layanan Pencarian Azure AI didukung di portal Azure, REST API Manajemen Pencarian, dan paket SDK yang menyediakan fitur tersebut.

portal Azure
REST API

Masuk ke portal Azure.
Di sudut kiri atas dasbor Anda, pilih Buat sumber daya.
Gunakan kotak pencarian untuk menemukan Identitas Terkelola yang Ditetapkan Pengguna, lalu pilih Buat.
Pilih langganan, grup sumber daya, dan wilayah. Berikan identitas nama yang deskriptif.
Pilih Buat dan tunggu hingga sumber daya selesai disebarkan.

Dibutuhkan beberapa menit sebelum Anda dapat menggunakan identitas.
Pada halaman layanan pencarian Anda, pilih Pengaturan>Identitas.
Pada tab Pengguna yang ditetapkan , pilih Tambahkan.
Pilih langganan dan identitas terkelola yang ditetapkan pengguna yang sebelumnya Anda buat.

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

Gunakan Layanan - Pembaruan (REST API) untuk merumuskan permintaan.

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

Atur identity.type ke jenis identitas.
- Nilai yang valid adalah SystemAssigned, UserAssigned, atau SystemAssigned, UserAssigned untuk keduanya.
- Nilai None menghapus identitas yang ditetapkan sebelumnya dari layanan pencarian.
Perbarui identity.userAssignedIdentities untuk menyertakan detail identitas terkelola yang ditetapkan pengguna Anda. Identitas ini harus sudah ada sebelum Anda dapat menentukannya dalam permintaan.

Menetapkan peran

Setelah Anda memiliki identitas terkelola, tetapkan peran yang menentukan izin layanan pencarian pada sumber daya Azure.

Izin baca diperlukan untuk koneksi data pengindeks dan untuk mengakses kunci yang dikelola pelanggan di Azure Key Vault.
Izin tulis diperlukan untuk kemampuan pengayaan AI yang menggunakan Azure Storage untuk menyimpan data sesi debug, penyimpanan sementara pengayaan, dan penyimpanan konten jangka panjang di penyimpanan pengetahuan.

Langkah-langkah berikut mengilustrasikan alur kerja penetapan peran. Contoh ini untuk Azure OpenAI. Untuk sumber daya Azure lainnya, lihat Hubungkan ke Azure Storage, Hubungkan ke Azure Cosmos DB, atau Hubungkan ke Azure SQL.

Buka sumber daya OpenAI Azure Anda di portal Azure.
Pilih Kontrol akses dari menu sebelah kiri.
Pilih Tambahkan lalu pilih Tambahkan penetapan peran.
Di bawah Peran fungsi pekerjaan, pilih Pengguna OpenAI Cognitive Services lalu pilih Berikutnya.
Di bawah Anggota, pilih Identitas terkelola lalu pilih Anggota.
Filter menurut langganan dan jenis sumber daya (Layanan pencarian), lalu pilih identitas terkelola layanan pencarian Anda.
Pilih Tinjau + tetapkan.

Contoh string koneksi

Ingat dari deskripsi skenario bahwa Anda dapat menggunakan identitas terkelola dalam string koneksi ke sumber daya Azure lainnya. Bagian ini menyediakan contoh.

Koneksi identitas terkelola yang ditetapkan sistem menggunakan versi REST API yang tersedia secara umum. Koneksi identitas terkelola yang ditetapkan pengguna menggunakan REST API versi 2026-04-01 atau yang lebih baru, kecuali untuk koneksi cache pengayaan, yang masih memerlukan versi API pratinjau.

Tips

Anda dapat membuat sebagian besar objek ini di portal Azure, menentukan sistem atau identitas terkelola yang ditetapkan pengguna, lalu melihat definisi JSON untuk mendapatkan string koneksi.

Sumber data blob (identitas terkelola sistem):

Sumber data pengindeks menyertakan credentials properti yang menentukan bagaimana koneksi dibuat ke sumber data. Contoh berikut menunjukkan string koneksi yang menyatakan ID sumber daya unik pada akun penyimpanan.

Identitas terkelola sistem ditunjukkan ketika string koneksi adalah ID sumber daya unik dari layanan atau aplikasi yang mendukung Microsoft Entra ID. Identitas terkelola yang ditetapkan pengguna ditentukan melalui properti identity.

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

Sumber data blob (identitas pengguna yang terkelola):

Identitas terkelola yang ditetapkan pengguna didukung melalui identity properti di SearchIndexerDataSource dengan REST API versi 2026-04-01 atau yang lebih baru.

"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}"
  }

Basis pengetahuan (identitas yang dikelola oleh sistem):

Definisi penyimpanan pengetahuan mencakup string koneksi untuk Azure Storage. 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 tertanam, bukan string koneksi.

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

Penyimpanan pengetahuan (identitas terkelola pengguna):

Identitas terkelola yang ditetapkan pengguna didukung melalui identity properti di SearchIndexerKnowledgeStore dengan REST API versi 2026-04-01 atau yang lebih baru.

"knowledgeStore": {
  "storageConnectionString": "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}"
  }
}

cache pengayaan (pratinjau):

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 Identity layanan pencarian Anda di portal Azure.

"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 Azure 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 khusus:

Keterampilan kustom menargetkan titik akhir fungsi Azure atau kode kustom hosting aplikasi.

uri adalah titik akhir fungsi atau aplikasi.
authResourceId memberi tahu layanan pencarian untuk terhubung menggunakan identitas terkelola, dengan meneruskan ID aplikasi dari fungsi atau aplikasi target di dalam 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": [ ...]
}

Contoh koneksi untuk model

Untuk koneksi yang dibuat menggunakan identitas terkelola, bagian ini menunjukkan contoh informasi koneksi yang digunakan oleh layanan pencarian untuk menyambungkan ke model di sumber daya lain. Koneksi melalui identitas terkelola sistem transparan; identitas dan peran ada, dan koneksi berhasil jika dikonfigurasi dengan benar. Sebaliknya, identitas terkelola pengguna memerlukan properti koneksi tambahan.

Kemampuan penyematan Azure OpenAI dan vektorisasi Azure OpenAI:

Keterampilan embed dan vektorizer OpenAI Azure dalam Pencarian AI menargetkan titik akhir dari Azure OpenAI yang menghosting model embed. Titik akhir ditentukan dalam definisi embedding Azure OpenAI dan/atau dalam definisi vektorisasi Azure OpenAI.

Identitas yang dikelola sistem digunakan secara otomatis jika "apikey" dan "authIdentity" kosong, seperti yang ditunjukkan dalam contoh berikut. Properti "authIdentity" hanya digunakan untuk identitas terkelola yang ditetapkan pengguna.

Contoh identitas yang dikelola sistem:

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

Berikut adalah contoh vektorizer yang dikonfigurasi untuk identitas terkelola yang ditetapkan sistem. Vektorisasi ditentukan dalam indeks pencarian.

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

Contoh identitas terkelola yang ditetapkan pengguna:

Identitas terkelola yang ditetapkan pengguna digunakan jika "apiKey" kosong dan valid "authIdentity" disediakan.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Berikut adalah contoh vektorizer yang dikonfigurasi untuk identitas terkelola yang ditetapkan pengguna. Vektorisasi ditentukan dalam indeks pencarian.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Periksa akses firewall

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

Untuk koneksi wilayah yang sama ke Azure Blob Storage atau Azure Data Lake Storage Gen2, gunakan identitas terkelola sistem dan pengecualian layanan percaya. Secara opsional, Anda dapat mengonfigurasi aturan instans sumber daya untuk mengakui permintaan.
Untuk semua sumber daya dan koneksi lainnya, mengonfigurasi aturan firewall IP yang mengakui permintaan dari Pencarian Azure AI. Lihat akses Indexer ke konten yang dilindungi oleh fitur keamanan jaringan Azure untuk detailnya.

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-07-03