Referensi Azure AI Search REST API
Azure AI Search (sebelumnya dikenal sebagai Azure Cognitive Search) adalah layanan pencarian cloud terkelola sepenuhnya yang menyediakan pengambilan informasi atas konten milik pengguna.
DATA plane REST API digunakan untuk mengindeks dan mengkueri alur kerja, dan didokumenkan di bagian ini.
Operasi sarana kontrol diakses melalui REST API Manajemen terpisah.
Dokumen API versi
Dokumen REST API sekarang diberi versi. Saat Anda membuka halaman referensi API, pemilih versi muncul di atas daftar isi. Pastikan referensi API berasal dari folder Bidang Data Referensi>.
Konsep utama
Azure AI Search memiliki konsep layanan pencarian, indeks, dokumen, pengindeks, sumber data, set keterampilan, dan peta sinonim.
- Layanan pencarian menghosting indeks, pengindeks, sumber data, set keterampilan, dan peta sinonim sebagai objek tingkat atas.
- Indeks pencarian menyediakan penyimpanan dokumen pencarian yang persisten. Search dokumen adalah data Anda, diartikulasikan sebagai kumpulan bidang, dimuat dari sumber eksternal dan didorong ke indeks untuk membuatnya dapat dicari.
- Pengindeks pencarian menambahkan otomatisasi, membaca data dalam format asli dan menserialisasikannya ke JSON.
- Pengindeks memiliki sumber data dan menunjuk ke indeks.
- Pengindeks mungkin juga memiliki set keterampilan yang menambahkan pengayaan AI dan vektorisasi terintegrasi ke alur pengindeksan. Set keterampilan selalu melekat pada pengindeks. Mereka memanggil pembelajaran mesin untuk mengekstrak atau memotong teks, mem-vektorisasi konten, menyimpulkan fitur, atau menambahkan struktur ke konten sehingga dapat diindeks oleh layanan pencarian.
Sama sekali, Anda dapat membuat objek berikut pada layanan pencarian:
| Objek | Deskripsi |
|---|---|
| Sumber data | Koneksi sumber data yang digunakan oleh pengindeks untuk mengambil dan menyegarkan dokumen untuk pengindeksan. Sumber data memiliki type. Anda dapat menggunakan koneksi yang disediakan Microsoft untuk Azure, atau konektor pihak ketiga melalui mitra. Lihat Galeri sumber data untuk daftar lengkapnya. |
| Dokumen | Secara konseptual, dokumen adalah entitas dalam indeks Anda. Memetakan konsep ini ke database yang lebih akrab setara: indeks pencarian sama dengan tabel, dan dokumen kira-kira setara dengan baris dalam tabel. Dokumen hanya ada dalam indeks, dan hanya diambil melalui kueri yang menargetkan kumpulan dokumen (/docs) indeks. Semua operasi yang dilakukan pada koleksi seperti mengunggah, menggabungkan, menghapus, atau mengkueri dokumen terjadi dalam konteks indeks tunggal, sehingga operasi dokumen format URL akan selalu disertakan /indexes/[index name]/docs untuk nama indeks tertentu. |
| Indeks | Indeks disimpan di layanan pencarian Anda dan diisi dengan dokumen JSON yang diindeks dan diberi token untuk pengambilan informasi. Kumpulan bidang indeks menentukan struktur dokumen pencarian. Bidang memiliki nama, jenis data, dan atribut yang menentukan cara penggunaannya. Misalnya, searchable bidang digunakan dalam pencarian teks lengkap, dan dengan demikian ditokenisasi selama pengindeksan. Indeks juga mendefinisikan konstruksi lain, seperti profil penilaian untuk penyetelan relevansi, pemberi saran, konfigurasi semantik, dan penganalisis kustom. |
| Pengindeks | Pengindeks menyediakan otomatisasi pengindeksan. Pengindeks tersambung ke sumber data, membaca data, dan meneruskannya ke mesin pencari untuk diindeks ke indeks pencarian target. Pengindeks membaca dari sumber eksternal menggunakan informasi koneksi di sumber data, dan membuat serialisasi data masuk ke dalam dokumen pencarian JSON. Selain sumber data, pengindeks juga memerlukan indeks. Indeks menentukan bidang dan atribut dokumen pencarian. |
| Keterampilan | Skillset menambahkan langkah-langkah pemrosesan eksternal untuk eksekusi pengindeks, dan biasanya digunakan untuk menambahkan AI atau model pembelajaran mendalam untuk menganalisis atau mengubah konten agar dapat dicari dalam indeks. Konten skillset adalah satu atau beberapa keterampilan, yang dapat menjadi keterampilan bawaan yang dibuat oleh Microsoft, keterampilan kustom, atau kombinasi keduanya. Keterampilan bawaan ada untuk analisis gambar, termasuk OCR, dan pemrosesan bahasa alami. Contoh lain dari keterampilan bawaan termasuk pengenalan entitas, ekstraksi frasa kunci, pemotongan teks menjadi halaman logis, antara lain. Skillset adalah objek mandiri tingkat tinggi yang ada pada tingkat yang setara dengan indeks, pengindeks, dan sumber data, tetapi hanya beroperasi dalam pemrosesan pengindeks. Sebagai objek tingkat tinggi, Anda dapat merancang set keterampilan sekali, lalu mereferensikannya dalam beberapa pengindeks. |
| Peta sinonim | Peta sinonim adalah objek tingkat layanan yang berisi sinonim yang ditentukan pengguna. Objek ini dipertahankan secara independen dari indeks pencarian. Setelah diunggah, Anda dapat mengarahkan bidang yang dapat dicari ke peta sinonim (satu per bidang). |
Izin dan kontrol akses
Anda dapat menggunakan autentikasi berbasis kunci atau berbasis peran melalui Microsoft Entra ID.
Autentikasi berbasis kunci bergantung pada kunci API yang dihasilkan untuk layanan pencarian. Memiliki kunci yang valid akan membangun kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan yang menanganinya. Anda dapat menggunakan kunci API Admin untuk operasi baca-tulis atau kunci API Kueri untuk akses baca ke kumpulan dokumen indeks pencarian.
Microsoft Entra ID autentikasi dan kontrol akses berbasis peran mengharuskan Anda memiliki penyewa yang mapan di Microsoft Entra ID, dengan prinsip keamanan dan penetapan peran. Anggota peran berikut memiliki akses sarana data. Anda dapat membuat peran kustom jika peran bawaan tidak mencukupi.
Peran Access Kontributor Layanan Pencarian Akses ke objek, tetapi tidak ada akses ke konten indeks. Peran ini tidak dapat mengkueri indeks pencarian atau menambahkan, menghapus, atau memperbarui dokumen dalam indeks pencarian. Peran ini untuk administrator yang perlu mengelola objek, tetapi tanpa kemampuan untuk melihat atau mengakses data objek. Kontributor Indeks Data Search Akses baca-tulis ke konten indeks. Peran ini untuk pengembang atau pemilik indeks yang perlu mengimpor, me-refresh, atau mengkueri koleksi dokumen indeks. Search Pembaca Indeks Data Akses baca ke konten indeks. Peran ini untuk aplikasi dan pengguna yang menjalankan kueri.
Saat menggunakan peran pada koneksi, aplikasi klien Anda menyajikan token pembawa di header otorisasi. Lihat Mengotorisasi akses ke aplikasi pencarian menggunakan Microsoft Entra ID untuk bantuan dalam menyiapkannya.
Anda dapat menonaktifkan autentikasi berbasis kunci atau autentikasi berbasis peran. Jika Anda menonaktifkan autentikasi berbasis peran, beberapa peran bawaan masih akan memiliki akses. Lihat autentikasi Microsoft Entra ID dan kontrol akses berbasis peran untuk azure AI Search untuk detailnya.
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).
URI permintaan harus menyertakan versi api. 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-30Header permintaan harus menyertakan kunci api atau token pembawa untuk koneksi yang diautentikasi. Secara opsional, Anda dapat mengatur header Terima HTTP. Jika header jenis konten tidak diatur, defaultnya diasumsikan sebagai
application/json.