Koneksi ke Azure AI Search menggunakan autentikasi kunci

Artikel
04/25/2024

Azure AI Search menawarkan autentikasi berbasis kunci yang dapat Anda gunakan pada koneksi ke layanan pencarian Anda. Kunci API adalah string unik yang terdiri dari 52 angka dan huruf yang dihasilkan secara acak. Permintaan yang dibuat ke titik akhir layanan pencarian diterima jika permintaan dan kunci API valid.

Autentikasi berbasis kunci adalah default. Anda dapat menonaktifkannya jika Anda memilih untuk autentikasi berbasis peran.

Catatan

Catatan singkat tentang terminologi kunci . Kunci API adalah GUID yang digunakan untuk autentikasi. Istilah terpisah, kunci dokumen adalah string unik dalam konten terindeks Anda yang secara unik mengidentifikasi dokumen dalam indeks pencarian.

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 ¹	Dua kunci admin, yang disebut sebagai kunci primer dan sekunder di portal, 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, Anda dapat memeriksa nilai kunci di portal.

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. Setelah pembuatan layanan, kunci API adalah satu-satunya mekanisme autentikasi untuk operasi sarana data, tetapi Anda dapat mengganti atau melengkapi autentikasi kunci dengan peran Azure jika Anda tidak dapat menggunakan kunci yang dikodekan secara permanen dalam kode Anda.

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.

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:

### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-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):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2023-11-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.

Cara kunci API digunakan di PowerShell:

Atur kunci API di header permintaan menggunakan sintaks berikut:

$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.

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.

Masuk ke portal Azure dan temukan layanan pencarian Anda.
Di bawah Pengaturan, pilih Kunci untuk menampilkan kunci admin dan kueri.

Az.Search Instal modul:
```
Install-Module Az.Search
```

Mengembalikan kunci admin:

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

Mengembalikan kunci kueri:

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

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

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

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

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.

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.

Masuk ke portal Azure dan temukan layanan pencarian Anda.
Di bawah Pengaturan, pilih Kunci untuk melihat kunci API.
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.

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.

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.

Di bawah Pengaturan, pilih Kunci, lalu salin kunci sekunder.
Untuk semua aplikasi, perbarui pengaturan kunci API untuk memakai kunci sekunder.
Regenerasi kunci primer.
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 bisa mengakses layanan melalui portal 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.

Buka halaman layanan pencarian Anda di portal Azure.
Di panel navigasi kiri, pilih Kontrol akses (IAM), lalu pilih tab Penetapan peran.
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.
Sebagai tindakan pencegahan, periksa juga tab Administrator klasik untuk menentukan apakah administrator dan rekan administrator memiliki akses.

Praktik terbaik

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.
Selalu periksa kode, sampel, dan materi pelatihan sebelum menerbitkan untuk memastikan Anda tidak meninggalkan kunci API yang valid.
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.