Mulai cepat: Pencarian teks dengan menggunakan REST
REST API di Azure AI Search menyediakan akses terprogram ke semua kemampuannya, termasuk fitur pratinjau, dan merupakan cara mudah untuk mempelajari cara kerja fitur. Dalam mulai cepat ini, pelajari cara memanggil REST API Pencarian untuk membuat, memuat, dan mengkueri indeks pencarian di Azure AI Search.
Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.
Prasyarat
- Visual Studio Code dengan klien REST.
- Pencarian Azure AI. Buat atau temukan sumber daya Azure AI Search yang sudah ada di bawah langganan Anda saat ini. Anda dapat menggunakan layanan gratis untuk mulai cepat ini.
Mengunduh file
Unduh sampel REST dari GitHub untuk mengirim permintaan dalam mulai cepat ini. Untuk informasi selengkapnya, lihat Mengunduh file dari GitHub.
Anda juga dapat memulai file baru di sistem lokal Anda dan membuat permintaan secara manual dengan menggunakan instruksi dalam artikel ini.
Menyalin kunci layanan pencarian dan URL
Panggilan REST memerlukan titik akhir layanan pencarian dan kunci API pada setiap permintaan. Anda bisa mendapatkan nilai-nilai ini dari portal Azure.
Masuk ke portal Azure. Kemudian buka halaman Gambaran Umum layanan pencarian dan salin URL. Contoh titik akhir mungkin terlihat seperti
https://mydemo.search.windows.net.Pilih Pengaturan> Keys lalu salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.
Menyiapkan Visual Studio Code
Jika Anda tidak terbiasa dengan klien REST untuk Visual Studio Code, bagian ini menyertakan penyiapan sehingga Anda dapat menyelesaikan tugas dalam mulai cepat ini.
Mulai Visual Studio Code dan pilih petak ekstensi .
Cari klien REST dan pilih Instal.
Buka atau buat file baru bernama dengan
.restekstensi file atau.http.Tempelkan dalam contoh berikut. Ganti URL dasar dan kunci API dengan nilai yang Anda salin sebelumnya.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2023-11-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Pilih Kirim Permintaan. Respons akan muncul di panel yang berdekatan. Jika Anda memiliki indeks yang sudah ada, indeks tersebut akan dicantumkan. Jika tidak, daftar kosong. Jika kode HTTP adalah
200 OK, Anda siap untuk langkah-langkah berikutnya.
Poin utama:
- Parameter ditentukan dengan menggunakan awalan
@. ###menunjuk panggilan REST. Baris berikutnya berisi permintaan, yang harus menyertakanHTTP/1.1.Send requestakan muncul di atas permintaan.
- Parameter ditentukan dengan menggunakan awalan
Buat indeks
Tambahkan permintaan kedua ke file Anda .rest . Buat Indeks (REST) membuat indeks pencarian dan menyiapkan struktur data fisik di layanan pencarian Anda.
Tempelkan dalam contoh berikut untuk membuat
hotels-quickstartindeks di layanan pencarian Anda.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] }Pilih Kirim Permintaan. Anda harus memiliki
HTTP/1.1 201 Createdrespons dan isi respons harus menyertakan representasi JSON dari skema indeks.Jika Anda mendapatkan
Header name must be a valid HTTP token ["{"]kesalahan, pastikan ada baris kosong antaraapi-keydan isi permintaan. Jika Anda mendapatkan HTTP 504, verifikasi bahwa URL menentukan HTTPS. Jika Anda melihat HTTP 400 atau 404, periksa isi permintaan untuk memverifikasi tidak ada kesalahan salin-tempel. HTTP 403 biasanya menunjukkan masalah dengan kunci API. Ini adalah kunci yang tidak valid atau masalah sintaks dengan bagaimana kunci API ditentukan.Anda sekarang memiliki beberapa permintaan dalam file Anda. Ingat bahwa
###memulai permintaan baru dan setiap permintaan berjalan secara independen.
Tentang definisi indeks
Dalam skema indeks, kumpulan bidang menentukan struktur dokumen. Setiap dokumen yang Anda unggah harus memiliki bidang ini. Setiap bidang harus ditetapkan ke jenis data Model Data Entitas (EDM). Bidang string digunakan dalam pencarian teks lengkap. Jika Anda ingin data numerik dapat dicari, pastikan jenis datanya adalah Edm.String. Jenis data lain seperti Edm.Int32 dapat difilter, dapat diurutkan, dapat difaset, dan dapat diambil tetapi tidak dapat dicari teks lengkap.
Atribut pada bidang menentukan tindakan yang diizinkan. REST API memungkinkan banyak tindakan secara default. Misalnya, semua string dapat dicari dan diambil secara default. Untuk REST API, Anda mungkin hanya memiliki atribut jika Anda perlu menonaktifkan perilaku.
{
"name": "hotels-quickstart",
"fields": [
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
{"name": "Address", "type": "Edm.ComplexType",
"fields": [
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
]
}
]
}
Muat dokumen
Membuat dan memuat indeks adalah langkah-langkah terpisah. Di Pencarian Azure AI, indeks berisi semua data dan kueri yang dapat dicari yang dijalankan pada layanan pencarian. Untuk panggilan REST, data disediakan sebagai dokumen JSON. Gunakan Dokumen- Indeks REST API untuk tugas ini.
URI diperluas untuk menyertakan docs koleksi dan index operasi.
Tempelkan contoh berikut untuk mengunggah dokumen JSON ke indeks pencarian.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Secret Point Motel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Twin Dome Motel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Triple Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }Pilih Kirim Permintaan. Dalam beberapa detik, Anda akan melihat respons HTTP 201 di panel yang berdekatan.
Jika Anda mendapatkan 207, setidaknya satu dokumen gagal diunggah. Jika Anda mendapatkan 404, Anda memiliki kesalahan sintaks di header atau isi permintaan. Verifikasi bahwa Anda mengubah titik akhir untuk menyertakan
/docs/index.
Jalankan Kueri
Setelah dokumen dimuat, Anda dapat mengeluarkan kueri terhadapnya dengan menggunakan Dokumen - Pos Pencarian (REST).
URI diperluas untuk menyertakan ekspresi kueri, yang ditentukan dengan menggunakan /docs/search operator.
Tempelkan dalam contoh berikut untuk mengkueri indeks pencarian. Lalu pilih Kirim permintaan. Permintaan pencarian teks selalu menyertakan
searchparameter. Contoh ini mencakup parameter opsionalsearchFieldsyang membatasi pencarian teks ke bidang tertentu.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }Tinjau respons di panel yang berdekatan. Anda harus memiliki hitungan yang menunjukkan jumlah kecocokan yang ditemukan dalam indeks, skor pencarian yang menunjukkan relevansi, dan nilai untuk setiap bidang yang
selecttercantum dalam pernyataan.{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
Dapatkan properti indeks
Anda juga bisa menggunakan Dapatkan Statistik untuk mengkueri jumlah dokumen dan ukuran indeks.
Tempelkan dalam contoh berikut untuk mengkueri indeks pencarian. Lalu pilih Kirim permintaan.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}Tinjau responsnya. Operasi ini adalah cara mudah untuk mendapatkan detail tentang penyimpanan indeks.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
Membersihkan sumber daya
Saat bekerja dengan langganan Anda sendiri, sebaiknya identifikasi apakah Anda masih membutuhkan sumber daya yang Anda buat di akhir proyek. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.
Anda dapat menemukan dan mengelola sumber daya di portal dengan menggunakan tautan Semua sumber daya atau Grup sumber daya di panel paling kiri.
Anda juga dapat mencoba perintah ini DELETE :
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Langkah selanjutnya
Sekarang setelah Anda terbiasa dengan klien REST dan melakukan panggilan REST ke Azure AI Search, coba mulai cepat lain yang menunjukkan dukungan vektor.