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.
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:
Tinjau instruksi penetapan peran untuk klien pilihan Anda:
Identifikasi nilai penerima tugas yang diperlukan oleh klien pilihan Anda. Bergantung pada jenis klien dan penerima tugas, nilai ini mungkin merupakan nama utama pengguna, ID objek grup, nama perwakilan layanan, ID aplikasi perwakilan layanan, atau ID objek Microsoft Entra.
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.
- Dapat mengambil kunci API admin dan kueri melalui operasi control plane.
- Tidak dapat memuat dokumen, indeks kueri, atau mengambil dari pangkalan pengetahuan secara langsung melalui akses berbasis peran.
- 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 1 |
❌ |
❌ |
✅ |
❌ |
❌ |
| Mengunggah data untuk pengindeksan 2 |
❌ |
❌ |
❌ |
✅ |
❌ |
| Menjalankan kueri pada indeks |
❌ |
❌ |
❌ |
✅ |
✅ |
| Mengambil dari pangkalan pengetahuan |
❌ |
❌ |
❌ |
✅ |
✅ |
| Lewati filter izin dengan akses baca tingkat lanjut (pratinjau) |
❌ |
❌ |
❌ |
✅ |
❌ |
1 Mencakup indeks, pengindeks, sumber data, set keterampilan, alias, peta sinonim, sesi debug, pangkalan pengetahuan, dan sumber pengetahuan. Pengindeks juga mendukung operasi menjalankan dan reset.
2 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:
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 |
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.
Masuk ke langganan Azure Anda.
az login
Buat penugasan peran dengan cakupan pada layanan pencarian. Berikan penerima tugas dan cakupan.
az role assignment create \
--assignee <assignee> \
--role "Reader" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:az role assignment create
Impor modul yang diperlukan dan sambungkan ke akun Azure Anda.
Import-Module Az.Resources
Connect-AzAccount
Buat penugasan peran dengan cakupan pada layanan pencarian. Contoh ini menggunakan nama masuk pengguna.
New-AzRoleAssignment -SignInName <email> `
-RoleDefinitionName "Reader" `
-Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:New-AzRoleAssignment
Buka shell perintah dan masuk ke langganan Azure Anda.
az login
Dapatkan token akses untuk Azure Resource Manager.
az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv
Kirim permintaan PUT untuk membuat penetapan peran dalam cakupan layanan pencarian. Atur principalType ke User, Group, atau ServicePrincipal untuk mencocokkan penerima tugas.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
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.
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.
Masuk ke langganan Azure Anda.
az login
Buat penugasan peran dengan cakupan pada layanan pencarian. Berikan penerima tugas dan cakupan.
az role assignment create \
--assignee <assignee> \
--role "Search Index Data Contributor" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:az role assignment create
(Opsional) Buat penetapan peran dengan cakupan pada sebuah indeks. Berikan penerima tugas dan cakupan.
az role assignment create \
--assignee <assignee> \
--role "Search Index Data Contributor" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Referensi:az role assignment create
Impor modul yang diperlukan dan sambungkan ke akun Azure Anda.
Import-Module Az.Resources
Connect-AzAccount
Buat penugasan peran dengan cakupan pada layanan pencarian. Contoh ini menggunakan nama masuk pengguna.
New-AzRoleAssignment -SignInName <email> `
-RoleDefinitionName "Search Index Data Contributor" `
-Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:New-AzRoleAssignment
(Opsional) Buat penetapan peran dengan cakupan pada sebuah indeks. Contoh ini menggunakan nama masuk pengguna.
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
Buka shell perintah dan masuk ke langganan Azure Anda.
az login
Dapatkan token akses untuk Azure Resource Manager.
az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv
Kirim permintaan PUT untuk membuat penetapan peran dalam cakupan layanan pencarian. Atur principalType ke User, Group, atau ServicePrincipal untuk mencocokkan penerima tugas.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
(Opsional) Kirim permintaan PUT untuk membuat penetapan peran dengan cakupan indeks.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
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.
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.
Masuk ke langganan Azure Anda.
az login
Buat penugasan peran dengan cakupan pada layanan pencarian. Berikan penerima tugas dan cakupan.
az role assignment create \
--assignee <assignee> \
--role "Search Index Data Reader" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:az role assignment create
(Opsional) Buat penetapan peran dengan cakupan pada sebuah indeks. Berikan penerima tugas dan cakupan.
az role assignment create \
--assignee <assignee> \
--role "Search Index Data Reader" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Referensi:az role assignment create
Impor modul yang diperlukan dan sambungkan ke akun Azure Anda.
Import-Module Az.Resources
Connect-AzAccount
Buat penugasan peran dengan cakupan pada layanan pencarian. Contoh ini menggunakan nama masuk pengguna.
New-AzRoleAssignment -SignInName <email> `
-RoleDefinitionName "Search Index Data Reader" `
-Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"
Referensi:New-AzRoleAssignment
(Opsional) Buat penetapan peran dengan cakupan pada sebuah indeks. Contoh ini menggunakan nama masuk pengguna.
New-AzRoleAssignment -SignInName <email> `
-RoleDefinitionName "Search Index Data Reader" `
-Scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Referensi:New-AzRoleAssignment
Buka shell perintah dan masuk ke langganan Azure Anda.
az login
Dapatkan token akses untuk Azure Resource Manager.
az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv
Kirim permintaan PUT untuk membuat penetapan peran dalam cakupan layanan pencarian. Atur principalType ke User, Group, atau ServicePrincipal untuk mencocokkan penerima tugas.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
(Opsional) Kirim permintaan PUT untuk membuat penetapan peran dengan cakupan indeks.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
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 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.
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 ini adalah contoh cara 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 ini contohnya.
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
Tambahkan dependensi yang diperlukan ke pom.xml Anda.
<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.
Saat ini, portal Azure tidak mendukung penetapan peran di tingkat indeks. Gunakan Azure CLI, PowerShell, atau REST API untuk menetapkan peran yang dilingkup ke satu indeks.
Masuk ke langganan Azure Anda.
az login
Buat penugasan peran yang terbatas pada satu indeks. Berikan penerima tugas dan cakupan tingkat indeks.
az role assignment create \
--assignee <assignee> \
--role "Search Index Data Contributor" \
--scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
Referensi:az role assignment create
Impor modul yang diperlukan dan sambungkan ke akun Azure Anda.
Import-Module Az.Resources
Connect-AzAccount
Buat penugasan peran yang terbatas pada satu indeks. Contoh ini menggunakan nama masuk pengguna.
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
Buka shell perintah dan masuk ke langganan Azure Anda.
az login
Dapatkan token akses untuk Azure Resource Manager.
az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv
Kirim permintaan PUT untuk membuat penugasan peran dengan cakupan pada satu indeks. Atur principalType ke User, Group, atau ServicePrincipal untuk mencocokkan penerima tugas.
PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
"principalId": "<principal-object-id>",
"principalType": "<principal-type>"
}
}
Referensi:Penetapan Peran - Buat
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": "List all indexes on the service and query them.",
"assignableScopes": [
"/subscriptions/<subscription>/resourceGroups/<resource-group>"
],
"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 Azure CLI memperlihatkan sintaks JSON untuk membuat peran kustom yang merupakan kloning Pembaca Data Indeks Pencarian, tetapi dengan kemampuan untuk mencantumkan semua indeks berdasarkan nama. Untuk instruksi langkah demi langkah tentang pembuatan peran kustom, lihat Membuat atau memperbarui Azure peran kustom menggunakan Azure CLI.
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/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
Simpan definisi peran berikut ke file JSON bernama search-index-data-explorer.json. Untuk Id, berikan GUID baru yang Anda hasilkan.
{
"Name": "Search Index Data Explorer",
"Id": "<role-definition-guid>",
"IsCustom": true,
"Description": "List all indexes on the service and query them.",
"Actions": [
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read"
],
"NotActions": [],
"DataActions": [
"Microsoft.Search/searchServices/indexes/documents/read"
],
"NotDataActions": [],
"AssignableScopes": [
"/subscriptions/<subscription>/resourceGroups/<resource-group>"
]
}
Buat peran kustom dengan meneruskan file JSON ke az role definition create.
az role definition create --role-definition @search-index-data-explorer.json
Referensi:az role definition create
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. Untuk instruksi langkah demi langkah tentang pembuatan peran kustom, lihat Membuat atau memperbarui Azure peran kustom menggunakan Azure PowerShell.
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/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
Simpan definisi peran berikut ke file JSON bernama search-index-data-explorer.json. Untuk Id, berikan GUID baru yang Anda hasilkan.
{
"Name": "Search Index Data Explorer",
"Id": "<role-definition-guid>",
"IsCustom": true,
"Description": "List all indexes on the service and query them.",
"Actions": [
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read"
],
"NotActions": [],
"DataActions": [
"Microsoft.Search/searchServices/indexes/documents/read"
],
"NotDataActions": [],
"AssignableScopes": [
"/subscriptions/<subscription>/resourceGroups/<resource-group>"
]
}
Buat peran kustom dengan meneruskan file JSON ke New-AzRoleDefinition.
New-AzRoleDefinition -InputFile "search-index-data-explorer.json"
Referensi:New-AzRoleDefinition
Contoh REST API menunjukkan sintaks JSON untuk membuat peran kustom yang merupakan kloning dari Search Index Data Reader, tetapi dengan kemampuan untuk mendaftar semua indeks berdasarkan nama. Untuk instruksi langkah demi langkah tentang pembuatan peran kustom, lihat Membuat atau memperbarui Azure peran kustom menggunakan REST API.
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/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
Buat peran kustom dengan mengirim permintaan berikut ke titik akhir definisi peran.
PUT https://management.azure.com/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/<role-definition-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
{
"properties": {
"roleName": "Search Index Data Explorer",
"description": "List all indexes on the service and query them.",
"type": "CustomRole",
"permissions": [
{
"actions": [
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read"
],
"notActions": [],
"dataActions": [
"Microsoft.Search/searchServices/indexes/documents/read"
],
"notDataActions": []
}
],
"assignableScopes": [
"/subscriptions/<subscription>/resourceGroups/<resource-group>"
]
}
}
Referensi:Definisi Peran - Buat Atau Perbarui
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 diterapkan kebijakan.
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 (pratinjau) untuk menyelidiki.
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: