Tutorial: Membuat aplikasi pencarian pertama Anda di Azure Cognitive Search menggunakan .NET SDK

Tutorial ini menunjukkan kepada Anda cara membuat aplikasi web yang meminta dan mengembalikan hasil dari indeks pencarian menggunakan Azure Cognitive Search dan Visual Studio.

Dalam tutorial ini, Anda akan mempelajari cara:

Menyiapkan lingkungan pengembangan
Struktur data model
Membuat halaman web untuk mengumpulkan input kueri dan menampilkan hasil
Menentukan metode pencarian
Menguji aplikasi

Anda juga akan mempelajari seberapa mudah panggilan pencarian. Pernyataan utama dalam kode dienkapsulasi dalam beberapa baris berikut:

var options = new SearchOptions()
{
    // The Select option specifies fields for the result set
    options.Select.Add("HotelName");
    options.Select.Add("Description");
};

var searchResult = await _searchClient.SearchAsync<Hotel>(model.searchText, options).ConfigureAwait(false);
model.resultList = searchResult.Value.GetResults().ToList();

Hanya satu panggilan yang mengkueri indeks pencarian dan mengembalikan hasil.

Gambaran Umum

Tutorial ini menggunakan indeks sampel hotel, yang dapat Anda buat dengan cepat di layanan pencarian Anda sendiri dengan menelusuri mulai cepat Impor data. Indeks berisi data hotel fiktif, tersedia sebagai sumber data bawaan di setiap layanan pencarian.

Pelajaran pertama dalam tutorial ini membuat struktur kueri dasar dan halaman pencarian, yang akan Anda tingkatkan dalam pelajaran berikutnya untuk menyertakan penomoran, faset, dan pengalaman fitur pelengkapan otomatis.

Versi kode yang sudah selesai dapat ditemukan dalam proyek berikut:

1-basic-search-page (GitHub)

Prasyarat

Membuat atau menemukan layanan pencarian yang sudah ada.
Indeks sampel (hotels-sample-index), yang dihosting di layanan pencarian Anda.
Visual Studio
Perpustakaan klien Azure.Cognitive.Search (versi 11)

Menginstal dan menjalankan proyek dari GitHub

Jika Anda ingin melompat ke aplikasi yang berfungsi, ikuti langkah-langkah di bawah ini untuk mengunduh dan menjalankan kode yang sudah selesai.

Temukan sampel di GitHub: Buat aplikasi pertama.
Di folder akar, pilih Kode, diikuti oleh Kloning atau Unduh ZIP untuk membuat salinan lokal privat proyek Anda.
Menggunakan Visual Studio, navigasikan ke, dan buka solusi untuk halaman pencarian dasar ("1-basic-search-page"), dan pilih Mulai tanpa penelusuran kesalahan (atau tekan F5) untuk membangun dan menjalankan program.
Ini adalah indeks hotel, jadi ketik beberapa kata yang mungkin Anda gunakan untuk mencari hotel (misalnya, "wifi", "view", "bar", "parking"). Periksa hasilnya.

Komponen penting untuk pencarian yang lebih canggih disertakan dalam aplikasi yang satu ini. Jika Anda baru menggunakan pengembangan pencarian, Anda dapat membuat ulang aplikasi ini selangkah demi selangkah untuk mempelajari alur kerja. Bagian berikut menunjukkan caranya.

Menyiapkan lingkungan pengembangan

Untuk membuat proyek ini dari awal, dan dengan demikian memperkuat konsep Azure Cognitive Search, mulailah dengan proyek Visual Studio.

Di Visual Studio, pilihProyekBaru>, lalu ASP.NET Core Web App (Model-View-Controller).
Beri nama proyek seperti "FirstSearchApp" dan atur lokasi. Pilih Berikutnya.
Terima default untuk kerangka kerja target, jenis autentikasi, dan HTTPS. Pilih Buat.
Menginstal pustaka klien. Di Alat> Pengelola >Paket NuGetKelola Paket NuGet untuk Solusi..., pilih Telusuri lalu cari "azure.search.documents". Instal Azure.Search.Documents (versi 11 atau yang lebih baru), menerima perjanjian lisensi dan dependensi.

Menginisialisasi Azure Cognitive Search

Dalam langkah ini, atur titik akhir dan kunci akses untuk menyambungkan ke layanan pencarian yang menyediakan indeks sampel hotel.

Buka appsettings.json dan ganti baris default dengan URL layanan pencarian (dalam format https://<service-name>.search.windows.net) dan kunci API admin atau kueri layanan pencarian Anda. Karena Anda tidak perlu membuat atau memperbarui indeks, Anda dapat menggunakan kunci kueri untuk tutorial ini.
```
{
    "SearchServiceUri": "<YOUR-SEARCH-SERVICE-URI>",
    "SearchServiceQueryApiKey": "<YOUR-SEARCH-SERVICE-API-KEY>"
}
```
Di Penjelajah Solusi, pilih file, dan di Properti, ubah pengaturan Salin ke Direktori Output menjadi Salin jika lebih baru.

Struktur data model

Model (kelas C#) digunakan untuk mengomunikasikan data antara klien (tampilan), server (pengontrol), dan juga cloud Azure menggunakan arsitektur MVC (model, tampilan, pengontrol). Biasanya, model-model ini mencerminkan struktur data yang sedang diakses.

Dalam langkah ini, Anda akan memodelkan struktur data indeks pencarian, serta string pencarian yang digunakan dalam komunikasi tampilan/pengontrol. Dalam indeks hotel, setiap hotel memiliki banyak kamar, dan setiap hotel memiliki alamat yang terdiri dari beberapa bagian. Sekaligus, representasi lengkap hotel adalah struktur data hierarkis dan berlapis. Anda memerlukan tiga kelas untuk membuat setiap komponen.

Set kelas Hotel, Alamat, dan Kamar dikenal sebagai jenis kompleks yang merupakan fitur penting Azure Cognitive Search. Jenis kompleks dapat berupa banyak tingkatan dalam kelas dan subkelas, dan memungkinkan struktur data yang jauh lebih kompleks untuk diwakili daripada menggunakan jenis sederhana (kelas yang hanya berisi anggota primitif).

Di Penjelajah Solusi, klik kanan Model>Tambahkan>Item Baru.

Pilih Kelas dan beri nama item Hotel.cs. Ganti semua konten Hotel.cs dengan kode berikut. Perhatikan anggota-anggota Alamat dan Ruangan dari kelas tersebut; bidang-bidang ini adalah kelas juga, sehingga Anda memerlukan model-model untuk masing-masingnya.

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Microsoft.Spatial;
using System;
using System.Text.Json.Serialization;

namespace FirstAzureSearchApp.Models
{
    public partial class Hotel
    {
        [SimpleField(IsFilterable = true, IsKey = true)]
        public string HotelId { get; set; }

        [SearchableField(IsSortable = true)]
        public string HotelName { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.EnLucene)]
        public string Description { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.FrLucene)]
        [JsonPropertyName("Description_fr")]
        public string DescriptionFr { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string Category { get; set; }

        [SearchableField(IsFilterable = true, IsFacetable = true)]
        public string[] Tags { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public bool? ParkingIncluded { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public DateTimeOffset? LastRenovationDate { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public double? Rating { get; set; }

        public Address Address { get; set; }

        [SimpleField(IsFilterable = true, IsSortable = true)]
        public GeographyPoint Location { get; set; }

        public Room[] Rooms { get; set; }
    }
}

Ulangi proses yang sama dalam membuat model untuk kelas Alamat , dengan menamai file Address.cs. Ganti konten dengan yang berikut ini.

using Azure.Search.Documents.Indexes;

namespace FirstAzureSearchApp.Models
{
    public partial class Address
    {
        [SearchableField]
        public string StreetAddress { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string City { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string StateProvince { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string PostalCode { get; set; }

        [SearchableField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
        public string Country { get; set; }
    }
}

Dan sekali lagi, ikuti proses yang sama untuk membuat kelas Kamar , menamai file Room.cs.

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using System.Text.Json.Serialization;

namespace FirstAzureSearchApp.Models
{
    public partial class Room
    {
        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.EnMicrosoft)]
        public string Description { get; set; }

        [SearchableField(AnalyzerName = LexicalAnalyzerName.Values.FrMicrosoft)]
        [JsonPropertyName("Description_fr")]
        public string DescriptionFr { get; set; }

        [SearchableField(IsFilterable = true, IsFacetable = true)]
        public string Type { get; set; }

        [SimpleField(IsFilterable = true, IsFacetable = true)]
        public double? BaseRate { get; set; }

        [SearchableField(IsFilterable = true, IsFacetable = true)]
        public string BedOptions { get; set; }

        [SimpleField(IsFilterable = true, IsFacetable = true)]
        public int SleepsCount { get; set; }

        [SimpleField(IsFilterable = true, IsFacetable = true)]
        public bool? SmokingAllowed { get; set; }

        [SearchableField(IsFilterable = true, IsFacetable = true)]
        public string[] Tags { get; set; }
    }
}

Model terakhir yang akan Anda buat dalam tutorial ini adalah kelas bernama SearchData dan mewakili input pengguna (searchText), dan output pencarian (resultList). Jenis output sangat penting, SearchResults<Hotel>, karena jenis ini sama persis dengan hasil dari pencarian, dan Anda perlu meneruskan referensi ini ke tampilan. Ganti templat default dengan kode berikut.
```
using Azure.Search.Documents.Models;

namespace FirstAzureSearchApp.Models
{
    public class SearchData
    {
        // The text to search for.
        public string searchText { get; set; }

        // The list of results.
        public SearchResults<Hotel> resultList;
    }
}
```

Membuat halaman web

Templat proyek dilengkapi dengan sejumlah tampilan klien yang terletak di folder Tampilan . Tampilan yang tepat tergantung pada versi Core .NET yang Anda gunakan (3.1 digunakan dalam sampel ini). Untuk tutorial ini, Anda akan memodifikasi Index.cshtml untuk menyertakan elemen halaman pencarian.

Hapus konten Index.cshtml secara keseluruhan, dan bangun ulang file dalam langkah-langkah berikut.

Tutorial ini menggunakan dua gambar kecil dalam tampilan: logo Azure dan ikon pembesar pencarian (azure-logo.png dan search.png). Salin semua gambar dari proyek GitHub ke folder wwwroot/images di proyek Anda.
Baris pertama Index.cshtml harus mereferensikan model yang digunakan untuk mengkomunikasikan data antara klien (tampilan) dan server (pengontrol), yang merupakan model SearchData yang sebelumnya dibuat. Tambahkan baris ini ke file Index.cshtml.
```
@model FirstAzureSearchApp.Models.SearchData
```
Ini adalah praktik standar untuk memasukkan judul untuk tampilan, sehingga baris berikutnya harus:
```
@{
    ViewData["Title"] = "Home Page";
}
```
Setelah judul, masukkan referensi ke lembar gaya HTML, yang akan segera Anda buat.
```
<head>
    <link rel="stylesheet" href="~/css/hotels.css" />
</head>
```

Isi tampilan menangani dua kasus penggunaan. Pertama, ini harus menyediakan halaman kosong saat digunakan pertama kali, sebelum teks pencarian dimasukkan. Kedua, harus menangani hasil dan kotak teks pencarian secara bersamaan untuk kueri berulang.

Untuk menangani dua kasus tersebut, Anda perlu memeriksa apakah model yang disediakan untuk tampilan adalah "null". Model null menunjukkan kasus penggunaan pertama (eksekusi awal aplikasi). Tambahkan yang berikut ini ke file Index.cshtml dan baca komentar.

<body>
<h1 class="sampleTitle">
    <img src="~/images/azure-logo.png" width="80" />
    Hotels Search
</h1>

@using (Html.BeginForm("Index", "Home", FormMethod.Post))
{
    // Display the search text box, with the search icon to the right of it.
    <div class="searchBoxForm">
        @Html.TextBoxFor(m => m.searchText, new { @class = "searchBox" }) <input class="searchBoxSubmit" type="submit" value="">
    </div>

    @if (Model != null)
    {
        // Show the result count.
        <p class="sampleText">
            @Model.resultList.TotalCount Results
        </p>

        var results = Model.resultList.GetResults().ToList();

        @for (var i = 0; i < results.Count; i++)
        {
            // Display the hotel name and description.
            @Html.TextAreaFor(m => results[i].Document.HotelName, new { @class = "box1" })
            @Html.TextArea($"desc{i}", results[i].Document.Description, new { @class = "box2" })
        }
    }
}
</body>

Tambahkan lembaran gaya. Di Visual Studio, di File>File Baru>, pilih Lembar Gaya (dengan Umum disorot).

Ganti kode default dengan yang berikut ini. Kami tidak akan masuk ke file ini secara lebih rinci, gayanya adalah HTML standar.

textarea.box1 {
    width: 648px;
    height: 30px;
    border: none;
    background-color: azure;
    font-size: 14pt;
    color: blue;
    padding-left: 5px;
}

textarea.box2 {
    width: 648px;
    height: 100px;
    border: none;
    background-color: azure;
    font-size: 12pt;
    padding-left: 5px;
    margin-bottom: 24px;
}

.sampleTitle {
    font: 32px/normal 'Segoe UI Light',Arial,Helvetica,Sans-Serif;
    margin: 20px 0;
    font-size: 32px;
    text-align: left;
}

.sampleText {
    font: 16px/bold 'Segoe UI Light',Arial,Helvetica,Sans-Serif;
    margin: 20px 0;
    font-size: 14px;
    text-align: left;
    height: 30px;
}

.searchBoxForm {
    width: 648px;
    box-shadow: 0 0 0 1px rgba(0,0,0,.1), 0 2px 4px 0 rgba(0,0,0,.16);
    background-color: #fff;
    display: inline-block;
    border-collapse: collapse;
    border-spacing: 0;
    list-style: none;
    color: #666;
}

.searchBox {
    width: 568px;
    font-size: 16px;
    margin: 5px 0 1px 20px;
    padding: 0 10px 0 0;
    border: 0;
    max-height: 30px;
    outline: none;
    box-sizing: content-box;
    height: 35px;
    vertical-align: top;
}

.searchBoxSubmit {
    background-color: #fff;
    border-color: #fff;
    background-image: url(/images/search.png);
    background-repeat: no-repeat;
    height: 20px;
    width: 20px;
    text-indent: -99em;
    border-width: 0;
    border-style: solid;
    margin: 10px;
    outline: 0;
}

Simpan file lembar gaya sebagai hotels.css, ke folder wwwroot/css , bersama dengan file site.css default.

Itu melengkapi pandangan kita. Pada titik ini, semua model dan tampilan sudah selesai. Hanya pengendali yang tersisa untuk menyatukan semuanya.

Tentukan metode

Dalam langkah ini, ubah konten Pengontrol Rumah.

Buka file HomeController.cs dan ganti pernyataan penggunaan dengan yang berikut ini.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using FirstAzureSearchApp.Models;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using System;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;

Menambahkan metode Indeks

Dalam aplikasi MVC, metode Index() adalah metode tindakan default untuk pengontrol apa pun. Ini membuka halaman HTML indeks. Metode default, yang tidak mengambil parameter, digunakan dalam tutorial ini untuk kasus penggunaan start-up aplikasi: merender halaman pencarian kosong.

Di bagian ini, kami memperluas metode untuk mendukung kasus penggunaan kedua: merender halaman ketika pengguna telah memasukkan teks pencarian. Untuk mendukung kasus ini, metode indeks diperluas untuk mengambil model sebagai parameter.

Tambahkan metode berikut, setelah metode Index() default.

    [HttpPost]
    public async Task<ActionResult> Index(SearchData model)
    {
        try
        {
            // Ensure the search string is valid.
            if (model.searchText == null)
            {
                model.searchText = "";
            }

            // Make the Azure Cognitive Search call.
            await RunQueryAsync(model);
        }

        catch
        {
            return View("Error", new ErrorViewModel { RequestId = "1" });
        }
        return View(model);
    }

Perhatikan deklarasi async untuk metode, dan panggilan await ke RunQueryAsync. Kata kunci ini bertanggung jawab untuk menangani panggilan asinkron, sehingga mencegah pemblokiran utas di server.

Blok tangkapan menggunakan model kesalahan default yang dibuat.

Perhatikan penanganan kesalahan dan tampilan dan metode default lainnya

Bergantung pada versi .NET Core mana yang Anda gunakan, kumpulan tampilan default yang sedikit berbeda dibuat. Untuk .NET Core 3.1, tampilan defaultnya adalah Indeks, Privasi, dan Kesalahan. Anda dapat melihat halaman default ini saat menjalankan aplikasi, dan memeriksa bagaimana halaman tersebut ditangani di pengontrol.

Anda akan menguji tampilan Kesalahan nanti dalam tutorial ini.

Dalam sampel GitHub, tampilan yang tidak digunakan dan tindakan terkaitnya dihapus.

Menambahkan metode RunQueryAsync

Panggilan Azure Cognitive Search dienkapsulasi dalam metode RunQueryAsync kami.

Pertama tambahkan beberapa variabel statis untuk menyiapkan layanan Azure, dan panggilan untuk memulainya.

    private static SearchClient _searchClient;
    private static SearchIndexClient _indexClient;
    private static IConfigurationBuilder _builder;
    private static IConfigurationRoot _configuration;

    private void InitSearch()
    {
        // Create a configuration using appsettings.json
        _builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
        _configuration = _builder.Build();

        // Read the values from appsettings.json
        string searchServiceUri = _configuration["SearchServiceUri"];
        string queryApiKey = _configuration["SearchServiceQueryApiKey"];

        // Create a service and index client.
        _indexClient = new SearchIndexClient(new Uri(searchServiceUri), new AzureKeyCredential(queryApiKey));
        _searchClient = _indexClient.GetSearchClient("hotels");
    }

Sekarang, tambahkan metode RunQueryAsync itu sendiri.
```
private async Task<ActionResult> RunQueryAsync(SearchData model)
{
    InitSearch();

    var options = new SearchOptions() 
    { 
        IncludeTotalCount = true
    };

    // Enter Hotel property names into this list so only these values will be returned.
    // If Select is empty, all values will be returned, which can be inefficient.
    options.Select.Add("HotelName");
    options.Select.Add("Description");

    // For efficiency, the search call should be asynchronous, so use SearchAsync rather than Search.
    model.resultList = await _searchClient.SearchAsync<Hotel>(model.searchText, options).ConfigureAwait(false);          

    // Display the results.
    return View("Index", model);
}
```
Dalam metode ini, pertama-tama pastikan konfigurasi Azure kami dimulai, lalu atur beberapa opsi pencarian. Opsi Pilih menentukan bidang mana yang akan dikembalikan dalam hasil, dan dengan demikian cocok dengan nama properti di kelas hotel . Jika Anda menghilangkan Pilih, semua bidang yang tidak tersembunyi akan ditampilkan, yang bisa tidak efisien jika Anda hanya tertarik pada subset dari semua bidang yang tersedia.

Panggilan asinkron untuk mencari merumuskan permintaan (dimodelkan sebagai searchText) dan respons (dimodelkan sebagai searchResult). Jika Anda melakukan debugging kode ini, kelas SearchResult adalah kandidat yang baik untuk menetapkan titik henti jika Anda perlu memeriksa isi model.resultList. Anda harus menemukan bahwa itu intuitif, hanya menyediakan data yang Anda minta, dan tidak banyak lagi.

Menguji aplikasi

Sekarang, mari kita periksa apakah aplikasi berjalan dengan benar.

Pilih Debug>Mulai Tanpa Penelusuran Kesalahan atau tekan F5. Jika aplikasi berjalan seperti yang diharapkan, Anda akan mendapatkan tampilan Indeks awal.
Masukkan string kueri seperti "pantai" (atau teks apa pun yang teringat), dan klik ikon pencarian untuk mengirim permintaan.
Coba masukkan "bintang lima". Perhatikan bahwa kueri ini tidak mengembalikan hasil. Pencarian yang lebih canggih akan memperlakukan "bintang lima" sebagai sinonim untuk "mewah" dan mengembalikan hasil tersebut. Dukungan untuk sinonim tersedia di Azure Cognitive Search, tetapi tidak tercakup dalam seri tutorial ini.
Coba masukkan "hot" sebagai teks pencarian. Ini tidak mengembalikan entri dengan kata "hotel" di dalamnya. Pencarian kami hanya menemukan seluruh kata, meskipun beberapa hasil dikembalikan.
Coba kata lain: "kolam", "sinar matahari", "pemandangan", dan apa pun. Anda akan melihat Azure Cognitive Search bekerja pada tingkat yang paling sederhana, tetapi masih meyakinkan.

Menguji kondisi dan kesalahan tepi

Penting untuk memverifikasi bahwa fitur penanganan kesalahan kami berfungsi sebagaimana mestinya, bahkan ketika semuanya bekerja dengan sempurna.

Dalam metode Indeks, setelah panggilan try {, masukkan baris Throw new Exception(). Pengecualian ini akan memunculkan kesalahan saat Anda mencari dalam teks.
Jalankan aplikasi, masukkan "bar" sebagai teks pencarian, dan klik ikon pencarian. Pengecualian akan mengakibatkan tampilan kesalahan.

Penting

Ini merupakan risiko keamanan untuk menampilkan nomor kesalahan internal pada halaman kesalahan. Jika aplikasi Anda ditujukan untuk penggunaan umum, ikuti praktik terbaik keamanan tentang apa yang harus dikembalikan saat kesalahan terjadi.
Hapus Throw new Exception() saat Anda puas, penanganan kesalahan berfungsi sebagaimana mestinya.

Kesimpulan

Pertimbangkan hal-hal berikut dari proyek ini:

Panggilan Azure Cognitive Search ringkas, dan mudah untuk menafsirkan hasilnya.
Panggilan asinkron menambahkan sejumlah kecil kompleksitas ke pengontrol, tetapi merupakan praktik terbaik yang meningkatkan performa.
Aplikasi ini melakukan pencarian teks langsung, yang ditentukan oleh apa yang disiapkan di searchOptions. Namun, kelas yang satu ini dapat diisi dengan banyak anggota yang menambahkan kecanggihan ke dalam pencarian. Dengan sedikit lebih banyak pekerjaan, Anda dapat membuat aplikasi ini jauh lebih kuat.

Langkah selanjutnya

Untuk meningkatkan pengalaman pengguna, tambahkan lebih banyak fitur, terutama penomoran halaman (baik menggunakan nomor halaman, atau pengguliran tak terbatas), dan lengkapi/saran otomatis. Anda juga dapat mempertimbangkan opsi pencarian lainnya (misalnya, pencarian geografis di hotel dalam radius tertentu dari titik tertentu) dan pemesanan hasil pencarian.

Langkah-langkah berikutnya ini ditangani dalam tutorial yang tersisa. Mari kita mulai dengan penomor.

Tutorial C#: Penomoran hasil pencarian - Azure Cognitive Search

Terakhir diperbarui pada 2022-07-01