Menghubungkan ke Pencarian Azure AI menggunakan peran

Pencarian Azure AI mendukung kontrol akses berbasis role melalui Microsoft Entra ID. Akses berbasis peran bersifat opsional tetapi disarankan. Alternatifnya adalah autentikasi berbasis kunci, yang merupakan default.

Jika Anda menetapkan beberapa peran ke entitas keamanan, izin digabungkan. Penugasan peran berlaku di semua alat dan perpustakaan klien. Anda dapat menetapkan peran menggunakan pendekatan yang didukung.

Artikel ini menjelaskan cara menetapkan peran bawaan untuk administrasi layanan, pengembangan, dan akses kueri serta pengambilan data secara baca-saja. Ini juga menyediakan langkah-langkah untuk membuat peran kustom dan menguji penetapan peran.

Tip

Ingin gambaran umum singkat tentang peran bawaan? Lihat Ringkasan izin.
Untuk mengontrol akses ke hasil pencarian di tingkat dokumen, juga dikenal sebagai keamanan tingkat baris, lihat kontrol akses tingkat Document di Pencarian Azure AI.

Prasyarat

Layanan Pencarian Azure AI (wilayah apa pun dan tingkat apa pun) dengan akses berbasis peran diaktifkan.
Izin untuk menetapkan peran Azure. Salah satu peran berikut berfungsi:
- Pemilik
- Administrator Akses Pengguna
- Administrator Kontrol Akses Berbasis Peran
- Peran kustom dengan izin Microsoft.Authorization/roleAssignments/write

Peran bawaan

Peran adalah kumpulan izin yang memengaruhi sarana kontrol atau sarana data:

Sarana kontrol: Operasi untuk provisi, konfigurasi, dan administrasi layanan. Operasi sarana kontrol termasuk membuat atau menghapus layanan pencarian, mencantumkan kunci API, dan mengelola pengaturan jaringan dan autentikasi. Tersedia melalui REST API Azure Resource Manager, Search Management REST API, dan pustaka klien Azure SDK yang setara.
Bidang data: Operasi terhadap titik akhir layanan pencarian. Operasi sarana data termasuk dalam dua kategori: manajemen objek dan akses konten. Tersedia melalui Search Service REST API dan pustaka klien Azure SDK yang setara.

Deskripsi peran

Peran bawaan berikut memberikan izin untuk Pencarian Azure AI. Peran bidang kontrol selalu tersedia, sementara peran bidang data memerlukan akses berbasis peran untuk aktif pada layanan pencarian Anda. Anda dapat menggabungkan peran bawaan untuk akses yang lebih luas atau membuat peran kustom dengan izin tertentu yang Anda butuhkan.

Peranan	Pesawat	Deskripsi
Pemilik	Kontrol	Akses sarana kontrol penuh, termasuk kemampuan untuk menetapkan peran dan mengubah pengaturan autentikasi. Administrator langganan memiliki peran ini secara default. Dapat mengelola kunci API. Tidak dapat membuat objek pencarian, memuat dokumen, indeks kueri, atau mengambil dari pangkalan pengetahuan.
Kontributor	Kontrol	Tingkat akses sarana kontrol yang sama dengan Pemilik, dikurangi kemampuan untuk menetapkan peran.
Pembaca	Kontrol	Akses sarana kontrol baca-saja. Dapat melihat metrik layanan dan definisi objek. Tidak dapat melihat atau mengelola kunci API, memuat dokumen, mengindeks kueri, atau mengambil dari pangkalan pengetahuan.
Kontributor Layanan Pencarian	Kontrol dan Data	Akses sarana kontrol penuh. Akses sarana data terbatas pada manajemen objek. Dapat membuat indeks, pengindeks, set keterampilan, pangkalan pengetahuan, dan objek pencarian lainnya. Tidak dapat memuat dokumen, indeks kueri, atau mengambil dari pangkalan pengetahuan. Untuk daftar izin lengkap, lihat `Microsoft.Search/searchServices/*`.
Kontributor Data Indeks Pencarian	Data Informasi	Akses baca-tulis ke konten. Dapat memuat dokumen, indeks kueri, dan mengambil dari pangkalan pengetahuan. Tidak dapat mengubah definisi objek atau mengambil kunci admin.
Pembaca Data Indeks Pencarian	Data Informasi	Akses konten baca-saja. Dapat mengkueri indeks dan mengambil dari pangkalan pengetahuan. Tidak dapat memuat dokumen, mengubah definisi objek, atau mengambil kunci admin.

Penting

Pemilik, Kontributor, dan Kontributor Layanan Pencarian dapat mengambil kunci admin, untuk menyediakan akses baca-tulis penuh ke lapisan data. Hanya berikan peran ini kepada pengguna tepercaya.
Secara default, peran bidang data berlaku untuk semua indeks pada layanan pencarian. Untuk membatasi Kontributor Data Indeks Penelusuran atau Pembaca Data Indeks Penelusuran ke satu indeks, lihat Memberikan akses ke satu indeks.

Ringkasan izin

Gunakan tabel berikut untuk menemukan peran mana yang menyediakan izin yang Anda butuhkan dengan cepat.

Hak akses	Pemilik/Kontributor	Pembaca	Kontributor Layanan Pencarian	Kontributor Data Indeks Pencarian	Pembaca Data Indeks Pencarian
Membuat dan mengonfigurasi layanan Pencarian Azure AI	✅	❌	✅	❌	❌
Mengakses layanan di portal Azure	✅	✅	✅	❌	❌
Menampilkan properti layanan, metrik, dan titik akhir	✅	✅	✅	❌	❌
Mencantumkan semua objek pada layanan	✅	✅	✅	❌	❌
Kuota akses dan statistik layanan	✅	❌	✅	❌	❌
Menampilkan, menyalin, dan meregenerasi kunci	✅	❌	✅	❌	❌
Pengaturan opsi autentikasi	✅	❌	✅	❌	❌
Menampilkan peran, kebijakan, dan definisi	✅	✅	✅	❌	❌
Mengonfigurasi keamanan jaringan dan koneksi privat	✅	❌	✅	❌	❌
Membuat, menjalankan, dan mengelola objek pencarian ¹	❌	❌	✅	❌	❌
Mengunggah data untuk pengindeksan ²	❌	❌	❌	✅	❌
Menjalankan kueri pada indeks	❌	❌	❌	✅	✅
Mengambil dari pangkalan pengetahuan	❌	❌	❌	✅	✅
Melewati filter izin dengan akses baca yang ditingkatkan	❌	❌	❌	✅	❌

¹ Mencakup indeks, pengindeks, sumber data, set keterampilan, alias, peta sinonim, sesi debug, pangkalan pengetahuan, dan sumber pengetahuan. Pengindeks juga mendukung operasi menjalankan dan reset.

² Pemilik atau Kontributor dapat menjalankan wizard Impor data untuk membuat dan memuat indeks, meskipun mereka tidak dapat mengunggah dokumen di klien lain. Demikian pula, pengindeks dapat menulis ke indeks apa pun di layanan pencarian, terlepas dari penetapan peran per indeks. Dalam kedua kasus, layanan pencarian (bukan pengguna) melakukan tindakan bidang data menggunakan izin Microsoft.Search/searchServices/indexes/documents/*.

Menetapkan peran bawaan

Di bagian ini, Anda menetapkan peran untuk:

Administrasi layanan
Pengembangan
Akses baca-saja

Menetapkan peran untuk administrasi layanan

Peran berikut memungkinkan Anda membuat, mengonfigurasi, dan mengelola layanan pencarian. Peran ini bersifat hierarkis, jadi pilih salah satu berdasarkan tingkat akses yang Anda butuhkan.

Peranan	ID
Pemilik	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Kontributor	b24988ac-6180-42a0-ab88-20f7382dd24c
Pembaca	acdd72a7-3385-48ef-bd42-f606fba81ae7

Portal Azure
PowerShell

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Kontrol akses (IAM).
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih peran: Pemilik, Kontributor, atau Pembaca.
Pada tab Members, pilih identitas pengguna atau grup Microsoft Entra. Jika Anda menyiapkan izin untuk layanan Azure lain, pilih identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.
Pada tab Review + assign, pilih Review + assign untuk memberikan peran.

Saat Anda tugaskan peran menggunakan PowerShell, panggil New-AzRoleAssignment, menyediakan nama pengguna atau grup Azure dan cakupan penugasan.

Contoh ini membuat penetapan peran yang dibatasi ke dalam layanan pencarian.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Referensi:New-AzRoleAssignment

Menetapkan peran untuk pengembangan

Peran berikut memungkinkan Anda membuat objek pencarian, memuat dokumen, mengindeks kueri, dan mengambil dari pangkalan pengetahuan. Tetapkan ketiga peran untuk mencakup berbagai tugas pengembangan.

Peranan	ID
Kontributor Layanan Pencarian	7ca78c08-252a-4471-8644-bb5ff32d4ba0
Kontributor Data Indeks Pencarian	8ebe5a00-799e-43f5-93ac-243d3dce84a7
Pembaca Data Indeks Pencarian	1407120a-92aa-4202-b7e9-c0e197c71c8f

Portal Azure
PowerShell

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Kontrol akses (IAM).
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih Kontributor Layanan Pencarian.
Pada tab Members, pilih identitas pengguna atau grup Microsoft Entra. Jika Anda menyiapkan izin untuk layanan Azure lain, pilih identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.
Pada tab Review + assign, pilih Review + assign untuk memberikan peran.
Ulangi langkah-langkah ini untuk menetapkan Kontributor Data Indeks Pencarian dan Pembaca Data Indeks Pencarian.

Saat Anda tugaskan peran menggunakan PowerShell, panggil New-AzRoleAssignment, menyediakan nama pengguna atau grup Azure dan cakupan penugasan.

Contoh ini membuat penetapan peran yang dibatasi ke dalam layanan pencarian.

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Contoh ini membuat pemberian peran yang dibatasi ke indeks tertentu:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Referensi:New-AzRoleAssignment

Menetapkan peran untuk akses baca saja

Gunakan peran berikut untuk aplikasi dan proses yang hanya memerlukan akses baca ke indeks dan pangkalan pengetahuan. Operasi yang didukung termasuk pencarian, pencarian, lengkapi otomatis, dan saran untuk indeks dan ambil untuk pangkalan pengetahuan.

Peranan	ID
Pembaca Data Indeks Pencarian	1407120a-92aa-4202-b7e9-c0e197c71c8f

Portal Azure
PowerShell

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilih Kontrol akses (IAM).
Pilih + Tambahkan>Tambahkan penetapan peran.
Pilih peran Pembaca Data Indeks Pencarian .
Pada tab Members, pilih identitas pengguna atau grup Microsoft Entra. Jika Anda menyiapkan izin untuk layanan Azure lain, pilih identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna.
Pada tab Review + assign, pilih Review + assign untuk memberikan peran.

Saat Anda tugaskan peran menggunakan PowerShell, panggil New-AzRoleAssignment, menyediakan nama pengguna atau grup Azure dan cakupan penugasan.

Dapatkan ID langganan Anda, grup sumber daya layanan pencarian, dan nama layanan pencarian.
Dapatkan pengidentifikasi objek layanan Azure Anda, seperti Azure OpenAI.
```
 Get-AzADServicePrincipal -SearchString <your-azure-openai-resource-name>
```
Output mencakup properti Id yang berisi ID objek yang Anda butuhkan untuk penetapan peran.
Dapatkan definisi peran dan tinjau izin untuk memastikan ini adalah peran yang Anda inginkan.
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

Buat penugasan peran, menggantikan placeholder dengan nilai yang valid.

New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>

Tugas yang berhasil menghasilkan detail penetapan peran termasuk RoleAssignmentId.

Berikut adalah contoh penetapan peran yang dilingkup ke indeks tertentu:

New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>/indexes/<your-index-name>

Referensi:New-AzRoleAssignment

Menguji penugasan peran

Gunakan klien untuk menguji penetapan peran. Ingat bahwa peran bersifat kumulatif. Anda tidak dapat menghapus atau menolak peran yang diwariskan yang memiliki ruang lingkup di tingkat langganan atau grup sumber daya pada tingkat sumber daya (layanan pencarian).

Sebelum melanjutkan, konfigurasikan aplikasi Anda untuk koneksi tanpa kunci dan tetapkan penetapan peran.

Buka layanan pencarian Anda di portal Azure.
Dari panel kiri, pilihIndeks> pencarian untuk menguji izin terkait indeks:
- Kontributor Layanan Pencarian dapat membuat, memodifikasi, dan menghapus objek pencarian tetapi tidak dapat memuat dokumen atau menjalankan kueri. Untuk memverifikasi izin, buat indeks pencarian.
- Kontributor Data Indeks Pencarian dapat memuat dokumen. Tidak ada opsi muat dokumen di portal Azure di luar Impor data wizard, tetapi Anda dapat mengatur ulang dan menjalankan pengindeksir untuk mengonfirmasi izin pemuatan dokumen.
- Pembaca Data Indeks Pencarian dapat mengkueri indeks. Untuk memverifikasi izin, gunakan Penjelajah pencarian. Anda seharusnya dapat mengirim kueri dan melihat hasil, tetapi Anda seharusnya tidak dapat melihat definisi indeks atau membuat indeks.

Pendekatan ini mengasumsikan Visual Studio Code dengan ekstensi Klien REST.

Buka shell perintah untuk Azure CLI dan masuk ke langganan Azure Anda.
```
az login
```
Dapatkan ID penyewa dan ID langganan Anda. Gunakan ID sebagai variabel di langkah mendatang.
```
az account show
```

Dapatkan token akses untuk bidang data Pencarian Azure AI.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Tempelkan variabel ini dalam file teks baru di Visual Studio Code.

@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

Kirim permintaan yang menggunakan variabel yang Anda tentukan. Untuk peran Pembaca Data Indeks Pencarian, Anda dapat mengirim kueri menggunakan versi API yang didukung.
```
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2026-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }
```
Referensi:Cari Dokumen

Kueri yang berhasil mengembalikan hasil pencarian dengan dokumen yang cocok. Jika indeks kosong atau tidak memiliki kecocokan, value berisi array kosong.

Tip

Untuk informasi selengkapnya tentang cara memperoleh token untuk lingkungan tertentu, lihat Kelola layanan Pencarian Azure AI dengan REST API dan pustaka autentikasi platform identitas Microsoft.

Instal paket yang diperlukan:

dotnet add package Azure.Search.Documents
dotnet add package Azure.Identity

Gunakan Azure. Identitas untuk .NET untuk autentikasi token. Microsoft merekomendasikan DefaultAzureCredential() untuk sebagian besar skenario.

Berikut adalah contoh koneksi klien menggunakan DefaultAzureCredential():

// Create a SearchIndexClient to send create/delete index commands
// Requires Search Service Contributor role
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
// Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Referensi:SearchClient, SearchIndexClient, DefaultAzureCredential

Berikut adalah contoh lain menggunakan kredensial rahasia klien:

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

Berikut adalah contoh menjalankan kueri:

SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    Console.WriteLine(result.Document["HotelName"]);
}

Kueri yang berhasil mengembalikan hasil pencarian. Jika tidak ada dokumen yang cocok, koleksi hasil kosong.

Instal paket yang diperlukan:

pip install azure-search-documents azure-identity

Gunakan Azure. Identitas untuk Python untuk autentikasi token.
Gunakan DefaultAzureCredential jika klien Python adalah aplikasi yang menjalankan sisi server. Aktifkan autentikasi interaktif jika aplikasi berjalan di browser.

Berikut adalah sebuah contoh:

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Referensi:SearchClient, DefaultAzureCredential

Instal paket yang diperlukan:

npm install @azure/search-documents @azure/identity

Gunakan Azure. Identitas untuk JavaScript untuk autentikasi token.
Jika Anda menggunakan React, gunakan InteractiveBrowserCredential untuk autentikasi Microsoft Entra ke Pencarian Azure AI. Untuk informasi selengkapnya, lihat Kapan menggunakan @azure/identity.

Referensi:SearchClient, DefaultAzureCredential

Tambahkan dependensi yang diperlukan ke pom.xml:

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-search-documents</artifactId>
  <version>11.7.4</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.15.0</version>
</dependency>

Gunakan Azure. Identitas untuk Java untuk autentikasi token.
Gunakan DefaultAzureCredential untuk aplikasi yang berjalan di Azure.

Memberikan akses ke satu indeks

Dalam beberapa skenario, Anda mungkin ingin membatasi akses aplikasi ke satu sumber daya, seperti indeks.

Portal Azure saat ini tidak mendukung penetapan peran pada tingkat granularitas ini, tetapi Anda dapat menetapkan peran menggunakan PowerShell atau Azure CLI.

Di PowerShell, gunakan New-AzRoleAssignment, memberikan nama pengguna atau grup Azure dan cakupan penugasan.

Muat modul Azure dan AzureAD dan sambungkan ke akun Azure Anda:

Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

Tambahkan penetapan peran yang terlingkup ke indeks individual:

New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Referensi:New-AzRoleAssignment

Cakupan per indeks dan operasi pengindeks

Penetapan peran per indeks hanya berlaku untuk operasi API langsung, seperti kueri atau unggahan dokumen dari pengguna atau aplikasi. Pengindeks tidak dibatasi oleh izin per indeks karena beroperasi dengan kredensial tingkat layanan.

Pengguna dengan peran Kontributor Layanan Pencarian dapat membuat pengindeks yang menulis ke indeks apa pun di layanan pencarian, bahkan indeks di mana pengguna tersebut tidak memiliki penetapan peran per indeks.

Untuk isolasi data yang ketat antar indeks, pertimbangkan pendekatan ini:

Gunakan layanan pencarian terpisah untuk tim atau pengguna yang memerlukan isolasi tingkat indeks.
Tetapkan Kontributor Layanan Pencarian hanya untuk administrator yang mengelola pengindeks.
Gunakan kontrol akses tingkat dokumen dengan filter keamanan untuk membatasi hasil kueri dalam indeks bersama.

Membuat peran kustom

Jika peran bawaan tidak memberikan kombinasi izin yang tepat, Anda dapat membuat peran kustom untuk mendukung operasi yang Anda butuhkan.

Contoh berikut mengkloning Pembaca Data Indeks Pencarian lalu menambahkan kemampuan untuk mencantumkan indeks berdasarkan nama. Biasanya, mencantumkan indeks pada layanan pencarian dianggap sebagai hak administratif.

Masuk ke portal Azure dan navigasikan ke layanan pencarian Anda.
Dari panel kiri, pilih Kontrol akses (IAM).
Pada tab Peran , temukan Pembaca Data Indeks Pencarian atau peran lain, pilih elipsis (...), lalu pilih Kloning.
Pada tab Basics, masukkan nama untuk peran kustom, seperti "Indeks Pencarian Data Explorer", lalu pilih Baru.
Pada tab Izin , pilih Tambahkan izin.
Di panel Tambahkan izin, pilih petak Microsoft Search.
Dengan Tindakan dipilih di bagian atas, atur izin berikut:
- Di bawah Microsoft.Search/operations, pilih Baca : Cantumkan semua operasi yang tersedia.
- Di bawah Microsoft.Search/searchServices/indexes, pilih Baca : Baca Indeks.

Beralih ke Aksi data di bagian atas, dan di bawah Microsoft.Search/searchServices/indexes/documents, pilih Baca : Baca Dokumen.

Definisi JSON terlihat seperti contoh berikut:

{
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

Pilih Tambahkan untuk menutup panel.
Pilih Tinjau + buat untuk membuat peran.

Sekarang Anda dapat menetapkan pengguna dan grup ke peran tersebut. Untuk informasi selengkapnya tentang langkah-langkah ini, lihat Buat atau perbarui peran kustom Azure menggunakan portal Azure.

Contoh PowerShell memperlihatkan sintaks JSON untuk membuat peran kustom yang merupakan kloning Pembaca Data Indeks Pencarian, tetapi dengan kemampuan untuk mencantumkan semua indeks menurut nama.

Tinjau daftar izin atom untuk menentukan izin mana yang Anda butuhkan. Untuk contoh ini, Anda memerlukan izin berikut:

"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/read",
"Microsoft.Search/searchServices/indexes/read"

Siapkan sesi PowerShell untuk membuat peran kustom. Untuk petunjuk terperinci, lihat Azure PowerShell.

Berikan definisi peran sebagai dokumen JSON. Contoh berikut menunjukkan sintaks untuk membuat peran kustom dengan PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Nota

Jika Anda menetapkan cakupan di tingkat indeks, gunakan tindakan data "Microsoft.Search/searchServices/indexes/documents/read".

Membuat kebijakan Akses Bersyarat

Jika Anda perlu menerapkan kebijakan organisasi, seperti autentikasi multifaktor, gunakan Akses Bersyarat Microsoft Entra.

Untuk membuat kebijakan Akses Bersyarat untuk Pencarian Azure AI:

Masuk ke portal Azure.
Cari Akses Bersyarat Microsoft Entra.
Pada halaman Gambaran Umum , pilih Buat kebijakan baru.
Di bawah Cloud app atau actions, tambahkan Pencarian Azure AI sebagai aplikasi cloud, bergantung pada cara Anda ingin menyiapkan kebijakan Anda.
Perbarui parameter yang tersisa dari kebijakan Anda. Misalnya, tentukan pengguna dan grup mana yang kebijakannya berlaku.
Simpan kebijakan.

Penting

Jika layanan pencarian Anda memiliki identitas terkelola yang ditetapkan, layanan pencarian tertentu muncul sebagai aplikasi cloud. Namun, memilih layanan pencarian tertentu tersebut tidak memberlakukan kebijakan. Sebagai gantinya, pilih aplikasi cloud umum Pencarian Azure AI untuk menerapkan kebijakan Akses Bersyarat ke layanan pencarian Anda.

Troubleshooting

Saat Anda mengembangkan aplikasi yang menggunakan kontrol akses berbasis peran untuk autentikasi, Anda mungkin mengalami beberapa masalah umum:

Konfigurasi default untuk layanan pencarian adalah autentikasi berbasis kunci. Jika Anda tidak mengubah pengaturan ini ke kontrol aksesberbasis Peran atau Keduanya, semua permintaan yang menggunakan autentikasi berbasis peran secara otomatis ditolak, terlepas dari izin yang mendasar.
Jika permintaan Anda menyertakan kunci API bersama kredensial berbasis peran, layanan akan mengautentikasi menggunakan kunci. Hapus kunci API dari header permintaan Anda untuk menggunakan autentikasi berbasis peran.
Jika token otorisasi berasal dari identitas terkelola dan Anda baru-baru ini menetapkan izin yang sesuai, mungkin perlu waktu beberapa jam agar penetapan izin berlaku.
Jika kueri dengan izin tingkat dokumen tidak mengembalikan hasil yang diharapkan, gunakan Kontributor Data Indeks Pencarian atau buat peran kustom dengan izin yang ditingkatkan untuk diselidiki.

Langkah selanjutnya

Artikel ini menjelaskan cara menetapkan peran untuk operasi kontrol dan lapisan data di Pencarian Azure AI. Untuk instruksi komprehensif tentang menambahkan akses berbasis peran ke kode aplikasi Anda:

Sambungkan aplikasi Anda ke Pencarian Azure AI menggunakan identitas

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-07

Menghubungkan ke Pencarian Azure AI menggunakan peran

Prasyarat

Peran bawaan

Deskripsi peran

Ringkasan izin

Menetapkan peran bawaan

Menetapkan peran untuk administrasi layanan

Menetapkan peran untuk pengembangan

Menetapkan peran untuk akses baca saja

Menguji penugasan peran

Memberikan akses ke satu indeks

Cakupan per indeks dan operasi pengindeks

Membuat peran kustom

Membuat kebijakan Akses Bersyarat

Troubleshooting

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: