Jak používat Microsoft.Azure.Search v aplikaci C# .NET

Tento článek vysvětluje, jak vytvářet a spravovat vyhledávací objekty pomocí jazyka C# a starší klientské knihovny Microsoft.Azure.Search (verze 10) v sadě Azure SDK pro .NET.

Verze 10 je poslední verzí balíčku Microsoft.Azure.Search. V budoucnu se nové funkce nasadí ve službě Azure.Search.Documents od týmu sady Azure SDK.

O verzi 10

Sada SDK se skládá z několika klientských knihoven, které umožňují spravovat indexy, zdroje dat, indexery a mapy synonym, stejně jako nahrávání a správu dokumentů a spouštění dotazů, a to vše bez nutnosti zabývat se podrobnostmi HTTP a JSON. Všechny tyto klientské knihovny se distribuují jako balíčky NuGet.

Hlavní balíček NuGet je Microsoft.Azure.Search, což je metabalíč, který obsahuje všechny ostatní balíčky jako závislosti. Tento balíček použijte, pokud teprve začínáte nebo pokud víte, že vaše aplikace bude potřebovat všechny funkce služby Azure Cognitive Search.

Další balíčky NuGet v sadě SDK jsou:

• Microsoft.Azure.Search.Data: Tento balíček použijte, pokud vyvíjíte aplikaci .NET pomocí služby Azure Cognitive Search a potřebujete pouze dotazovat nebo aktualizovat dokumenty v indexech. Pokud potřebujete také vytvořit nebo aktualizovat indexy, mapy synonym nebo jiné prostředky na úrovni služby, použijte místo toho balíček Microsoft.Azure.Search.
• Microsoft.Azure.Search.Service: Tento balíček použijte, pokud vyvíjíte automatizaci v .NET ke správě indexů služby Azure Cognitive Search, map synonym, indexerů, zdrojů dat nebo jiných prostředků na úrovni služby. Pokud potřebujete dotazovat nebo aktualizovat dokumenty jenom v indexech, použijte místo toho balíček Microsoft.Azure.Search.Data. Pokud potřebujete všechny funkce služby Azure Cognitive Search, použijte místo toho balíček Microsoft.Azure.Search.
• Microsoft.Azure.Search.Common: Běžné typy vyžadované knihovnami .NET služby Azure Cognitive Search Tento balíček nemusíte používat přímo ve vaší aplikaci. Slouží pouze jako závislost.

Různé klientské knihovny definují třídy, jako jsou Index, Fielda Document, a také operace, jako jsou Indexes.Create a Documents.Search ve třídách SearchServiceClient a SearchIndexClient. Tyto třídy jsou uspořádány do následujících jmenných prostorů.

• Microsoft.Azure.Search
• Microsoft.Azure.Search.Models

Pokud chcete poskytnout zpětnou vazbu k budoucí aktualizaci sady SDK, podívejte se na naši stránku pro zpětnou vazbu nebo vytvořte problém na GitHubu a v názvu problému uveďte "Azure Cognitive Search".

Sada .NET SDK cílí na verzi2019-05-06 rozhraní REST API služby Azure Cognitive Search. Tato verze zahrnuje podporu komplexních typů, rozšiřování AI, automatického dokončování a režimu parsování JsonLines při indexování objektů blob Azure.

Tato sada SDK nepodporuje operace správy , jako je vytváření a škálování vyhledávacích služeb a správa klíčů rozhraní API. Pokud potřebujete spravovat prostředky služby Search z aplikace .NET, můžete použít sadu SDK pro správu .NET služby Azure Cognitive Search.

Aktualizace na verzi 10

Pokud už používáte starší verzi sady .NET SDK služby Azure Cognitive Search a chcete upgradovat na nejnovější obecně dostupnou verzi, tento článek vysvětluje, jak na to.

Požadavky sady SDK

1. Visual Studio 2017 nebo novější
2. Vlastní služba Azure Cognitive Search. Abyste mohli používat sadu SDK, budete potřebovat název vaší služby a jeden nebo více klíčů rozhraní API. Vytvoření služby v portálu vám pomůže projít těmito kroky.
3. Stáhněte balíček NuGet sady .NET SDK služby Azure Cognitive Search pomocí příkazu Spravovat balíčky NuGet v sadě Visual Studio. Stačí vyhledat název balíčku Microsoft.Azure.Search na NuGet.org (nebo jeden z dalších názvů balíčků výše, pokud potřebujete jenom podmnožinu funkcí).

Sada .NET SDK služby Azure Cognitive Search podporuje aplikace, které cílí na rozhraní .NET Framework 4.5.2 a vyšší a také .NET Core 2.0 a vyšší.

Základní scénáře

Ve vyhledávací aplikaci je potřeba udělat několik věcí. V tomto kurzu se budeme zabývat těmito základními scénáři:

• Vytvoření indexu
• Plnění indexu dokumenty
• Hledání dokumentů pomocí fulltextového vyhledávání a filtrů

Každý z těchto scénářů ilustruje následující ukázkový kód. Nebojte se používat fragmenty kódu ve vlastní aplikaci.

Přehled

Ukázková aplikace, která prozkoumáme, vytvoří nový index s názvem "hotels", naplní ho několika dokumenty a pak provede některé vyhledávací dotazy. Tady je hlavní program zobrazující celkový tok:

// This sample shows how to delete, create, upload documents and query an index
static void Main(string[] args)
{
    IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
    IConfigurationRoot configuration = builder.Build();

    SearchServiceClient serviceClient = CreateSearchServiceClient(configuration);

    string indexName = configuration["SearchIndexName"];

    Console.WriteLine("{0}", "Deleting index...\n");
    DeleteIndexIfExists(indexName, serviceClient);

    Console.WriteLine("{0}", "Creating index...\n");
    CreateIndex(indexName, serviceClient);

    ISearchIndexClient indexClient = serviceClient.Indexes.GetClient(indexName);

    Console.WriteLine("{0}", "Uploading documents...\n");
    UploadDocuments(indexClient);

    ISearchIndexClient indexClientForQueries = CreateSearchIndexClient(configuration);

    RunQueries(indexClientForQueries);

    Console.WriteLine("{0}", "Complete.  Press any key to end application...\n");
    Console.ReadKey();
}

Projdeme si to krok za krokem. Nejprve musíme vytvořit nový SearchServiceClient. Tento objekt umožňuje spravovat indexy. Pokud chcete vytvořit jednu, musíte zadat název služby Azure Cognitive Search a také klíč rozhraní API pro správu. Tyto informace můžete zadat do appsettings.json souboru ukázkové aplikace .

private static SearchServiceClient CreateSearchServiceClient(IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string adminApiKey = configuration["SearchServiceAdminApiKey"];

    SearchServiceClient serviceClient = new SearchServiceClient(searchServiceName, new SearchCredentials(adminApiKey));
    return serviceClient;
}

Několik následujících řádků volá metody k vytvoření indexu s názvem "hotels", přičemž ho nejprve odstraní, pokud již existuje. Tyto metody si projdeme o něco později.

Console.WriteLine("{0}", "Deleting index...\n");
DeleteIndexIfExists(indexName, serviceClient);

Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, serviceClient);

V dalším kroku je potřeba index naplnit. Abychom naplnili index, budeme potřebovat SearchIndexClient. Existují dva způsoby, jak jednu získat: vytvořením nebo voláním Indexes.GetClient na SearchServiceClient. Pro pohodlí používáme ten druhý.

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient(indexName);

Když teď máme SearchIndexClient, můžeme index naplnit. Vytváření indexu probíhá pomocí jiné metody, kterou si projdeme později.

Console.WriteLine("{0}", "Uploading documents...\n");
UploadDocuments(indexClient);

Nakonec provedeme několik vyhledávacích dotazů a zobrazíme výsledky. Tentokrát používáme jiný SearchIndexClient:

ISearchIndexClient indexClientForQueries = CreateSearchIndexClient(indexName, configuration);

RunQueries(indexClientForQueries);

Později se podrobněji podíváme na metodu RunQueries. Tady je kód pro vytvoření nového SearchIndexClient:

private static SearchIndexClient CreateSearchIndexClient(string indexName, IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string queryApiKey = configuration["SearchServiceQueryApiKey"];

    SearchIndexClient indexClient = new SearchIndexClient(searchServiceName, indexName, new SearchCredentials(queryApiKey));
    return indexClient;
}

Tentokrát použijeme klíč dotazu, protože k indexu nepotřebujeme přístup k zápisu. Tyto informace můžete zadat do appsettings.json souboru ukázkové aplikace .

Pokud spustíte tuto aplikaci s platným názvem služby a klíči rozhraní API, výstup by měl vypadat jako v tomto příkladu: (Některé výstupy konzoly byly nahrazeny textem "..." pro ilustraci.)

Deleting index...

Creating index...

Uploading documents...

Waiting for documents to be indexed...

Search the entire index for the term 'motel' and return only the HotelName field:

Name: Secret Point Motel

Name: Twin Dome Motel


Apply a filter to the index to find hotels with a room cheaper than $100 per night, and return the hotelId and description:

HotelId: 1
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 Times 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.

HotelId: 2
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.


Search the entire index, order by a specific field (lastRenovationDate) in descending order, take the top two results, and show only hotelName and lastRenovationDate:

Name: Triple Landscape Hotel
Last renovated on: 9/20/2015 12:00:00 AM +00:00

Name: Twin Dome Motel
Last renovated on: 2/18/1979 12:00:00 AM +00:00


Search the hotel names for the term 'hotel':

HotelId: 3
Name: Triple Landscape Hotel
...

Complete.  Press any key to end application... 

Úplný zdrojový kód aplikace je k dispozici na konci tohoto článku.

Dále se podrobněji podíváme na každou z metod volaných Main.

Vytvoření indexu

Po vytvoření SearchServiceClientodstraní Main index „hotels“, pokud již existuje. Toto odstranění se provádí následující metodou:

private static void DeleteIndexIfExists(string indexName, SearchServiceClient serviceClient)
{
    if (serviceClient.Indexes.Exists(indexName))
    {
        serviceClient.Indexes.Delete(indexName);
    }
}

Tato metoda používá danou SearchServiceClient ke kontrole, jestli index existuje, a pokud ano, odstraňte ho.

Dále Main vytvoří nový index "hotels" zavoláním této metody:

private static void CreateIndex(string indexName, SearchServiceClient serviceClient)
{
    var definition = new Index()
    {
        Name = indexName,
        Fields = FieldBuilder.BuildForType<Hotel>()
    };
    
    serviceClient.Indexes.Create(definition);
}

Tato metoda vytvoří nový Index objekt se seznamem Field objektů, které definují schéma nového indexu. Každé pole má název, datový typ a několik atributů, které definují chování hledání. Třída FieldBuilder používá reflexi k vytvoření seznamu Field objektů pro index prozkoumáním veřejných vlastností a atributů dané Hotel třídy modelu. Později se podrobněji podíváme na Hotel třídu.

Kromě polí můžete do indexu přidat také profily bodování, návrhy nebo možnosti CORS (tyto parametry jsou z ukázky vynechány kvůli stručnosti). Další informace o objektu indexu a jeho součástech najdete v referenční dokumentaci sady SDK a také v referenční dokumentaci rozhraní REST API služby Azure Cognitive Search .

Naplnění indexu

Další krok v Main naplní nově vytvořený index. Tento soubor indexu se provádí v následující metodě: (Kód nahrazený znakem "..." pro ilustraci. Podívejte se na úplné ukázkové řešení pro celý kód základního souboru dat.)

private static void UploadDocuments(ISearchIndexClient indexClient)
{
    var hotels = new Hotel[]
    {
        new Hotel()
        {
            HotelId = "1",
            HotelName = "Secret Point Motel",
            ...
            Address = new Address()
            {
                StreetAddress = "677 5th Ave",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Budget Room, 1 Queen Bed (Cityside)",
                    ...
                },
                new Room()
                {
                    Description = "Budget Room, 1 King Bed (Mountain View)",
                    ...
                },
                new Room()
                {
                    Description = "Deluxe Room, 2 Double Beds (City View)",
                    ...
                }
            }
        },
        new Hotel()
        {
            HotelId = "2",
            HotelName = "Twin Dome Motel",
            ...
            {
                StreetAddress = "140 University Town Center Dr",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Suite, 2 Double Beds (Mountain View)",
                    ...
                },
                new Room()
                {
                    Description = "Standard Room, 1 Queen Bed (City View)",
                    ...
                },
                new Room()
                {
                    Description = "Budget Room, 1 King Bed (Waterfront View)",
                    ...
                }
            }
        },
        new Hotel()
        {
            HotelId = "3",
            HotelName = "Triple Landscape Hotel",
            ...
            Address = new Address()
            {
                StreetAddress = "3393 Peachtree Rd",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Standard Room, 2 Queen Beds (Amenities)",
                    ...
                },
                new Room ()
                {
                    Description = "Standard Room, 2 Double Beds (Waterfront View)",
                    ...
                },
                new Room()
                {
                    Description = "Deluxe Room, 2 Double Beds (Cityside)",
                    ...
                }
            }
        }
    };

    var batch = IndexBatch.Upload(hotels);

    try
    {
        indexClient.Documents.Index(batch);
    }
    catch (IndexBatchException e)
    {
        // Sometimes when your Search service is under load, indexing will fail for some of the documents in
        // the batch. Depending on your application, you can take compensating actions like delaying and
        // retrying. For this simple demo, we just log the failed document keys and continue.
        Console.WriteLine(
            "Failed to index some of the documents: {0}",
            String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
    }

    Console.WriteLine("Waiting for documents to be indexed...\n");
    Thread.Sleep(2000);
}

Tato metoda má čtyři části. První vytvoří pole tří objektů Hotel, z nichž každý obsahuje tři objekty Room, sloužící jako vstupní data pro nahrání do indexu. Tato data jsou pro jednoduchost pevně zakódovaná. Ve vlastní aplikaci budou vaše data pravděpodobně pocházet z externího zdroje dat, jako je databáze SQL.

Druhá část vytvoří IndexBatch obsahující dokumenty. Zadáte operaci, kterou chcete použít pro dávku v době, kdy ji vytvoříte, v tomto případě zavoláním IndexBatch.Upload. Dávka se pak nahraje do indexu služby Azure Cognitive Search metodou Documents.Index.

Třetí část této metody je blok catch, který zpracovává důležitý případ chyby pro indexování. Pokud se službě Azure Cognitive Search nepodaří indexovat některé dokumenty v dávce, IndexBatchException vyvolá Documents.Index. K této výjimce může dojít v případě, že indexujete dokumenty, když je služba zatížená velkým zatížením. Důrazně doporučujeme v kódu explicitně zpracovávat tento případ. Indexování dokumentů, které selhaly, můžete odložit a poté zkusit znovu, nebo můžete zaznamenat chyby a pokračovat, jak to dělá vzorek, nebo v závislosti na požadavcích vaší aplikace na konzistenci dat provést něco jiného.

Nakonec metoda UploadDocuments zpožďuje dvě sekundy. Indexování probíhá asynchronně ve službě Azure Cognitive Search, takže ukázková aplikace musí chvíli počkat, aby se zajistilo, že jsou dokumenty k dispozici pro vyhledávání. Tato odložení se obvykle používají pouze v ukázkových aplikacích a při testech.

Jak sada .NET SDK zpracovává dokumenty

Možná vás zajímá, jak sada .NET SDK služby Azure Cognitive Search dokáže nahrát instance uživatelem definované třídy, jako je Hotel do indexu. Abychom na tuto otázku mohli odpovědět, podívejme se na třídu Hotel:

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Microsoft.Spatial;
using Newtonsoft.Json;

public partial class Hotel
{
    [System.ComponentModel.DataAnnotations.Key]
    [IsFilterable]
    public string HotelId { get; set; }

    [IsSearchable, IsSortable]
    public string HotelName { get; set; }

    [IsSearchable]
    [Analyzer(AnalyzerName.AsString.EnLucene)]
    public string Description { get; set; }

    [IsSearchable]
    [Analyzer(AnalyzerName.AsString.FrLucene)]
    [JsonProperty("Description_fr")]
    public string DescriptionFr { get; set; }

    [IsSearchable, IsFilterable, IsSortable, IsFacetable]
    public string Category { get; set; }

    [IsSearchable, IsFilterable, IsFacetable]
    public string[] Tags { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public bool? ParkingIncluded { get; set; }

    // SmokingAllowed reflects whether any room in the hotel allows smoking.
    // The JsonIgnore attribute indicates that a field should not be created 
    // in the index for this property and it will only be used by code in the client.
    [JsonIgnore]
    public bool? SmokingAllowed => (Rooms != null) ? Array.Exists(Rooms, element => element.SmokingAllowed == true) : (bool?)null;

    [IsFilterable, IsSortable, IsFacetable]
    public DateTimeOffset? LastRenovationDate { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public double? Rating { get; set; }

    public Address Address { get; set; }

    [IsFilterable, IsSortable]
    public GeographyPoint Location { get; set; }

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

První věc, kterou si můžete všimnout, je, že název každé veřejné vlastnosti v Hotel třídy se mapuje na pole se stejným názvem v definici indexu. Pokud chcete, aby každé pole začínalo malým písmenem ("camel case"), můžete sadě SDK říct, aby názvy vlastností mapovala na camel-case automaticky pomocí atributu [SerializePropertyNamesAsCamelCase] ve třídě. Tento scénář je běžný v aplikacích .NET, které provádějí datové vazby, kde cílové schéma není pod kontrolou vývojáře aplikací, aniž by bylo nutné porušit pokyny pro pojmenování "Pascal case" v .NET.

Druhá věc, kterou si můžete všimnout, je každá vlastnost zdobena atributy, jako jsou IsFilterable, IsSearchable, Keya Analyzer. Tyto atributy se mapují přímo na odpovídající atributy pole v indexu služby Azure Cognitive Search. Třída FieldBuilder používá tyto vlastnosti k vytvoření definic polí pro index.

Třetí důležitou věcí třídy Hotel jsou datové typy veřejných vlastností. Typy .NET těchto vlastností odpovídají jejich ekvivalentním typům polí v definici indexu. Například řetězcová vlastnost Category se mapuje na pole category, které je typu Edm.String. Existují podobná mapování typů mezi bool?, Edm.Boolean, DateTimeOffset?a Edm.DateTimeOffset tak dále. Konkrétní pravidla pro mapování typů jsou zdokumentovaná metodou Documents.Get v referenčních informacích k sadě .NET SDK služby Azure Cognitive Search. Třída FieldBuilder se postará o toto mapování za vás, ale přesto může být užitečné pochopit v případě, že potřebujete řešit problémy se serializací.

Všimli jste si SmokingAllowed vlastnosti?

[JsonIgnore]
public bool? SmokingAllowed => (Rooms != null) ? Array.Exists(Rooms, element => element.SmokingAllowed == true) : (bool?)null;

Atribut JsonIgnore u této vlastnosti určuje FieldBuilder, aby ji neserializoval do indexu jako pole. To je skvělý způsob, jak vytvořit počítané vlastnosti na straně klienta, které můžete použít jako pomocné rutiny ve vaší aplikaci. V tomto případě vlastnost SmokingAllowed odráží, zda některý Room v kolekci Rooms umožňuje kouření. Pokud jsou všechny nepravdivé, znamená to, že celý hotel neumožňuje kouření.

Některé vlastnosti, jako jsou Address a Rooms, jsou instancemi tříd .NET. Tyto vlastnosti představují složitější datové struktury a v důsledku toho vyžadují pole se složitým datovým typem v indexu.

Vlastnost Address představuje sadu více hodnot v Address třídě definované níže:

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Newtonsoft.Json;

namespace AzureSearch.SDKHowTo
{
    public partial class Address
    {
        [IsSearchable]
        public string StreetAddress { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string City { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string StateProvince { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string PostalCode { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string Country { get; set; }
    }
}

Tato třída obsahuje standardní hodnoty používané k popisu adres ve Spojených státech nebo Kanadě. Podobné typy můžete použít k seskupení logických polí v indexu.

Vlastnost Rooms představuje pole objektů Room:

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Newtonsoft.Json;

namespace AzureSearch.SDKHowTo
{
    public partial class Room
    {
        [IsSearchable]
        [Analyzer(AnalyzerName.AsString.EnMicrosoft)]
        public string Description { get; set; }

        [IsSearchable]
        [Analyzer(AnalyzerName.AsString.FrMicrosoft)]
        [JsonProperty("Description_fr")]
        public string DescriptionFr { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string Type { get; set; }

        [IsFilterable, IsFacetable]
        public double? BaseRate { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string BedOptions { get; set; }

        [IsFilterable, IsFacetable]
        public int SleepsCount { get; set; }

        [IsFilterable, IsFacetable]
        public bool? SmokingAllowed { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string[] Tags { get; set; }
    }
}

Datový model v .NET a jeho odpovídající schéma indexu by mělo být navržené tak, aby podporovalo prostředí vyhledávání, které chcete poskytnout koncovému uživateli. Každý objekt nejvyšší úrovně v .NET, tj. dokument v indexu, odpovídá výsledku hledání, který byste prezentovat ve svém uživatelském rozhraní. Například v aplikaci pro vyhledávání hotelů můžou koncoví uživatelé chtít hledat podle názvu hotelu, funkcí hotelu nebo vlastností konkrétní místnosti. O něco později probereme některé příklady dotazů.

Tato schopnost používat vlastní třídy k interakci s dokumenty v indexu funguje v obou směrech; Můžete také načíst výsledky hledání a nechat sadu SDK automaticky deserializovat na typ podle vašeho výběru, jak uvidíme v další části.

Proč byste měli použít datové typy s možnou hodnotou null

Při navrhování vlastních tříd modelů pro mapování na index služby Azure Cognitive Search doporučujeme deklarovat vlastnosti typů hodnot, jako jsou bool a int, aby byly null (například bool? místo bool). Pokud používáte vlastnost, která není nullable, musíte zaručit , že žádné dokumenty v indexu neobsahují hodnotu null pro odpovídající pole. Sada SDK ani služba Azure Cognitive Search vám s tímto vynucením nepomůžou.

Nejedná se jen o hypotetický problém: Představte si scénář, ve kterém přidáte nové pole do existujícího indexu, který je typu Edm.Int32. Po aktualizaci definice indexu budou mít všechny dokumenty hodnotu null pro toto nové pole (protože všechny typy jsou ve službě Azure Cognitive Search nulovatelné). Pokud pak použijete třídu modelu s nenulovou vlastností int pro toto pole, při pokusu o načtení dokumentů získáte JsonSerializationException podobné tomuto:

Error converting value {null} to type 'System.Int32'. Path 'IntValue'.

Z tohoto důvodu doporučujeme jako osvědčený postup použít typy s možnou hodnotou null ve třídách modelu.

Vlastní serializace s JSON.NET

Sada SDK používá JSON.NET k serializaci a deserializaci dokumentů. Můžete přizpůsobit serializaci a deserializaci definováním vlastních JsonConverter nebo IContractResolverv případě potřeby. Další informace najdete v JSON.NET dokumentaci. To může být užitečné, když chcete přizpůsobit existující třídu modelu z aplikace pro použití se službou Azure Cognitive Search a další pokročilejší scénáře. Například s vlastní serializací můžete:

• Můžete zahrnout nebo vyloučit určité vlastnosti třídy modelu z ukládání jako pole dokumentu.
• Mapování mezi názvy vlastností v kódu a názvy polí v indexu
• Vytvořte vlastní atributy, které lze použít k mapování vlastností na pole dokumentu.

Příklady implementace vlastní serializace najdete v testech jednotek pro sadu .NET SDK služby Azure Cognitive Search na GitHubu. Dobrým výchozím bodem je tato složka. Obsahuje třídy, které jsou používány vlastními serializačními testy.

Hledání dokumentů v indexu

Posledním krokem v ukázkové aplikaci je vyhledání některých dokumentů v indexu:

private static void RunQueries(ISearchIndexClient indexClient)
{
    SearchParameters parameters;
    DocumentSearchResult<Hotel> results;

    Console.WriteLine("Search the entire index for the term 'motel' and return only the HotelName field:\n");

    parameters =
        new SearchParameters()
        {
            Select = new[] { "HotelName" }
        };

    results = indexClient.Documents.Search<Hotel>("motel", parameters);

    WriteDocuments(results);

    Console.Write("Apply a filter to the index to find hotels with a room cheaper than $100 per night, ");
    Console.WriteLine("and return the hotelId and description:\n");

    parameters =
        new SearchParameters()
        {
            Filter = "Rooms/any(r: r/BaseRate lt 100)",
            Select = new[] { "HotelId", "Description" }
        };

    results = indexClient.Documents.Search<Hotel>("*", parameters);

    WriteDocuments(results);

    Console.Write("Search the entire index, order by a specific field (lastRenovationDate) ");
    Console.Write("in descending order, take the top two results, and show only hotelName and ");
    Console.WriteLine("lastRenovationDate:\n");

    parameters =
        new SearchParameters()
        {
            OrderBy = new[] { "LastRenovationDate desc" },
            Select = new[] { "HotelName", "LastRenovationDate" },
            Top = 2
        };

    results = indexClient.Documents.Search<Hotel>("*", parameters);

    WriteDocuments(results);

    Console.WriteLine("Search the entire index for the term 'hotel':\n");

    parameters = new SearchParameters();
    results = indexClient.Documents.Search<Hotel>("hotel", parameters);

    WriteDocuments(results);
}

Pokaždé, když spustí dotaz, tato metoda nejprve vytvoří nový SearchParameters objekt. Tento objekt slouží k určení dalších možností dotazu, jako je řazení, filtrování, stránkování a fasetování. V této metodě nastavujeme vlastnost Filter, Select, OrderBya Top pro různé dotazy. SearchParameters Všechny vlastnosti jsou zde zdokumentované.

Dalším krokem je skutečné spuštění vyhledávacího dotazu. Spuštění hledání se provádí pomocí Documents.Search metody. Pro každý dotaz předáme hledaný text, který se použije jako řetězec (nebo "*" pokud neexistuje hledaný text), plus parametry hledání vytvořené dříve. Zadáme Hotel také jako parametr typu Documents.Search, který říká sadě SDK, aby dokumenty ve výsledcích hledání byly deserializovány do objektů typu Hotel.

Nakonec po každém dotazu se tato metoda iteruje všemi shodami ve výsledcích hledání a vytiskne každý dokument do konzoly:

private static void WriteDocuments(DocumentSearchResult<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.Results)
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

Pojďme se podrobněji podívat na jednotlivé dotazy. Tady je kód pro spuštění prvního dotazu:

parameters =
    new SearchParameters()
    {
        Select = new[] { "HotelName" }
    };

results = indexClient.Documents.Search<Hotel>("motel", parameters);

WriteDocuments(results);

V tomto případě hledáme v celém indexu slovo "motel" v libovolném prohledávatelném poli a chceme načíst pouze názvy hotelů, jak je specifikováno parametrem Select. Tady jsou výsledky:

Name: Secret Point Motel

Name: Twin Dome Motel

Další dotaz je o něco zajímavější. Chceme najít všechny hotely, které mají pokoj s noční sazbou nižší než 100 USD, a vrátit pouze ID hotelu a popis:

parameters =
    new SearchParameters()
    {
        Filter = "Rooms/any(r: r/BaseRate lt 100)",
        Select = new[] { "HotelId", "Description" }
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

Tento dotaz používá k filtrování dokumentů v indexu výraz $filterODataRooms/any(r: r/BaseRate lt 100). Tento operátor používá operátor any k aplikaci podmínky 'BaseRate lt 100' na každou položku v kolekci Rooms. Další informace o syntaxi OData, kterou Azure Cognitive Search podporuje, najdete tady.

Tady jsou výsledky dotazu:

HotelId: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York...

HotelId: 2
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to...

Dále chceme najít nejlepší dva hotely, které byly naposledy rekonstruovány, a ukázat název hotelu a datum poslední renovace. Zde je kód:

parameters =
    new SearchParameters()
    {
        OrderBy = new[] { "LastRenovationDate desc" },
        Select = new[] { "HotelName", "LastRenovationDate" },
        Top = 2
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

V tomto případě znovu použijeme syntaxi OData k určení parametru OrderBy jako lastRenovationDate desc. Také jsme nastavili Top na hodnotu 2, abychom zajistili, že získáme jenom první dva dokumenty. Stejně jako předtím jsme nastavili Select, abychom určili, která pole se mají vracet.

Tady jsou výsledky:

Name: Fancy Stay        Last renovated on: 6/27/2010 12:00:00 AM +00:00
Name: Roach Motel       Last renovated on: 4/28/1982 12:00:00 AM +00:00

Nakonec chceme najít všechny názvy hotelů, které odpovídají slovu "hotel":

parameters = new SearchParameters()
{
    SearchFields = new[] { "HotelName" }
};
results = indexClient.Documents.Search<Hotel>("hotel", parameters);

WriteDocuments(results);

A tady jsou výsledky, které zahrnují všechna pole, protože jsme nezadali vlastnost Select:

	HotelId: 3
	Name: Triple Landscape Hotel
	...

Tento krok dokončí kurz, ale nezastaví se tady. **Další kroky poskytují další zdroje informací o službě Azure Cognitive Search.

Další kroky

• Projděte si referenční informace k sadě .NET SDK a rozhraní REST API.
• Projděte si zásady vytváření názvů a seznamte se s pravidly pro pojmenování různých objektů.
• Projděte si podporované datové typy ve službě Azure Cognitive Search.