Menggunakan kunci API untuk autentikasi Azure Cognitive Search

Cognitive Search menggunakan autentikasi berbasis kunci sebagai metodologi autentikasi utamanya. Untuk permintaan masuk ke titik akhir layanan pencarian, seperti permintaan yang membuat atau mengkueri indeks, kunci API adalah satu-satunya opsi autentikasi yang tersedia secara umum yang Anda miliki. Beberapa skenario permintaan keluar, terutama yang melibatkan pengindeks, dapat menggunakan identitas dan peran Azure Active Directory.

Catatan

Otorisasi untuk operasi bidang data menggunakan kontrol akses berbasis peran Azure (RBAC) sekarang dalam pratinjau. Anda dapat menggunakan kemampuan pratinjau ini untuk melengkapi atau mengganti kunci API pada permintaan indeks pencarian.

Kunci API dihasilkan saat layanan dibuat. Meneruskan kunci API yang valid pada permintaan dianggap sebagai bukti bahwa permintaan tersebut berasal dari klien yang sah. Ada dua jenis kunci. Kunci admin menyampaikan izin tulis pada layanan dan juga memberikan hak untuk mengkueri informasi sistem. Kunci kueri menyampaikan izin baca dan dapat digunakan oleh aplikasi untuk mengkueri indeks tertentu.

Saat menghubungkan ke layanan pencarian, semua permintaan harus menyertakan kunci API yang dibuat secara khusus untuk layanan Anda.

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

Portal page, retrieve settings, keys section

Apa itu kunci API?

Kunci API adalah string unik yang terdiri dari angka dan huruf yang dihasilkan secara acak yang diteruskan di setiap permintaan ke layanan pencarian. Layanan akan menerima permintaan, jika permintaan dan kuncinya itu sendiri valid.

Dua tipe kunci digunakan untuk mengakses layanan pencarian Anda: admin (baca-tulis) dan kueri (baca-saja).

Kunci Deskripsi Batas
Admin Memberikan hak penuh untuk semua operasi, termasuk kemampuan untuk mengelola layanan, membuat dan menghapus indeks, pengindeks, serta sumber data.

Dua kunci admin, yang disebut sebagai kunci primer dan sekunder di portal, dihasilkan ketika layanan dibuat dan dapat diregenerasi secara individual sesuai permintaan. Memiliki dua kunci memungkinkan Anda untuk menggulirkan satu kunci saat menggunakan kunci kedua untuk akses berkelanjutan ke layanan.

Kunci admin hanya ditentukan di header permintaan HTTP. Anda tidak dapat menempatkan kunci API admin di URL.
Maksimum 2 per layanan
Kueri Memberikan akses baca-saja ke indeks dan dokumen, dan biasanya didistribusikan ke aplikasi klien yang mengeluarkan permintaan pencarian.

Kunci kueri dibuat sesuai permintaan.

Kunci kueri dapat ditentukan dalam header permintaan HTTP untuk operasi pencarian, saran, atau pencarian. Atau, Anda dapat meneruskan kunci kueri sebagai parameter pada URL. Bergantung pada bagaimana aplikasi klien Anda merumuskan permintaan, mungkin akan lebih mudah untuk meneruskan kunci sebagai parameter kueri:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
50 per layanan

Secara visual, tidak ada perbedaan antara kunci admin dan kunci kueri. Kedua kunci adalah string yang terdiri dari 32 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.

Catatan

Meneruskan data sensitif seperti api-key dalam permintaan URI dianggap sebagai praktik keamanan yang buruk. Untuk alasan ini, Azure Cognitive Search hanya menerima kunci kueri sebagai api-key di string kueri, dan Anda harus menghindari melakukannya kecuali konten indeks Anda harus tersedia untuk umum. Sebagai aturan umum, sebaiknya lewati api-key sebagai header permintaan Anda.

Temukan kunci yang ada

Anda dapat memperoleh kunci akses di portal atau melalui PowerShell, Azure CLI, atau REST API.

  1. Masuk ke portal Microsoft Azure.

  2. Mencantumkan layanan pencarian untuk langganan Anda.

  3. Pilih layanan dan pada halaman Gambaran Umum, klik Pengaturan>Kunci untuk menampilkan kunci admin dan kueri.

    Portal page, view settings, keys section

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.

  1. Masuk ke portal Microsoft Azure.

  2. Mencantumkan layanan pencarian untuk langganan Anda.

  3. Pilih layanan dan pada halaman Gambaran Umum, klik Pengaturan>Kunci.

  4. Klik Kelola kunci kueri.

  5. Gunakan kunci kueri yang sudah dibuat untuk layanan Anda, atau buat hingga 50 kunci kueri baru. Kunci kueri default tidak bernama, tetapi kunci kueri tambahan dapat diberi nama untuk pengelolaannya.

    Create or use a query key

Catatan

Contoh kode yang memperlihatkan penggunaan kunci kueri dapat ditemukan di DotNetHowTo.

Meregenerasi kunci admin

Dua kunci admin dibuat untuk setiap layanan agar Anda dapat memutar kunci utama, menggunakan kunci sekunder untuk kelangsungan bisnis.

  1. Di halaman Pengaturan>Kunci, 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 akan 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 tersedia.

Setelah Anda membuat kunci baru lewat portal atau lapisan manajemen, akses dipulihkan ke konten Anda (indeks, pengindeks, sumber data, peta sinonim) setelah Anda memiliki kunci baru dan menyediakan kunci tersebut berdasarkan permintaan.

Kunci API aman

Penetapan peran menentukan siapa saja yang dapat membaca dan mengelola kunci. Anggota peran berikut dapat melihat dan menghasilkan ulang kunci: Pemilik, Kontributor, Kontributor Layanan Pencarian. Peran Pembaca tidak memiliki akses ke kunci API.

Administrator langganan dapat melihat dan menghasilkan ulang semua kunci API. Sebagai pencegahan, tinjau tugas peran untuk memahami siapa yang memiliki akses ke kunci admin.

  1. Buka halaman layanan pencarian Anda di portal Azure.
  2. Di panel navigasi kiri, pilih Kontrol akses (IAM) , lalu pilih tab Penetapan peran.
  3. Atur Cakupan ke Sumber daya ini untuk melihat penetapan peran untuk layanan Anda.

Lihat juga