Menyambungkan ke Pencarian Azure AI menggunakan kunci

Azure AI Search mendukung autentikasi tanpa kunci dan berbasis kunci untuk koneksi ke layanan pencarian Anda. Kunci API adalah string unik yang terdiri dari 52 angka dan huruf yang dihasilkan secara acak. Dalam kode sumber, Anda dapat menentukannya sebagai variabel lingkungan atau sebagai pengaturan aplikasi di proyek Anda, lalu mereferensikan variabel pada permintaan.

Penting

Saat Anda membuat layanan pencarian, autentikasi berbasis kunci adalah default, tetapi ini bukan opsi yang paling aman. Kami menyarankan agar Anda menggantinya dengan akses berbasis peran.

Diaktifkan secara default

Autentikasi berbasis kunci adalah default pada layanan pencarian baru. Permintaan yang dibuat ke titik akhir layanan pencarian diterima jika permintaan dan kunci API valid, dan layanan pencarian Anda dikonfigurasi untuk mengizinkan kunci API berdasarkan permintaan. Di portal Azure, autentikasi ditentukan pada halaman Kunci di bawah Pengaturan. Baik kunci API atau Keduanya memberikan dukungan utama.

Jenis kunci API

Ada dua jenis kunci yang digunakan untuk mengautentikasi permintaan:

Jenis	Tingkat izin	Maksimum	Cara pembuatan
Admin	Akses penuh (baca-tulis) untuk semua operasi konten	2 1	Dua kunci admin, disebut sebagai kunci primer dan sekunder dalam portal Azure, dihasilkan ketika layanan dibuat dan dapat diregenerasi secara individual sesuai permintaan.
Kueri	Akses baca-saja, tercakup ke kumpulan dokumen indeks pencarian	50	Satu kunci kueri dihasilkan dengan layanan. Lainnya dapat dibuat sesuai permintaan oleh administrator layanan pencarian.

¹ Memiliki dua memungkinkan Anda untuk menggulirkan satu kunci saat menggunakan kunci kedua untuk akses berkelanjutan ke layanan.

Secara visual, tidak ada perbedaan antara kunci admin atau kunci kueri. Kedua kunci adalah string yang terdiri dari 52 karakter alfa-numerik yang dihasilkan secara acak. Jika Anda kehilangan jejak jenis kunci apa yang ditentukan dalam aplikasi, Anda dapat memeriksa nilai kunci di portal Azure.

Menggunakan kunci API pada koneksi

Kunci API digunakan untuk permintaan sarana data (konten), seperti membuat atau mengakses indeks atau, permintaan lain yang diwakili dalam REST API Pencarian.

Anda dapat menggunakan kunci API atau peran Azure untuk permintaan sarana manajemen (layanan). Saat Anda menggunakan kunci API:

• Kunci admin digunakan untuk membuat, memodifikasi, atau menghapus objek. Kunci admin juga digunakan untuk MENDAPATKAN definisi objek dan informasi sistem.
• Kunci kueri biasanya didistribusikan ke aplikasi klien yang mengeluarkan kueri.

REST API

Cara kunci API digunakan dalam panggilan REST:

Atur kunci admin di header permintaan. Anda tidak dapat meneruskan kunci admin pada URI atau di isi permintaan. Kunci admin digunakan untuk operasi create-read-update-delete dan pada permintaan yang dikeluarkan untuk layanan pencarian itu sendiri, seperti Indeks LIST atau Statistik Layanan GET.

Berikut adalah contoh penggunaan kunci API admin pada permintaan buat indeks:

HTTP

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Atur kunci kueri di header permintaan untuk POST, atau di URI untuk GET. Kunci kueri digunakan untuk operasi yang menargetkan index/docs koleksi: Dokumen Pencarian, Lengkapi Otomatis, Sarankan, atau DOKUMEN GET.

Berikut adalah contoh penggunaan kunci API kueri pada permintaan Dokumen Pencarian (GET):

HTTP

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

Catatan

Meneruskan data sensitif seperti api-key dalam permintaan URI dianggap sebagai praktik keamanan yang buruk. Untuk alasan ini, Azure AI Search hanya menerima kunci kueri sebagai api-key dalam string kueri. Sebagai aturan umum, sebaiknya lewati api-key sebagai header permintaan Anda.

PowerShell

Cara kunci API digunakan di PowerShell:

Atur kunci API di header permintaan menggunakan sintaks berikut:

Azure PowerShell

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Contoh skrip yang menunjukkan penggunaan kunci API untuk berbagai operasi dapat ditemukan di Mulai Cepat: Membuat indeks Pencarian Azure AI di PowerShell menggunakan REST API.

Portal

Bagaimana kunci API digunakan dalam portal Azure:

Autentikasi kunci berlaku untuk operasi bidang data seperti pengindeksan dan kueri. Status diaktifkan secara default. Namun, jika Anda menonaktifkan kunci API dan menyiapkan penetapan peran, portal Azure menggunakan penetapan peran sebagai gantinya.

Izin untuk melihat atau mengelola kunci API

Izin untuk melihat dan mengelola kunci API disampaikan melalui penetapan peran. Anggota peran berikut dapat melihat dan meregenerasi kunci:

• Pemilik
• Kontributor
• Kontributor Layanan Pencarian
• Administrator dan rekan administrator (klasik)

Peran berikut tidak memiliki akses ke kunci API:

• Pembaca
• Kontributor Data Indeks Pencarian
• Pembaca Data Indeks Pencarian

Temukan kunci yang ada

Anda dapat melihat dan mengelola kunci API di portal Microsoft Azure, atau melalui PowerShell, Azure CLI, atau REST API.

Portal

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

2. Di bawah Pengaturan, pilih Kunci untuk menampilkan kunci admin dan kueri.

PowerShell

1. Az.Search Instal modul:

   Azure PowerShell

   Install-Module Az.Search
   

2. Mengembalikan kunci admin:

   Azure PowerShell

   Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

3. Mengembalikan kunci kueri:

   Azure PowerShell

   Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

Azure CLI

Gunakan perintah berikut untuk mengembalikan kunci API admin dan kueri, masing-masing:

Azure CLI

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

REST API

Gunakan Kunci Admin Daftar atau Kunci Kueri Daftar di REST API Manajemen untuk mengembalikan kunci API.

Anda harus memiliki penetapan peran yang valid untuk mengembalikan atau memperbarui kunci API. Lihat Mengelola layanan Pencarian Azure AI Anda dengan REST API untuk panduan tentang persyaratan peran rapat menggunakan REST API.

rest

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Membuat kunci kueri

Kunci kueri digunakan untuk akses baca-saja ke dokumen di dalam indeks untuk operasi yang menargetkan kumpulan dokumen. Kueri pencarian, filter, dan saran adalah semua operasi yang menggunakan kunci kueri. Setiap operasi baca-saja yang mengembalikan data sistem atau definisi objek, seperti definisi indeks atau status pengindeks, membutuhkan kunci admin.

Membatasi akses dan operasi di aplikasi klien sangat penting untuk melindungi aset pencarian pada layanan Anda. Selalu gunakan kunci kueri, ketimbang kunci admin, untuk setiap kueri yang berasal dari aplikasi klien.

Portal

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

2. Di bawah Pengaturan, pilih Kunci untuk melihat kunci API.

3. Di bawah Kelola kunci kueri, gunakan kunci kueri yang sudah dibuat untuk layanan Anda, atau buat kunci kueri baru. Kunci kueri default tidak dinamai, tetapi kunci kueri lain yang dihasilkan dapat dinamai untuk pengelolaan.

   

PowerShell

Contoh skrip yang menunjukkan penggunaan kunci API dapat ditemukan di Membuat atau menghapus kunci kueri.

Azure CLI

Contoh skrip yang memperlihatkan penggunaan kunci kueri dapat ditemukan di Membuat atau menghapus kunci kueri.

REST API

Gunakan Buat Kunci Kueri di REST API Manajemen.

Anda harus memiliki penetapan peran yang valid untuk membuat atau mengelola kunci API. Lihat Mengelola layanan Pencarian Azure AI Anda dengan REST API untuk panduan tentang persyaratan peran rapat menggunakan REST API.

rest

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Meregenerasi kunci admin

Dua kunci admin dibuat untuk setiap layanan sehingga Anda dapat memutar kunci primer saat menggunakan kunci sekunder untuk kelangsungan bisnis.

1. Di bawah Pengaturan, pilih Kunci, lalu salin kunci sekunder.

2. Untuk semua aplikasi, perbarui pengaturan kunci API untuk memakai kunci sekunder.

3. Regenerasi kunci primer.

4. Perbarui semua aplikasi untuk menggunakan kunci primer baru.

Jika Anda meregenerasi kedua kunci pada saat yang sama secara tidak sengaja, semua permintaan klien yang menggunakan kunci tersebut akan gagal dengan HTTP 403 Terlarang. Namun, konten tidak dihapus dan Anda tidak dikunci secara permanen.

Anda masih dapat mengakses layanan melalui portal Azure atau secara terprogram. Fungsi manajemen beroperasi melalui ID langganan bukan kunci API layanan, dan dengan demikian masih tersedia meskipun kunci API Anda tidak.

Setelah Anda membuat kunci baru melalui portal atau lapisan manajemen, akses dipulihkan ke konten Anda (indeks, pengindeks, sumber data, peta sinonim) setelah Anda memberikan kunci tersebut pada permintaan.

Kunci API aman

Gunakan penetapan peran untuk membatasi akses ke kunci API.

Tidak dimungkinkan untuk menggunakan enkripsi kunci yang dikelola pelanggan untuk mengenkripsi kunci API. Hanya data sensitif dalam layanan pencarian itu sendiri (misalnya, konten indeks atau string koneksi dalam definisi objek sumber data) yang dapat dienkripsi CMK.

1. Buka halaman layanan pencarian Anda di portal Azure.

2. Di panel navigasi kiri, pilih Kontrol akses (IAM), lalu pilih tab Penetapan peran.

3. Di filter Peran, pilih peran yang memiliki izin untuk melihat atau mengelola kunci (Pemilik, Kontributor, Kontributor Layanan Pencarian). Perwakilan keamanan yang dihasilkan yang ditetapkan untuk peran tersebut memiliki izin utama pada layanan pencarian Anda.

4. Sebagai tindakan pencegahan, periksa juga tab Administrator klasik untuk menentukan apakah administrator dan rekan administrator memiliki akses.

Praktik terbaik

• Untuk beban kerja produksi, beralihlah ke ID Microsoft Entra dan akses berbasis peran. Atau, jika Anda ingin terus menggunakan kunci API, pastikan untuk selalu memantau siapa yang memiliki akses ke kunci API Anda dan meregenerasi kunci API pada irama biasa.

• Hanya gunakan kunci API jika pengungkapan data bukan risiko (misalnya, saat menggunakan data sampel) dan jika Anda beroperasi di belakang firewall. Paparan kunci API adalah risiko bagi data dan penggunaan layanan pencarian Anda yang tidak sah.

• Jika Anda menggunakan kunci API, simpan dengan aman di tempat lain, seperti di Azure Key Vault. Jangan sertakan kunci API langsung dalam kode Anda, dan jangan pernah mempostingnya secara publik.

• Selalu periksa kode, sampel, dan materi pelatihan sebelum menerbitkan untuk memastikan Anda tidak secara tidak sengaja mengekspos kunci API.

Lihat juga

• Keamanan di Azure AI Search
• Kontrol akses berbasis peran Azure di Azure AI Search
• Mengelola menggunakan PowerShell