Kurz: Vytvoření první vyhledávací aplikace ve službě Azure Cognitive Search pomocí sady .NET SDK

2022-07-01

V tomto kurzu se dozvíte, jak vytvořit webovou aplikaci, která se dotazuje a vrací výsledky z indexu vyhledávání pomocí služby Azure Cognitive Search a sady Visual Studio.

V tomto kurzu se naučíte:

Nastavení vývojového prostředí
Modelování datových struktur
Vytvoření webové stránky pro shromažďování vstupů dotazů a zobrazení výsledků
Definování metody vyhledávání
Otestování aplikace

Dozvíte se také, jak jednoduché je vyhledávací dotaz. Klíčové příkazy v kódu jsou shrnuty v následujících několika řádcích.

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();

Stačí jedno volání, které prohledá index vyhledávání a vrátí výsledky.

Přehled

V tomto kurzu se používá index hotels-sample-index, který můžete rychle vytvořit ve své vlastní vyhledávací službě pomocí rychlého startu importu dat. Index obsahuje fiktivní data hotelů, která jsou k dispozici jako předdefinovaný zdroj dat ve všech vyhledávacích službách.

První lekce v tomto kurzu vytvoří základní konstrukci dotazu a vyhledávací stránku, kterou v dalších lekcích vylepšíte tak, aby zahrnovala stránkování, filtry a nápovědu při psaní.

Dokončenou verzi kódu najdete v následujícím projektu:

1-basic-search-page (GitHub)

Požadavky

Vytvořte nebo najděte existující vyhledávací službu.
Ukázkový index (hotels-sample-index) hostovaný ve vaší vyhledávací službě.
Visual Studio
Klientská knihovna Azure.Cognitive.Search (verze 11)

Instalace a spuštění projektu z GitHubu

Pokud chcete přejít k pracovní aplikaci, stáhněte a spusťte hotový kód podle následujících kroků.

Vyhledejte ukázku na GitHubu: Vytvoření první aplikace.
V kořenové složce vyberte Code (Kód) a potom Clone or Download ZIP (Klonovat nebo Stáhnout ZIP) a vytvořte svou soukromou místní kopii projektu.
Ve Visual Studiu přejděte na řešení pro základní vyhledávací stránku („1-basic-search-page“) a otevřete ho, poté vyberte Spustit bez ladění (nebo stiskněte klávesu F5) pro sestavení a spuštění programu.
Toto je index hotelů, takže zadejte některá slova, která můžete použít k hledání hotelů (například "wi-fi", "view", "bar", "parking"). Prozkoumejte výsledky.

Základní komponenty pro propracovanější vyhledávání jsou součástí této jedné aplikace. Pokud s vývojem vyhledávání začínáte, můžete tuto aplikaci vytvořit krok za krokem a seznámit se s pracovním postupem. V následujících částech se dozvíte, jak na to.

Nastavení vývojového prostředí

Pokud chcete tento projekt vytvořit úplně od začátku, a tím posílit koncepty služby Azure Cognitive Search, začněte projektem sady Visual Studio.

V sadě Visual Studio vyberte Nový>projekt a pak ASP.NET Core Web App (model –View-Controller).
Pojmenujte projekt, například FirstSearchApp, a nastavte umístění. Vyberte Další.
Přijměte výchozí hodnoty pro cílovou architekturu, typ ověřování a HTTPS. Vyberte Vytvořit.
Nainstalujte klientskou knihovnu. VeSprávci> balíčků NuGet Tools>spravujte balíčky NuGet pro řešení..., vyberte Procházet a vyhledejte "azure.search.documents". Nainstalujte Azure.Search.Documents (verze 11 nebo novější), přijměte licenční smlouvy a závislosti.

Inicializace služby Azure Cognitive Search

V tomto kroku nastavte koncový bod a přístupový klíč pro připojení k vyhledávací službě, která poskytuje ukázkový index hotelů.

Otevřete appsettings.json a nahraďte výchozí řádky adresou URL vyhledávací služby (ve formátu https://<service-name>.search.windows.net) a klíčem rozhraní API správce nebo dotazu vaší vyhledávací služby. Vzhledem k tomu, že index nemusíte vytvářet ani aktualizovat, můžete pro účely tohoto kurzu použít klíč dotazu.
```
{
    "SearchServiceUri": "<YOUR-SEARCH-SERVICE-URI>",
    "SearchServiceQueryApiKey": "<YOUR-SEARCH-SERVICE-API-KEY>"
}
```
V Průzkumníku řešení vyberte soubor a ve vlastnostech změňte nastavení Kopírovat do výstupního adresáře na kopírovat, pokud je novější.

Modelování datových struktur

Modely (třídy jazyka C#) slouží ke komunikaci dat mezi klientem (zobrazením), serverem (kontrolerem) a také cloudem Azure pomocí architektury MVC (model, zobrazení, kontroler). Tyto modely obvykle odrážejí strukturu dat, ke kterým se přistupuje.

V tomto kroku budete modelovat datové struktury indexu vyhledávání a také hledaný řetězec použitý při komunikaci zobrazení/kontroleru. V indexu hotelů má každý hotel mnoho pokojů a každý hotel má vícedílnou adresu. Kompletní reprezentace hotelu je hierarchická a vnořená datová struktura. K vytvoření každé komponenty budete potřebovat tři třídy.

Sada hotelových, adresních a pokojových tříd se označuje jako komplexní typy, důležitou funkcí služby Azure Cognitive Search. Komplexní typy mohou být v mnoha vrstvách tříd a podtříd a umožňují reprezentovat mnohem složitější datové struktury, než je tomu u jednoduchých typů (jde o třídu obsahující pouze primitivní členy).

V Průzkumníku řešení klikněte pravým tlačítkem na Models>Přidat>novou položku.

Vyberte třídu a pojmenujte položku Hotel.cs. Nahraďte veškerý obsah Hotel.cs následujícím kódem. Všimněte si členů třídy Address a Room, tato pole jsou samostatnými třídami, proto budete potřebovat i modely pro ně.

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; }
    }
}

Opakujte postup vytvoření modelu pro třídu Address a pojmenujte soubor Address.cs. Obsah nahraďte následujícím kódem.

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; }
    }
}

A znovu postupujte stejným způsobem pro vytvoření třídy Room a pojmenujte soubor 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; }
    }
}

Poslední model, který vytvoříte v tomto kurzu, je třída s názvem SearchData a představuje vstup uživatele (searchText) a výstup hledání (resultList). Typ výstupu je kritický, SearchResults<Hotel>, protože tento typ přesně odpovídá výsledkům hledání a potřebujete tento odkaz předat do zobrazení. Nahraďte výchozí šablonu následujícím kódem.
```
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;
    }
}
```

Vytvoření webové stránky

Šablony projektů mají řadu klientských zobrazení umístěných ve složce Zobrazení . Přesná zobrazení závisí na verzi rozhraní .NET Core, kterou používáte (v této ukázce se používá verze 3.1). V tomto kurzu upravíte index.cshtml tak, aby zahrnoval prvky vyhledávací stránky.

Odstraňte obsah souboru Index.cshtml v celém souboru a znovu ho sestavte v následujících krocích.

Tento kurz používá v zobrazení dva malé obrázky: logo Azure a ikonu lupy hledání (azure-logo.png a search.png). Zkopírujte obrázky z projektu GitHub do složky wwwroot/images v projektu.
První řádek index.cshtml by měl odkazovat na model použitý ke komunikaci dat mezi klientem (zobrazení) a serverem (kontrolerem), což je model SearchData dříve vytvořený. Přidejte tento řádek do souboru Index.cshtml.
```
@model FirstAzureSearchApp.Models.SearchData
```
Standardním postupem je zadat název zobrazení, takže další řádky by měly být:
```
@{
    ViewData["Title"] = "Home Page";
}
```
Za nadpisem zadejte odkaz na šablonu stylů HTML, kterou vytvoříte za chvíli.
```
<head>
    <link rel="stylesheet" href="~/css/hotels.css" />
</head>
```

Tělo zobrazení zpracovává dva případy použití. Nejprve musí před zadáním libovolného hledaného textu zadat prázdnou stránku při prvním použití. Za druhé musí zpracovávat výsledky kromě vyhledávacího textového pole pro opakované dotazy.

Pokud chcete zpracovat oba případy, musíte zkontrolovat, jestli má model zadaný do zobrazení hodnotu null. Model null označuje první případ použití (počáteční spuštění aplikace). Do souboru Index.cshtml přidejte následující kód a pročtěte si komentáře.

<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>

Přidejte šablonu stylů. Ve Visual Studiu, v nabídce Soubor>Nový>Soubor, vyberte šablonu stylů (s možností Obecné zvýrazněnou).

Nahraďte výchozí kód následujícím kódem. Tímto souborem se nebudeme dále zabývat, styly jsou standardní HTML.

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;
}

Uložte soubor šablony stylů jako hotels.css do složky wwwroot/css spolu s výchozím site.css souborem.

Tím se naše zobrazení dokončí. V tomto okamžiku jsou modely i zobrazení dokončeny. Jen kontroler je ponechán, aby všechno svážel dohromady.

Definování metod

V tomto kroku upravte obsah domovského kontroleru.

Otevřete soubor HomeController.cs a nahraďte příkazy using následujícím kódem.

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;

Přidání metod indexu

V aplikaci MVC je metoda Index() výchozí metodou akce pro libovolný kontroler. Otevře indexovou stránku HTML. Výchozí metoda, která nepřijímá žádné parametry, se v tomto kurzu používá pro případ použití spuštění aplikace: vykreslení prázdné vyhledávací stránky.

V této části rozšíříme metodu podpory druhého případu použití: vykreslení stránky, když uživatel zadal hledaný text. Pro podporu tohoto případu je metoda indexu rozšířena tak, aby jako parametr převzala model.

Za výchozí metodu Index() přidejte následující metodu.

    [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);
    }

Všimněte si deklarace async metody a volání await na RunQueryAsync. Tato klíčová slova se stará o asynchronní volání, a proto se vyhýbají blokování vláken na serveru.

Blok catch používá výchozí model chyb, který byl vytvořen.

Poznamenejte si zpracování chyb a další výchozí zobrazení a metody.

V závislosti na tom, jakou verzi .NET Core používáte, se vytvoří mírně odlišná sada výchozích zobrazení. Pro .NET Core 3.1 jsou výchozí zobrazení index, ochrana osobních údajů a chyba. Tyto výchozí stránky můžete zobrazit při spuštění aplikace a prozkoumat, jak se zpracovávají v kontroleru.

Později v tomto kurzu otestujete zobrazení chyby.

V ukázce z GitHubu jsou odstraněna nepoužívaná zobrazení a jejich přidružené akce.

Přidání metody RunQueryAsync

Volání služby Azure Cognitive Search je zapouzdřené v naší metodě RunQueryAsync .

Nejprve přidejte několik statických proměnných pro nastavení služby Azure a volání, které je zahájí.

    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");
    }

Teď přidejte samotnou metodu RunQueryAsync .
```
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);
}
```
V této metodě nejprve zkontrolujte, jestli je inicializována naše konfigurace Azure, a pak nastavte některé možnosti hledání. Možnost Select určuje, která pole se mají vrátit ve výsledcích, a proto odpovídají názvům vlastností v hotelové třídě. Pokud vynecháte výběr, vrátí se všechna skrytá pole, která můžou být neefektivní, pokud vás zajímá jenom podmnožina všech možných polí.

Asynchronní volání vyhledávání formuluje požadavek (modelovaný jako searchText) a odpověď (modelovaná jako searchResult). Pokud ladíte tento kód, třída SearchResult je dobrým kandidátem pro nastavení zarážky, pokud potřebujete prozkoumat obsah model.resultList. Měli byste zjistit, že je intuitivní a poskytuje jenom data, která jste požadovali, a ne mnoho dalšího.

Otestování aplikace

Teď zkontrolujeme, jestli aplikace běží správně.

Vyberte Debug>Spustit bez ladění nebo stiskněte F5. Pokud aplikace běží podle očekávání, měli byste získat počáteční zobrazení indexu.
Zadejte řetězec dotazu, například "pláž" (nebo jakýkoliv text, který je na mysli) a kliknutím na ikonu hledání odešlete požadavek.
Zkuste zadat "pět hvězdiček". Všimněte si, že tento dotaz nevrací žádné výsledky. Sofistikovanější hledání by zacházelo s "pět hvězdiček" jako synonymem pro "luxus" a vrátilo by tyto výsledky. Podpora synonym je dostupná ve službě Azure Cognitive Search, ale v této sérii kurzů se na ně nevztahuje.
Zkuste jako hledaný text zadat "hot". Nevrací položky se slovem "hotel" v nich. Hledání pouze vyhledá celá slova, i když se vrátí několik výsledků.
Zkuste jiná slova: "bazén", "sluníčko", "výhled" a třeba cokoli. Uvidíte, že Azure Cognitive Search funguje na nejjednodušší, ale stále přesvědčivé úrovni.

Testování hraničních podmínek a chyb

Je důležité ověřit, že funkce zpracování chyb fungují tak, jak by měly, i když všechno funguje dokonale.

V metodě Index po volání try { zadejte řádek Throw new Exception(). Tato výjimka způsobí chybu při vyhledávání textu.
Spusťte aplikaci, zadejte "bar" jako hledaný text a klikněte na ikonu hledání. Výsledkem výjimky by mělo být zobrazení chyb.

Důležité

Považuje se za bezpečnostní riziko vrácení interních chybových čísel na chybových stránkách. Pokud je vaše aplikace určena pro obecné použití, postupujte podle osvědčených postupů zabezpečení týkajících se toho, co vrátit, když dojde k chybě.
Pokud jste spokojení se zpracováním chyb, odeberte Throw new Exception() při přesvědčení, že zpracování chyb funguje správně.

Klíčové poznatky

Vezměte v úvahu následující poznatky z tohoto projektu:

Volání služby Azure Cognitive Search je stručné a výsledky se snadno interpretují.
Asynchronní volání přidávají do kontroleru malé množství složitosti, ale jedná se o osvědčený postup, který zlepšuje výkon.
Tato aplikace prováděla jednoduché vyhledávání textu definovaného nastavením v searchOptions. Tato jedna třída však může být naplněna mnoha členy, které přidávají do vyhledávání sofistikovanost. S trochou více práce můžete tuto aplikaci učinit výrazně silnější.

Další kroky

Pokud chcete zlepšit uživatelské prostředí, přidejte další funkce, zejména stránkování (buď pomocí čísel stránek, nebo nekonečné posouvání) a automatické dokončování/návrhy. Můžete také zvážit další možnosti hledání (například geografické vyhledávání hotelů v zadaném poloměru daného bodu) a řazení výsledků hledání.

Tyto další kroky jsou vyřešené ve zbývajících kurzech. Začněme stránkováním.

Kurz jazyka C#: Stránkování výsledků hledání – Azure Cognitive Search

Sdílet prostřednictvím