Azure Cognitive Search Service REST

Azure Cognitive Search adalah layanan pencarian cloud terkelola penuh yang memberikan pengalaman pencarian yang kaya atas konten milik pengguna. Salah satu cara untuk menambahkan kemampuan pencarian adalah melalui Rest API Pencarian, dengan operasi yang membuat dan mengelola indeks, memuat data, menerapkan fitur pencarian, menjalankan kueri, dan menangani hasil.

REST API Manajemen terpisah dapat digunakan untuk membuat atau memodifikasi layanan itu sendiri. Atau, Anda dapat menggunakan portal untuk banyak tugas manajemen layanan dan konten. Untuk memulai, lihat Membuat layanan pencarian di portal Azure.

Konsep Utama

Cognitive Search memiliki konsep layanan pencarian dan indeks dan dokumen:

  • Layanan pencarian berisi satu atau beberapa indeks.
  • Indeks menyediakan penyimpanan dokumen pencarian yang persisten.
  • Dokumen pencarian dimuat dari sumber eksternal dalam bentuk dokumen JSON dan didorong ke indeks untuk membuatnya dapat dicari.

Anda juga dapat membuat pengindeks untuk mengotomatiskan pengindeksan. Pengindeks memiliki sumber data dan menunjuk ke indeks. Secara opsional, mungkin juga memiliki set keterampilan yang menambahkan AI ke alur pengindeks.

Pengayaan AI adalah ekstensi pengindeks yang menambahkan transformasi pembelajaran mesin yang mengekstrak atau menghasilkan teks, atau menambahkan struktur ke konten sehingga dapat diindeks oleh layanan pencarian. Konstruksi yang mendorong pengayaan AI disebut set keterampilan. Selama penyerapan data, ini mendefinisikan urutan langkah-langkah yang mendeteksi, menyusun, atau mengubah konten yang tidak dapat diselimuti (misalnya, konten gambar).

Semua bersama-sama, ada lima jenis operasi yang dapat dijalankan terhadap layanan:

Operasi Deskripsi
Indeks Membuat, menghapus, memperbarui, atau mengonfigurasi indeks pencarian.
Dokumen Menambahkan, memperbarui, atau menghapus dokumen dalam indeks, mengkueri indeks, atau mencari dokumen tertentu berdasarkan ID.
Pengindeks Mengotomatiskan aspek operasi pengindeksan dengan mengonfigurasi sumber data dan pengindeks yang dapat Anda jadwalkan atau jalankan sesuai permintaan. Fitur ini didukung untuk sejumlah jenis sumber data terbatas di Azure.
Skillset Bagian dari beban kerja pengayaan AI , set keterampilan mendefinisikan serangkaian pemrosesan pengayaan yang mengekstrak atau membuat teks yang dapat dicari dari teks, file aplikasi, atau file gambar yang tidak terstruktur. Set keterampilan dipanggil oleh pengindeks.
Peta sinonim Peta sinonim adalah sumber daya tingkat layanan yang berisi sinonim yang ditentukan pengguna. Sumber daya ini dipertahankan secara independen dari indeks pencarian. Setelah diunggah, Anda dapat mengarahkan bidang yang dapat dicari ke peta sinonim (satu per bidang).

Memanggil API

API yang didokumenkan di bagian ini menyediakan akses ke operasi pada data pencarian, seperti pembuatan dan populasi indeks, pengunggahan dokumen, dan kueri. Saat memanggil API, ingatlah poin-poin berikut:

  • Permintaan harus dikeluarkan melalui HTTPS (pada port default 443).

  • Permintaan harus menyertakan versi api dalam URI. Nilai harus diatur ke versi yang didukung, diformat seperti yang ditunjukkan dalam contoh ini: GET https://[search service name].search.windows.net/indexes?api-version=2020-06-30

  • Header permintaan harus menyertakan kunci api yang dihasilkan untuk layanan pencarian yang Anda sediakan. Memiliki kunci yang valid akan membangun kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan yang menanganinya. Secara opsional, Anda dapat mengatur header Terima HTTP. Jika header tidak diatur, defaultnya diasumsikan sebagai application/json.

Autentikasi kunci

Setiap permintaan HTTP ke layanan pencarian Anda diautentikasi berdasarkan dua informasi: URL layanan pencarian dan kunci api yang memberikan bukti permintaan berasal dari entitas tepercaya. Ada dua jenis kunci api untuk tingkat operasi yang berbeda.

Kunci Deskripsi Batas
Admin Kunci admin memberikan hak penuh untuk semua operasi, termasuk kemampuan untuk mengelola layanan, mendapatkan status dan definisi objek, serta membuat dan menghapus indeks, pengindeks, dan sumber data.

Dua kunci api admin, yang disebut sebagai kunci primer dan sekunder di portal, secara otomatis 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 dalam header permintaan HTTP. Anda tidak dapat menempatkan kunci api admin di URL.
Maksimum 2 per layanan
Kueri Kunci kueri memberikan akses baca-saja ke konten dalam indeks (dokumen), dan biasanya didistribusikan ke aplikasi klien yang mengeluarkan permintaan pencarian.

Kunci kueri dibuat sesuai permintaan. Anda dapat membuatnya secara manual di portal atau secara terprogram melalui REST API Manajemen.

Kunci kueri dapat ditentukan di 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 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 dapat memeriksa nilai kunci di portal atau menggunakan MANAGEMENT REST API untuk mengembalikan nilai dan jenis kunci.

Catatan

Meneruskan data sensitif seperti api-key dalam permintaan URI dianggap sebagai praktik keamanan yang buruk. Untuk alasan ini, Azure Cognitive Search hanya akan menerima kunci kueri sebagai api-key dalam 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.

Authorization

Cognitive Search mendukung kontrol akses berbasis peran Azure (Azure RBAC) untuk administrasi layanan pencarian, melalui peran Pemilik, Kontributor, dan Pembaca.

Secara opsional, untuk solusi pencarian yang dapat menggunakan fitur pratinjau, Anda dapat menggunakan Azure RBAC untuk mengontrol akses ke indeks dan objek lain pada layanan pencarian. Pendekatan ini memerlukan layanan pencarian yang dikonfigurasi untuk Azure RBAC pada bidang data dan header otorisasi pada panggilan REST API yang diautentikasi menggunakan Azure Active Directory.

Lihat juga