Rychlý start: Fulltextové vyhledávání

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro .NET k vytvoření, načtení a dotazování vyhledávacího indexu pro vyhledávání full-text označované také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• .NET 8 nebo novější.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. Přejděte do složky rychlý start.

   cd azure-search-dotnet-samples/quickstart-keyword-search/AzureSearchQuickstart
   

3. Nahraďte v Program.cs zástupnou hodnotu serviceEndpoint adresou URL, kterou jste získali v Get endpoint.

4. Nainstalujte závislosti z AzureSearchQuickstart.csproj.

   dotnet restore
   

   Po dokončení obnovení ověřte, že se ve výstupu nezobrazí žádné chyby.

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

Sestavte a spusťte aplikaci.

dotnet run

Výstup

Výstup by měl vypadat přibližně takto:

Deleting index...

Creating index...

Uploading documents...

Waiting for indexing...

Starting queries...

Query #1: Search on empty term '*' to return all documents, showing a subset of fields...

HotelId: 3
Name: Gastronomic Landscape Hotel
Rating: 4.8

HotelId: 2
Name: Old Century Hotel
Rating: 3.6

HotelId: 4
Name: Sublime Palace Hotel
Rating: 4.6

HotelId: 1
Name: Stay-Kay City Hotel
Rating: 3.6


Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...

HotelId: 3
Name: Gastronomic Landscape Hotel
Rating: 4.8

HotelId: 4
Name: Sublime Palace Hotel
Rating: 4.6


Query #3: Limit search to specific fields (pool in Tags field)...

HotelId: 2
Name: Old Century Hotel
Tags: [ pool, free wifi, concierge ]


Query #4: Facet on 'Category'...

HotelId: 3
Name: Gastronomic Landscape Hotel
Category: Suite

HotelId: 2
Name: Old Century Hotel
Category: Boutique

HotelId: 4
Name: Sublime Palace Hotel
Category: Boutique

HotelId: 1
Name: Stay-Kay City Hotel
Category: Boutique


Query #5: Look up a specific document...

3
Query #6: Call Autocomplete on HotelName...

san
sarasota

Complete. Press any key to end this program...

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření vyhledávacího klienta
2. Vytvoření indexu vyhledávání
3. Nahrání dokumentů do indexu
4. Dotazování indexu

Vytvoření vyhledávacího klienta

V Program.csaplikaci vytvoříte dva klienty:

• SearchIndexClient vytvoří index.
• SearchClient načte a dotazuje existující index.

Oba klienti vyžadují koncový bod služby a přihlašovací údaje pro ověřování. V tomto rychlém startu použijete DefaultAzureCredential pro ověřování bez klíčů pomocí Microsoft Entra ID.

Vytvoření indexu vyhledávání

V tomto rychlém startu vytvoříte index hotelů, na který načítáte hotelová data a provádíte dotazy. V tomto kroku definujete pole v indexu. Každá definice pole obsahuje název, datový typ a atributy, které určují způsob použití pole.

Tento příklad používá synchronní metody SearchIndexClient třídy pro jednoduchost a čitelnost. V produkčních scénářích ale pomocí asynchronních metod udržujte aplikaci škálovatelnou a responzivní. Například místo CreateIndex Použijte CreateIndexAsync.

Definování struktur

Vytvoříte dvě pomocné třídy Hotel.cs a Address.cs, abyste definovali strukturu hotelového dokumentu a jeho adresy. Třída Hotel obsahuje pole pro ID hotelu, název, popis, kategorii, značky, parkování, datum renovace, hodnocení a adresu. Třída Address obsahuje pole pro adresu ulice, město, stát/kraj, PSČ a zemi/oblast.

V Azure. Klientská knihovna Search.Documents umožňuje zjednodušit definice polí pomocí SearchableField a SimpleField. Oba jsou pomocné třídy, které generují SearchField a můžou potenciálně zjednodušit váš kód:

• SimpleField může být libovolný datový typ, je vždy nehledatelný (ignorován pro fulltextové vyhledávací dotazy) a je možné je načíst (není skrytý). Ostatní atributy jsou ve výchozím nastavení vypnuté, ale je možné je povolit. Můžete použít SimpleField pro ID dokumentu nebo pouze pro pole použitá ve filtrech, fasetách nebo v bodovacích profilech. Pokud ano, použijte všechny atributy, které jsou nezbytné pro daný scénář, například IsKey = true pro ID dokumentu.

• SearchableField musí být řetězec a je vždy prohledávatelný a načístelný. Ostatní atributy jsou ve výchozím nastavení vypnuté, ale je možné je povolit. Vzhledem k tomu, že tento typ pole je prohledávatelný, podporuje synonyma a úplný doplněk vlastností analyzátoru.

Bez ohledu na to, jestli používáte základní SearchField rozhraní API nebo jeden z pomocných modelů, musíte povolit explicitně atributy filtru, facety a řazení. Například IsFilterable, IsSortable a IsFacetable musí být explicitně přiřazeny, jak je znázorněno v předchozí ukázce.

Vytvoření indexu vyhledávání

V Program.cs vytvoříte objekt SearchIndex a potom zavoláte metodu CreateOrUpdateIndex, abyste index vyjádřili ve vaší vyhledávací službě. Index také obsahuje SearchSuggester, který umožňuje automatické dokončování v zadaných polích.

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient searchIndexClient)
{
    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);

    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);

    searchIndexClient.CreateOrUpdateIndex(definition);
}

Nahrání dokumentů do indexu

Azure AI Vyhledávač prohledá obsah uložený ve službě. V tomto kroku načtete dokumenty JSON, které odpovídají indexu hotelu, který jste vytvořili.

V Azure AI Vyhledávač jsou vyhledávací dokumenty datové struktury, které jsou vstupy indexování a výstupy z dotazů. Jak je získáno z externího zdroje dat, vstupy dokumentů můžou být řádky v databázi, objekty blob v Azure Blob Storage nebo dokumenty JSON na disku. V tomto příkladu použijete zkratku a přímo vložíte JSON dokumenty pro čtyři hotely.

Při nahrávání dokumentů musíte použít objekt IndexDocumentsBatch . Objekt IndexDocumentsBatch obsahuje kolekci Actions, z nichž každý obsahuje dokument a vlastnost, která informuje Azure AI Vyhledávač, jakou akci provést (upload, merge, delete a mergeOrUpload).

V Program.csaplikaci vytvoříte pole dokumentů a akcí indexu a pak předáte pole IndexDocumentsBatch. Následující dokumenty odpovídají indexu pro rychlý start hotelů, jak je definováno hotelovou třídou.

// Upload documents in a single Upload request.
private static void UploadDocuments(SearchClient searchClient)
{
    IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "1",
                HotelName = "Stay-Kay City Hotel",
                Description = "This classic hotel is fully-refurbished and 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.",
                Category = "Boutique",
                Tags = new[] { "view", "air conditioning", "concierge" },
                ParkingIncluded = false,
                LastRenovationDate = new DateTimeOffset(2022, 1, 18, 0, 0, 0, TimeSpan.Zero),
                Rating = 3.6,
                Address = new Address()
                {
                    StreetAddress = "677 5th Ave",
                    City = "New York",
                    StateProvince = "NY",
                    PostalCode = "10022",
                    Country = "USA"
                }
            }),
        // REDACTED FOR BREVITY
}

Metoda UploadDocuments vytvoří IndexDocumentsBatch a volá IndexDocuments na SearchClient pro nahrání dokumentů. Tento rychlý start získá SearchClient z SearchIndexClient pomocí GetSearchClient, který znovu použije stejné přihlašovací údaje.

SearchClient ingesterClient = searchIndexClient.GetSearchClient(indexName);

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

Vzhledem k tomu, že tato konzolová aplikace spouští všechny příkazy postupně, přidá kód mezi indexování a dotazy dvousekundovou dobu čekání.

// Wait 2 seconds for indexing to complete before starting queries (for demo and console-app purposes only)
Console.WriteLine("Waiting for indexing...\n");
System.Threading.Thread.Sleep(2000);

Dvousekundové zpoždění kompenzuje indexování, což je asynchronní, aby se všechny dokumenty mohly indexovat před spuštěním dotazů. Kódování ve zpoždění je obvykle nezbytné pouze v ukázkách, testech a ukázkových aplikacích.

Dotazování indexu

Výsledky dotazu můžete získat hned po indexování prvního dokumentu, ale skutečné testování indexu by mělo počkat na indexování všech dokumentů.

Tato část přidá dvě části funkčnosti: logiku dotazu a výsledky. Pro dotazy použijte metodu Search . Tato metoda přebírá hledaný text (řetězec dotazu) a další možnosti.

SearchResults třída představuje výsledky.

Metoda Program.csvypíše WriteDocuments výsledky hledání do konzoly.

// Write search results to console
private static void WriteDocuments(SearchResults<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.GetResults())
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

private static void WriteDocuments(AutocompleteResults autoResults)
{
    foreach (AutocompleteItem result in autoResults.Results)
    {
        Console.WriteLine(result.Text);
    }

    Console.WriteLine();
}

Příklad dotazu 1

Metoda RunQueries provádí dotazy a vrací výsledky. Výsledky jsou objekty hotelu. Tato ukázka ukazuje podpis metody a první dotaz. Tento dotaz ukazuje Select parametr, který umožňuje vytvořit výsledek pomocí vybraných polí z dokumentu.

// Run queries, use WriteDocuments to print output
private static void RunQueries(SearchClient searchClient)
{
    SearchOptions options;
    SearchResults<Hotel> response;
    
    // Query 1
    Console.WriteLine("Query #1: Search on empty term '*' to return all documents, showing a subset of fields...\n");

    options = new SearchOptions()
    {
        IncludeTotalCount = true,
        Filter = "",
        OrderBy = { "" }
    };

    options.Select.Add("HotelId");
    options.Select.Add("HotelName");
    options.Select.Add("Rating");

    response = searchClient.Search<Hotel>("*", options);
    WriteDocuments(response);
    // REDACTED FOR BREVITY
}

Příklad dotazu 2

Ve druhém dotazu vyhledejte termín, přidejte filtr, který vybere dokumenty, ve kterých Rating je větší než 4, a potom seřadí Rating sestupně. Filtr je logický výraz vyhodnocený na polích IsFilterable v indexu. Dotazy filtrování zahrnují nebo vylučují hodnoty. Proto neexistuje žádné skóre relevance přidružené k dotazu filtru.

// Query 2
Console.WriteLine("Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...\n");

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Rating");

response = searchClient.Search<Hotel>("hotels", options);
WriteDocuments(response);

Příklad dotazu 3

Třetí dotaz ukazuje searchFields, který slouží k určení rozsahu operace fulltextového vyhledávání na konkrétní pole.

// Query 3
Console.WriteLine("Query #3: Limit search to specific fields (pool in Tags field)...\n");

options = new SearchOptions()
{
    SearchFields = { "Tags" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Tags");

response = searchClient.Search<Hotel>("pool", options);
WriteDocuments(response);

Příklad dotazu 4

Čtvrtý dotaz ukazuje facets, který lze použít ke strukturování fasetové navigační struktury.

// Query 4
Console.WriteLine("Query #4: Facet on 'Category'...\n");

options = new SearchOptions()
{
    Filter = ""
};

options.Facets.Add("Category");

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Category");

response = searchClient.Search<Hotel>("*", options);
WriteDocuments(response);

Příklad dotazu 5

V pátém dotazu vraťte konkrétní dokument. Vyhledání dokumentu je typická odpověď na OnClick událost v sadě výsledků.

// Query 5
Console.WriteLine("Query #5: Look up a specific document...\n");

Response<Hotel> lookupResponse;
lookupResponse = searchClient.GetDocument<Hotel>("3");

Console.WriteLine(lookupResponse.Value.HotelId);

Příklad dotazu 6

Poslední dotaz ukazuje syntaxi automatického dokončování, která simuluje částečný vstup uživatele sa , který odpovídá dvěma možným shodám v souvisejícím navrhovateli definovaném v indexu.

// Query 6
Console.WriteLine("Query #6: Call Autocomplete on HotelName...\n");

var autoresponse = searchClient.Autocomplete("sa", "sg");
WriteDocuments(autoresponse);

Souhrn dotazů

Předchozí dotazy zobrazují v dotazu několik způsobů párování termínů: fulltextové vyhledávání, filtry a automatické dokončování.

Metoda SearchClient.Search provádí fulltextové vyhledávání a filtry. Vyhledávací dotaz můžete předat v searchText řetězci, zatímco výraz filtru předáte ve vlastnosti Filter třídy SearchOptions. Pokud chcete filtrovat bez hledání, stačí předat "*"searchText parametr metody Search . Pokud chcete hledat bez filtrování, nechejte Filter vlastnost nenasazenou nebo vůbec nepředávejte SearchOptions instanci.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Java k vytvoření, načtení a dotazování vyhledávacího indexu pro vyhledávání full-text označované také jako hledání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• Java 21 (LTS) a Maven.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. Přejděte do složky rychlý start.

   cd azure-search-java-samples/quickstart-keyword-search
   

3. Nahraďte v src/main/java/azure/search/sample/App.java zástupnou hodnotu searchServiceEndpoint adresou URL, kterou jste získali v Get endpoint.

4. Nainstalujte závislosti.

   mvn clean dependency:copy-dependencies
   

   Po dokončení sestavení ověřte, že se ve výstupu nezobrazí žádné chyby.

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

Zkompilujte a spusťte aplikaci.

Windows

javac -d target/classes -cp "target/dependency/*" src/main/java/azure/search/sample/*.java
java -cp "target/classes;target/dependency/*" azure.search.sample.App

macOS

javac -d target/classes -cp "target/dependency/*" src/main/java/azure/search/sample/*.java
java -cp "target/classes:target/dependency/*" azure.search.sample.App

Linux

javac -d target/classes -cp "target/dependency/*" src/main/java/azure/search/sample/*.java
java -cp "target/classes:target/dependency/*" azure.search.sample.App

Výstup

Výstup by měl vypadat přibližně takto:

Waiting for indexing...

Starting queries...

Query #1: Search on empty term '*' to return all documents, showing a subset of fields...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Address":{"City":"Atlanta"}}
{"HotelId":"2","HotelName":"Old Century Hotel","Address":{"City":"Sarasota"}}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Address":{"City":"San Antonio"}}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Address":{"City":"New York"}}

Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #3: Limit search to specific fields (pool in Tags field)...

{"HotelId":"2","HotelName":"Old Century Hotel","Tags":["pool","free wifi","concierge"]}

Query #4: Facet on 'Category'...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Category":"Suite"}
{"HotelId":"2","HotelName":"Old Century Hotel","Category":"Boutique"}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Category":"Boutique"}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Category":"Boutique"}

Query #5: Look up a specific document...

3

Query #6: Call Autocomplete on HotelName that starts with 's'...

stay
sublime

Complete.

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření vyhledávacího klienta
2. Vytvoření indexu vyhledávání
3. Nahrání dokumentů do indexu
4. Dotazování indexu

Vytvoření vyhledávacího klienta

V App.javaaplikaci vytvoříte dva klienty:

• SearchIndexClient vytvoří index.
• SearchClient načte a dotazuje existující index.

Oba klienti vyžadují koncový bod služby a přihlašovací údaje pro ověřování. V tomto rychlém startu použijete DefaultAzureCredential pro ověřování bez klíčů pomocí Microsoft Entra ID.

Vytvoření indexu vyhledávání

V tomto rychlém startu vytvoříte index hotelů, na který načítáte hotelová data a provádíte dotazy. V tomto kroku definujete pole v indexu. Každá definice pole obsahuje název, datový typ a atributy, které určují způsob použití pole.

Tento příklad používá synchronní metody SearchIndexClient třídy pro jednoduchost a čitelnost. V produkčních scénářích ale pomocí třídy SearchIndexAsyncClient udržujte aplikaci škálovatelnou a responzivní.

Definování struktur

Vytvoříte dvě pomocné třídy Hotel.java a Address.java, abyste definovali strukturu hotelového dokumentu a jeho adresy. Třída Hotel obsahuje pole pro ID hotelu, název, popis, kategorii, značky, parkování, datum renovace, hodnocení a adresu. Třída Address obsahuje pole pro adresu ulice, město, stát/kraj, PSČ a zemi/oblast.

V klientské knihovně azure-search-documents můžete k zjednodušení definic polí použít SearchableField a SimpleField . Obě jsou poznámky, které můžete použít u polí nebo metod pro vygenerování vyhledávacího pole:

• SimpleField může být libovolný datový typ, je vždy nehledatelný (ignorován pro fulltextové vyhledávací dotazy) a je možné je načíst (není skrytý). Ostatní atributy jsou ve výchozím nastavení vypnuté, ale je možné je povolit. Můžete použít SimpleField pro ID dokumentu nebo pouze pro pole použitá ve filtrech, fasetách nebo v bodovacích profilech. Pokud ano, použijte všechny atributy, které jsou nezbytné pro daný scénář, například isKey = true pro ID dokumentu.
• SearchableField musí být řetězec a je vždy prohledávatelný a načístelný. Ostatní atributy jsou ve výchozím nastavení vypnuté, ale je možné je povolit. Vzhledem k tomu, že tento typ pole je prohledávatelný, podporuje synonyma a úplný doplněk vlastností analyzátoru.

Bez ohledu na to, jestli používáte základní SearchField rozhraní API nebo jeden z pomocných modelů, musíte povolit explicitně atributy filtru, facety a řazení. Například isFilterable, isSortable a isFacetable musí být explicitně atribut, jak je znázorněno v předchozí ukázce.

Vytvoření indexu vyhledávání

Ve App.java vytvoříte objekt SearchIndex, a pak zavoláte metodu createOrUpdateIndex, abyste použili index ve své vyhledávací službě. Index také obsahuje SearchSuggester, který umožňuje automatické dokončování v zadaných polích.

// Create Search Index for Hotel model
searchIndexClient.createOrUpdateIndex(
    new SearchIndex(indexName, SearchIndexClient.buildSearchFields(Hotel.class, null))
    .setSuggesters(new SearchSuggester("sg", Arrays.asList("HotelName"))));

Nahrání dokumentů do indexu

Azure AI Vyhledávač prohledá obsah uložený ve službě. V tomto kroku načtete dokumenty JSON, které odpovídají indexu hotelu, který jste vytvořili.

V Azure AI Vyhledávač jsou vyhledávací dokumenty datové struktury, které jsou vstupy indexování a výstupy z dotazů. Jak je získáno z externího zdroje dat, vstupy dokumentů můžou být řádky v databázi, objekty blob v Azure Blob Storage nebo dokumenty JSON na disku. V tomto příkladu použijete zkratku a přímo vložíte JSON dokumenty pro čtyři hotely.

Při nahrávání dokumentů musíte použít objekt IndexDocumentsBatch . Objekt IndexDocumentsBatch obsahuje kolekci objektů IndexActions, z nichž každý obsahuje dokument a vlastnost, která říká Azure AI Vyhledávač, jakou akci provést (upload, merge, delete a mergeOrUpload).

V App.javaaplikaci vytvoříte pole dokumentů a akcí indexu a pak předáte pole IndexDocumentsBatch. Následující dokumenty odpovídají indexu pro rychlý start hotelů, jak je definováno hotelovou třídou.

private static void uploadDocuments(SearchClient searchClient)
{
    var hotelList = new ArrayList<Hotel>();

    var hotel = new Hotel();
    hotel.hotelId = "1";
    hotel.hotelName = "Stay-Kay City Hotel";
    hotel.description = "This classic hotel is fully-refurbished and 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.",
    hotel.category = "Boutique";
    hotel.tags = new String[] { "view", "air conditioning", "concierge" };
    hotel.parkingIncluded = false;
    hotel.lastRenovationDate = OffsetDateTime.of(LocalDateTime.of(LocalDate.of(2022, 1, 18), LocalTime.of(0, 0)), ZoneOffset.UTC);
    hotel.rating = 3.6;
    hotel.address = new Address();
    hotel.address.streetAddress = "677 5th Ave";
    hotel.address.city = "New York";
    hotel.address.stateProvince = "NY";
    hotel.address.postalCode = "10022";
    hotel.address.country = "USA";
    hotelList.add(hotel);
    
    // REDACTED FOR BREVITY

    var batch = new IndexDocumentsBatch<Hotel>();
    batch.addMergeOrUploadActions(hotelList);
    try
    {
        searchClient.indexDocuments(batch);
    }
    catch (Exception e)
    {
        e.printStackTrace();
        // If for some reason any documents are dropped during indexing, you can compensate by delaying and
        // retrying. This simple demo just logs failure and continues
        System.err.println("Failed to index some of the documents");
    }
}

Metoda uploadDocuments vytvoří IndexDocumentsBatch a volá indexDocuments na SearchClient pro nahrání dokumentů. Tento rychlý start vytvoří SearchClient nezávisle pomocí SearchClientBuilderu, který vyžaduje konfiguraci koncového bodu a přihlašovacích údajů samostatně.

uploadDocuments(searchClient);

Vzhledem k tomu, že tato konzolová aplikace spouští všechny příkazy postupně, přidá kód mezi indexování a dotazy dvousekundovou dobu čekání.

// Wait 2 seconds for indexing to complete before starting queries (for demo and console-app purposes only)
System.out.println("Waiting for indexing...\n");
try
{
    Thread.sleep(2000);
}
catch (InterruptedException e)
{
}

Dvousekundové zpoždění kompenzuje indexování, což je asynchronní, aby se všechny dokumenty mohly indexovat před spuštěním dotazů. Kódování ve zpoždění je obvykle nezbytné pouze v ukázkách, testech a ukázkových aplikacích.

Dotazování indexu

Výsledky dotazu můžete získat hned po indexování prvního dokumentu, ale skutečné testování indexu by mělo počkat na indexování všech dokumentů.

Tato část přidá dvě části funkčnosti: logiku dotazu a výsledky. Pro dotazy použijte metodu vyhledávání . Tato metoda přebírá hledaný text (řetězec dotazu) a další možnosti.

SearchPagedIterable třída představuje výsledky.

Metoda App.javavypíše WriteDocuments výsledky hledání do konzoly.

// Write search results to console
private static void WriteSearchResults(SearchPagedIterable searchResults)
{
    searchResults.iterator().forEachRemaining(result ->
    {
        Hotel hotel = result.getDocument(Hotel.class);
        System.out.println(hotel);
    });

    System.out.println();
}

// Write autocomplete results to console
private static void WriteAutocompleteResults(AutocompletePagedIterable autocompleteResults)
{
    autocompleteResults.iterator().forEachRemaining(result ->
    {
        String text = result.getText();
        System.out.println(text);
    });

    System.out.println();
}

Příklad dotazu 1

Metoda RunQueries provádí dotazy a vrací výsledky. Výsledky jsou objekty hotelu. Tato ukázka ukazuje podpis metody a první dotaz. Tento dotaz ukazuje Select parametr, který umožňuje vytvořit výsledek pomocí vybraných polí z dokumentu.

// Run queries, use WriteDocuments to print output
private static void RunQueries(SearchClient searchClient)
{
    // Query 1
    System.out.println("Query #1: Search on empty term '*' to return all documents, showing a subset of fields...\n");

    SearchOptions options = new SearchOptions();
    options.setIncludeTotalCount(true);
    options.setFilter("");
    options.setOrderBy("");
    options.setSelect("HotelId", "HotelName", "Address/City");

    WriteSearchResults(searchClient.search("*", options, Context.NONE));
}

Příklad dotazu 2

Ve druhém dotazu vyhledejte termín, přidejte filtr, který vybere dokumenty, ve kterých Rating je větší než 4, a potom seřadí Rating sestupně. Filtr je logický výraz vyhodnocený přes poleFilterable v indexu. Dotazy filtrování zahrnují nebo vylučují hodnoty. Proto neexistuje žádné skóre relevance přidružené k dotazu filtru.

// Query 2
System.out.println("Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...\n");

options = new SearchOptions();
options.setFilter("Rating gt 4");
options.setOrderBy("Rating desc");
options.setSelect("HotelId", "HotelName", "Rating");

WriteSearchResults(searchClient.search("hotels", options, Context.NONE));

Příklad dotazu 3

Třetí dotaz ukazuje searchFields, který slouží k určení rozsahu operace fulltextového vyhledávání na konkrétní pole.

// Query 3
System.out.println("Query #3: Limit search to specific fields (pool in Tags field)...\n");

options = new SearchOptions();
options.setSearchFields("Tags");

options.setSelect("HotelId", "HotelName", "Tags");

WriteSearchResults(searchClient.search("pool", options, Context.NONE));

Příklad dotazu 4

Čtvrtý dotaz ukazuje facets, který lze použít ke strukturování fasetové navigační struktury.

// Query 4
System.out.println("Query #4: Facet on 'Category'...\n");

options = new SearchOptions();
options.setFilter("");
options.setFacets("Category");
options.setSelect("HotelId", "HotelName", "Category");

WriteSearchResults(searchClient.search("*", options, Context.NONE));

Příklad dotazu 5

V pátém dotazu vraťte konkrétní dokument. Vyhledání dokumentu je typická odpověď na OnClick událost v sadě výsledků.

// Query 5
System.out.println("Query #5: Look up a specific document...\n");

Hotel lookupResponse = searchClient.getDocument("3", Hotel.class);
System.out.println(lookupResponse.hotelId);
System.out.println();

Příklad dotazu 6

Poslední dotaz ukazuje syntaxi automatického dokončování, která simuluje částečný uživatelský vstup s , který se přeloží na dvě možné shody v sourceFields přidruženém s návrhu, který jste definovali v indexu.

// Query 6
System.out.println("Query #6: Call Autocomplete on HotelName that starts with 's'...\n");

WriteAutocompleteResults(searchClient.autocomplete("s", "sg"));

Souhrn dotazů

Předchozí dotazy zobrazují v dotazu několik způsobů párování termínů: fulltextové vyhledávání, filtry a automatické dokončování.

Metoda SearchClient.search provádí fulltextové vyhledávání a filtry. V řetězci searchText můžete předat vyhledávací dotaz, zatímco ve vlastnosti filtru třídy SearchOptions předáte výraz filtru. Pokud chcete filtrovat bez hledání, stačí předat "*"searchText parametr metody hledání . Pokud chcete hledat bez filtrování, nechejte filter vlastnost nenasazenou nebo vůbec nepředávejte SearchOptions instanci.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript k vytvoření, načtení a dotazování vyhledávacího indexu pro vyhledávání full-text, označovaného také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• Node.js 20 LTS nebo novější.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Přejděte do složky rychlý start.

   cd azure-search-javascript-samples/quickstart-keyword-search
   

3. Nahraďte v sample.env zástupnou hodnotu SEARCH_API_ENDPOINT adresou URL, kterou jste získali v Get endpoint.

4. Přejmenujte sample.env na .env.

   mv sample.env .env
   

5. Nainstalujte závislosti.

   npm install
   

   Po dokončení instalace by se měla v adresáři projektu zobrazit node_modules složka.

6. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

Aplikaci spusťte.

node index.js

Výstup

Výstup by měl vypadat přibližně takto:

Running Azure AI Search Javascript quickstart...
Checking if index exists...
Deleting index...
Creating index...
Index named hotels-quickstart-js has been created.
Uploading documents...
Index operations succeeded: true
Querying the index...

Query #1 - search everything:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}
Result count: 4

Query #2 - search with filter, orderBy, and select:
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}

Query #3 - limit searchFields:
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #4 - limit searchFields and use facets:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}

Query #5 - Lookup document:
HotelId: 3; HotelName: Gastronomic Landscape Hotel

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření vyhledávacího klienta
2. Vytvoření indexu vyhledávání
3. Nahrání dokumentů do indexu
4. Dotazování indexu

Vytvoření vyhledávacího klienta

V index.jsaplikaci vytvoříte dva klienty:

• SearchIndexClient vytvoří index.
• SearchClient načte a dotazuje existující index.

Oba klienti vyžadují koncový bod služby a přihlašovací údaje pro ověřování. V tomto rychlém startu použijete DefaultAzureCredential pro ověřování bez klíčů pomocí Microsoft Entra ID.

const credential = new DefaultAzureCredential();
const indexClient = new SearchIndexClient(endpoint, credential);

Vytvoření indexu vyhledávání

V tomto rychlém startu vytvoříte index hotelů, na který načítáte hotelová data a provádíte dotazy. V tomto kroku importujete definici indexu ze souboru JSON a vytvoříte index ve vyhledávací službě.

Soubor hotels_quickstart_index.json definuje schéma indexu, včetně polí a jejich atributů. Každé pole je identifikováno pomocí name a má zadané type. Každé pole má také řadu atributů indexu, které určují, zda může Azure AI Vyhledávač prohledávat, filtrovat, řadit a vytvářet fasety na základě pole. Většina polí je jednoduchých datových typů, ale některé, například Address, jsou komplexní typy, které umožňují vytvářet bohaté datové struktury v indexu. Můžete si přečíst více o podporovaných typech dat a atributech indexu popsaných v Vytvořit index (REST).

Následující kód naimportuje hotels_quickstart_index.json na začátek index.js, aby hlavní funkce mohla přistupovat k definici indexu.

const indexDefinition = require('./hotels_quickstart_index.json');

Tento rychlý start odstraní index, pokud už existuje, což je běžný postup pro testovací nebo ukázkový kód. Následující funkce se pokusí odstranit index.

async function deleteIndexIfExists(indexClient, indexName) {
    try {
        await indexClient.deleteIndex(indexName);
        console.log('Deleting index...');
    } catch {
        console.log('Index does not exist yet.');
    }
}

Následující kód extrahuje název indexu z definice indexu a předá indexName spolu s indexClient do funkce deleteIndexIfExists().

const indexName = indexDefinition["name"];

console.log('Checking if index exists...');
await deleteIndexIfExists(indexClient, indexName);

Potom vytvoříte index s metodou createIndex() .

console.log('Creating index...');
let index = await indexClient.createIndex(indexDefinition);

console.log(`Index named ${index.name} has been created.`);

Nahrání dokumentů do indexu

V Azure AI Vyhledávač jsou dokumenty datové struktury, které jsou vstupy indexování a výstupy z dotazů. Tato data můžete odeslat do indexu nebo použít indexer. V tomto rychlém průvodci odesíláte dokumenty do indexu pomocí programu.

Vstupy dokumentů můžou být řádky v databázi, objekty blob v Azure Blob Storage nebo dokumenty JSON na disku, jak je uvedeno v tomto rychlém startu. indexDefinition Podobně jako hotels.json, jej naimportujete v horní části index.js, aby k datům bylo možné přistupovat v hlavní funkci.

const hotelData = require('./hotels.json');

Pokud chcete data indexovat do vyhledávacího indexu, vytvořte SearchClient. Při SearchIndexClient vytváření a správě indexu SearchClient nahrává dokumenty a dotazuje se na index.

Tento rychlý start získá pomocí , který používá getSearchClient a znovu použije stejné přihlašovací údaje.

const searchClient = indexClient.getSearchClient(indexName);

Následující kód nahraje dokumenty do indexu vyhledávání pomocí mergeOrUploadDocuments() metody, která dokumenty nahraje nebo je sloučí s existujícím dokumentem, pokud dokument se stejným klíčem již existuje.

console.log('Uploading documents...');
let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);

console.log(`Index operations succeeded: ${JSON.stringify(indexDocumentsResult.results[0].succeeded)}`);

Dotazování indexu

Když jste vytvořili index a nahráli jste dokumenty, můžete do indexu odesílat dotazy. V této části se do indexu vyhledávání odešle pět různých dotazů, které vám předvádějí různé funkce dotazů.

Dotazy jsou zapsány ve funkci sendQueries(), která je volána v hlavní funkci následujícím způsobem.

await sendQueries(searchClient);

Metoda search()searchClient odesílá dotazy. Prvním parametrem je hledaný text a druhý parametr určuje možnosti hledání.

Příklad dotazu 1

První dotaz vyhledá *, což je ekvivalent pro hledání všeho a vybere tři pole v indexu. Osvědčeným postupem je zahrnovat pouze pole, která potřebujete, protože zahrnování nepotřebných dat může do dotazů přidat latenci.

Pro searchOptions tento dotaz je includeTotalCount také nastavena true hodnota, která vrátí počet nalezených odpovídajících výsledků.

async function sendQueries(searchClient) {
    console.log('Query #1 - search everything:');
    let searchOptions = {
        includeTotalCount: true,
        select: ["HotelId", "HotelName", "Rating"]
    };

    let searchResults = await searchClient.search("*", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log(`Result count: ${searchResults.count}`);

    // remaining queries go here
}

Zbývající níže uvedené dotazy by se také měly přidat do sendQueries() funkce. Jsou zde odděleny pro čitelnost.

Příklad dotazu 2

Další dotaz určuje hledaný termín "wifi" a obsahuje filtr, který vrátí pouze výsledky, ve kterých je stav roven 'FL'. Výsledky jsou také seřazeny podle atributu hotelu Rating. Filtr je booleovský výraz vyhodnocovaný nad filtrovatelnými poli v indexu. Dotazy filtrování zahrnují nebo vylučují hodnoty. Proto neexistuje žádné skóre relevance přidružené k dotazu filtru.

console.log('Query #2 - Search with filter, orderBy, and select:');
let state = 'FL';
searchOptions = {
    filter: odata`Address/StateProvince eq ${state}`,
    orderBy: ["Rating desc"],
    select: ["HotelId", "HotelName", "Rating"]
};

searchResults = await searchClient.search("wifi", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 3

Třetí dotaz omezuje hledání na jedno prohledávatelné pole pomocí parametru searchFields . Tento přístup je skvělou možností, jak zefektivnit dotaz, pokud víte, že vás zajímají jenom shody v určitých polích.

console.log('Query #3 - Limit searchFields:');
searchOptions = {
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("sublime cliff", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 4

Další běžnou možností zahrnutí do dotazu je facets. Facety umožňují vytvářet filtry ve vašem uživatelském rozhraní, takže uživatelé snadno zjistí, na jaké hodnoty mohou filtrovat. Tento dotaz také omezuje vyhledávání na HotelName pole.

console.log('Query #4 - limit searchFields and use facets:');
searchOptions = {
    facets: ["Category"],
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 5

Poslední dotaz používá getDocument() metodu searchClient. Díky tomu můžete dokument efektivně načíst podle jeho klíče.

console.log('Query #5 - Lookup document:');
let documentResult = await searchClient.getDocument(key='3')
console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`)

Souhrn dotazů

Předchozí dotazy zobrazují v dotazu několik způsobů párování termínů: fulltextové vyhledávání, filtry a vyhledávání dokumentů.

Metoda searchClient.search provádí fulltextové vyhledávání a filtry. V řetězci searchText můžete předat vyhledávací dotaz, zatímco ve vlastnosti filter třídy předáte výraz SearchOptions filtru. Pokud chcete filtrovat bez hledání, stačí předat "*" jako searchText parametr metody search. Pokud chcete hledat bez filtrování, nechejte filter vlastnost nenasazenou nebo vůbec nepředávejte SearchOptions instanci.

V tomto rychlém startu použijete klientskou knihovnu Azure AI Vyhledávač pro Python k vytvoření, načtení a dotazování vyhledávacího indexu pro vyhledávání full-text označované také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• Python 3.8 nebo novější.

• Visual Studio Code s rozšířeními Python a Jupyter.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. Přejděte do složky rychlý start a otevřete ji v Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Keyword-Search
   code .
   

3. Otevřít azure-search-quickstart.ipynb.

4. Stiskněte Kombinaci kláves Ctrl+Shift+P, vyberte Poznámkový blok: Vyberte jádro poznámkového bloku a podle pokynů vytvořte virtuální prostředí.

   Po dokončení by se měla v adresáři projektu zobrazit .venv složka.

5. Spuštěním první buňky kódu nainstalujte požadované balíčky.

6. Ve druhé buňce kódu nahraďte zástupnou hodnotu search_endpoint adresou URL, kterou jste získali v koncovém bodu Get, a spusťte buňku.

7. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

Spusťte zbývající buňky kódu jednu po druhé, abyste vytvořili index, nahráli dokumenty a provedli dotaz na index.

Výstup

Každá buňka kódu vytiskne svůj výstup do poznámkového bloku. Následující příklad je výstupem prvního dotazu, prázdné vyhledávání, které vrátí všechny dokumenty v indexu.

Total Documents Matching Query: 4
1.0
Gastronomic Landscape Hotel
['restaurant', 'bar', 'continental breakfast']
Description: The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.
1.0
Old Century Hotel
['pool', 'free wifi', 'concierge']
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. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
1.0
Sublime Palace Hotel
['concierge', 'view', 'air conditioning']
Description: Sublime Palace 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 19th century resort, updated for every modern convenience.
1.0
Stay-Kay City Hotel
['view', 'air conditioning', 'concierge']
Description: This classic hotel is fully-refurbished and 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.

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření klientů
2. Vytvoření indexu vyhledávání
3. Nahrání dokumentů do indexu
4. Dotazování indexu
5. Odebrání indexu

Vytvoření klientů

Poznámkový blok vytvoří dva klienty:

• SearchIndexClient vytváří a spravuje indexy.
• SearchClient načte dokumenty a spouští dotazy.

Oba klienti vyžadují koncový bod služby a přihlašovací údaje. V tomto rychlém startu použijete DefaultAzureCredential pro ověřování bez klíčů pomocí Microsoft Entra ID.

Vytvoření indexu vyhledávání

V tomto rychlém startu vytvoříte index hotelů, na který načtete data hotelů a spustíte dotazy. V tomto kroku definujete pole v indexu. Každá definice pole obsahuje název, datový typ a atributy, které určují způsob použití pole.

Poznámkový blok používá SimpleField, SearchableField a ComplexField z balíčku modelů k definování schématu. Můžete si přečíst více o podporovaných typech dat a atributech indexu popsaných v Vytvořit index (REST).

# Create a search schema
index_client = SearchIndexClient(
    endpoint=search_endpoint, credential=credential)
fields = [
        SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True),
        SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
        SearchableField(name="Description", type=SearchFieldDataType.String, analyzer_name="en.lucene"),
        SearchableField(name="Category", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),

        SearchableField(name="Tags", collection=True, type=SearchFieldDataType.String, facetable=True, filterable=True),

        SimpleField(name="ParkingIncluded", type=SearchFieldDataType.Boolean, facetable=True, filterable=True, sortable=True),
        SimpleField(name="LastRenovationDate", type=SearchFieldDataType.DateTimeOffset, facetable=True, filterable=True, sortable=True),
        SimpleField(name="Rating", type=SearchFieldDataType.Double, facetable=True, filterable=True, sortable=True),

        ComplexField(name="Address", fields=[
            SearchableField(name="StreetAddress", type=SearchFieldDataType.String),
            SearchableField(name="City", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="StateProvince", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="PostalCode", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="Country", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
        ])
    ]

scoring_profiles = []
suggester = [{'name': 'sg', 'source_fields': ['Tags', 'Address/City', 'Address/Country']}]

# Create the search index=
index = SearchIndex(name=index_name, fields=fields, suggesters=suggester, scoring_profiles=scoring_profiles)
result = index_client.create_or_update_index(index)
print(f' {result.name} created')

Nahrání dokumentů do indexu

Azure AI Vyhledávač prohledá obsah uložený ve službě. V tomto kroku načtete dokumenty JSON, které odpovídají indexu hotelu, který jste vytvořili.

V Azure AI Vyhledávač jsou dokumenty datové struktury, které jsou vstupy indexování a výstupy z dotazů. Poznámkový blok definuje datový obsah dokumentů jako seznam slovníků, které obsahují hotelová data.

# Create a documents payload
documents = [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Stay-Kay City Hotel",
    "Description": "This classic hotel is fully-refurbished and 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.",
    "Category": "Boutique",
    "Tags": [ "view", "air conditioning", "concierge" ],
    "ParkingIncluded": "false",
    "LastRenovationDate": "2020-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": "Old Century Hotel",
    "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. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge" ],
    "ParkingIncluded": "false",
    "LastRenovationDate": "2019-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": "Gastronomic Landscape Hotel",
    "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
    "Category": "Suite",
    "Tags": [ "restaurant", "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 Palace Hotel",
    "Description": "Sublime Palace 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 19th century resort, updated for every modern convenience.",
    "Category": "Boutique",
    "Tags": [ "concierge", "view", "air conditioning" ],
    "ParkingIncluded": "true",
    "LastRenovationDate": "2020-02-06T00:00:00Z",
    "Rating": 4.60,
    "Address": {
        "StreetAddress": "7400 San Pedro Ave",
        "City": "San Antonio",
        "StateProvince": "TX",
        "PostalCode": "78216",
        "Country": "USA"
        }
    }
]

Metoda upload_documents přidá dokumenty do indexu, vytvoří je, pokud neexistují nebo je aktualizují, pokud ano.

search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

try:
    result = search_client.upload_documents(documents=documents)
    print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
    print (ex.message)

Dotazování indexu

Výsledky dotazu můžete získat hned po indexování prvního dokumentu, ale skutečné testování indexu by mělo počkat na indexování všech dokumentů.

Ke spouštění dotazů použijte metodu searchSearchClient .

Ukázkové dotazy v poznámkovém bloku ukazují běžné vzory:

• Prázdné hledání: Provede prázdné hledání (search_text="*"), vrátí nehodnocený seznam (skóre hledání = 1,0) libovolných dokumentů. Vzhledem k tomu, že neexistují žádná kritéria, jsou ve výsledcích zahrnuty všechny dokumenty.

• Hledání termínů: Přidá do hledaného výrazu celé termíny (search_text="wifi"). Tento dotaz určuje, že výsledky obsahují pouze tato pole v parametru select . Omezení polí, která se vrátí, minimalizuje množství dat odesílaných zpět přes drát a snižuje latenci vyhledávání.

• Filtrované vyhledávání: Přidá výraz filtru, který vrátí pouze ty hotely s hodnocením větším než čtyři, seřazené sestupně.

• Hledání ve specifických polích: Přidá search_fields do rozsahu provádění dotazu na specifická pole.

• Fasetové vyhledávání: Generuje facety pro kladné shody nalezené ve výsledcích vyhledávání. Neexistují žádné nulové shody. Pokud výsledky hledání neobsahují termín "wifi", nezobrazí se "wifi" ve fasetové navigační struktuře.

• Vyhledávání dokumentu: Vyhledá dokument podle jeho klíče. Tato operace je užitečná, pokud chcete poskytnout podrobnou analýzu, když uživatel vybere položku ve výsledku hledání.

• Automatické dokončování: Poskytuje potenciální shody, zatímco uživatelé píší do vyhledávacího pole. Automatické dokončování používá modul pro návrhy (sg) ke zjištění, která pole obsahují potenciální shody pro žádosti s návrhy. V tomto rychlém startu jsou tato pole Tags, Address/City a Address/Country. Pokud chcete simulovat automatické dokončování, předejte písmena "sa" jako částečný řetězec. Metoda autocomplete vrací potenciální shody pro termín SearchClient.

Odebrání indexu

Pokud jste s tímto indexem hotovi, můžete ho odstranit spuštěním buňky kódu Clean up. Odstranění nepotřebných indexů uvolní místo pro procházení dalších rychlých návodů a kurzů.

try:
    result = index_client.delete_index(index_name)
    print ('Index', index_name, 'Deleted')
except Exception as ex:
    print (ex)

V tomto rychlém průvodci použijete klientskou knihovnu Azure AI Vyhledávač pro JavaScript (kompatibilní s TypeScriptem) k vytvoření, načtení a dotazování vyhledávacího indexu pro fulltextové vyhledávání, označované také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• Node.js 20 LTS nebo novější, aby se spustil zkompilovaný kód.

• Kompilujte TypeScript do JavaScriptu pomocí TypeScriptu.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. Přejděte do složky rychlý start.

   cd azure-search-javascript-samples/quickstart-keyword-search
   

3. Nahraďte v sample.env zástupnou hodnotu SEARCH_API_ENDPOINT adresou URL, kterou jste získali v Get endpoint.

4. Přejmenujte sample.env na .env.

   mv sample.env .env
   

5. Nainstalujte závislosti.

   npm install
   npm install typescript @types/node --save-dev
   npm pkg set type=module
   

   Po dokončení instalace by se měla v adresáři projektu zobrazit node_modules složka.

6. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

Spuštění kódu

Ukázkový kód ve výchozím nastavení používá JavaScript. Spuštění kódu pomocí TypeScriptu:

1. Vytvořte soubor s názvem tsconfig.jsona vložte do něj následující kód.

   {
     "compilerOptions": {
       "module": "NodeNext",
       "target": "ES2022",
       "moduleResolution": "NodeNext",
       "skipLibCheck": true,
       "strict": true,
       "resolveJsonModule": true
     },
     "include": ["*.ts"],
     "exclude": ["node_modules"]
   }
   

2. index.js Přejmenujte soubor na index.tsa pak nahraďte obsah následujícím kódem. Tento kód převede syntaxi CommonJS na importy modulů ES, které jsou vyžadovány pro kompilaci TypeScriptu.

   // Import from the @azure/search-documents library
   import {
       SearchIndexClient,
       SearchClient,
       SearchFieldDataType,
       odata,
       SearchIndex
   } from "@azure/search-documents";
   
   // Import from the Azure Identity library
   import { DefaultAzureCredential } from "@azure/identity";
   
   // Importing the hotels sample data
   import hotelData from './hotels.json' with { type: "json" };
   
   // Load the .env file if it exists
   import "dotenv/config";
   
   // Defining the index definition
   const indexDefinition: SearchIndex = {
   	"name": "hotels-quickstart",
   	"fields": [
   		{
   			"name": "HotelId",
   			"type": "Edm.String" as SearchFieldDataType,
   			"key": true,
   			"filterable": true
   		},
   		{
   			"name": "HotelName",
   			"type": "Edm.String" as SearchFieldDataType,
   			"searchable": true,
   			"filterable": false,
   			"sortable": true,
   			"facetable": false
   		},
   		{
   			"name": "Description",
   			"type": "Edm.String" as SearchFieldDataType,
   			"searchable": true,
   			"filterable": false,
   			"sortable": false,
   			"facetable": false,
   			"analyzerName": "en.lucene"
   		},
   		{
   			"name": "Category",
   			"type": "Edm.String" as SearchFieldDataType,
   			"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" as SearchFieldDataType,
   					"filterable": false,
   					"sortable": false,
   					"facetable": false,
   					"searchable": true
   				},
   				{
   					"name": "City",
   					"type": "Edm.String" as SearchFieldDataType,
   					"searchable": true,
   					"filterable": true,
   					"sortable": true,
   					"facetable": true
   				},
   				{
   					"name": "StateProvince",
   					"type": "Edm.String" as SearchFieldDataType,
   					"searchable": true,
   					"filterable": true,
   					"sortable": true,
   					"facetable": true
   				},
   				{
   					"name": "PostalCode",
   					"type": "Edm.String" as SearchFieldDataType,
   					"searchable": true,
   					"filterable": true,
   					"sortable": true,
   					"facetable": true
   				},
   				{
   					"name": "Country",
   					"type": "Edm.String" as SearchFieldDataType,
   					"searchable": true,
   					"filterable": true,
   					"sortable": true,
   					"facetable": true
   				}
   			]
   		}
   	],
   	"suggesters": [
   		{
   			"name": "sg",
   			"searchMode": "analyzingInfixMatching",
   			"sourceFields": [
   				"HotelName"
   			]
   		}
   	]
   };
   
   async function main() {
   
   	// Your search service endpoint (from .env file)
   	const searchServiceEndpoint = process.env.SEARCH_API_ENDPOINT || "";
   
   	// Use the recommended keyless credential instead of the AzureKeyCredential credential.
   	const credential = new DefaultAzureCredential();
   	//const credential = new AzureKeyCredential(Your search service admin key);
   
   	// Create a SearchIndexClient to send create/delete index commands
   	const searchIndexClient: SearchIndexClient = new SearchIndexClient(
   		searchServiceEndpoint,
   		credential
   	);
   
   	// Creating a search client to upload documents and issue queries
   	const indexName: string  = "hotels-quickstart";
       const searchClient: SearchClient<any> = searchIndexClient.getSearchClient(indexName);
   
       console.log('Checking if index exists...');
       await deleteIndexIfExists(searchIndexClient, indexName);
   
       console.log('Creating index...');
       let index: SearchIndex = await searchIndexClient.createIndex(indexDefinition);
       console.log(`Index named ${index.name} has been created.`);
   
       console.log('Uploading documents...');
       let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);
       console.log(`Index operations succeeded: ${JSON.stringify(indexDocumentsResult.results[0].succeeded)} `);
   
       // waiting one second for indexing to complete (for demo purposes only)
       await sleep(1000);
   
       console.log('Querying the index...');
       console.log();
       await sendQueries(searchClient);
   }
   
   async function deleteIndexIfExists(searchIndexClient: SearchIndexClient, indexName: string) {
       try {
           await searchIndexClient.deleteIndex(indexName);
           console.log('Deleting index...');
       } catch {
           console.log('Index does not exist yet.');
       }
   }
   
   async function sendQueries(searchClient: SearchClient<any>) {
       // Query 1
       console.log('Query #1 - search everything:');
       let searchOptions: any = {
           includeTotalCount: true,
           select: ["HotelId", "HotelName", "Rating"]
       };
   
       let searchResults = await searchClient.search("*", searchOptions);
       for await (const result of searchResults.results) {
           console.log(`${JSON.stringify(result.document)}`);
       }
       console.log(`Result count: ${searchResults.count}`);
       console.log();
   
   
       // Query 2
       console.log('Query #2 - search with filter, orderBy, and select:');
       let state = 'FL';
       searchOptions = {
           filter: odata`Address/StateProvince eq ${state}`,
           orderBy: ["Rating desc"],
           select: ["HotelId", "HotelName", "Rating"]
       };
   
       searchResults = await searchClient.search("wifi", searchOptions);
       for await (const result of searchResults.results) {
           console.log(`${JSON.stringify(result.document)}`);
       }
       console.log();
   
       // Query 3
       console.log('Query #3 - limit searchFields:');
       searchOptions = {
           select: ["HotelId", "HotelName", "Rating"],
           searchFields: ["HotelName"]
       };
   
       searchResults = await searchClient.search("sublime palace", searchOptions);
       for await (const result of searchResults.results) {
           console.log(`${JSON.stringify(result.document)}`);
       }
       console.log();
   
       // Query 4
       console.log('Query #4 - limit searchFields and use facets:');
       searchOptions = {
           facets: ["Category"],
           select: ["HotelId", "HotelName", "Rating"],
           searchFields: ["HotelName"]
       };
   
       searchResults = await searchClient.search("*", searchOptions);
       for await (const result of searchResults.results) {
           console.log(`${JSON.stringify(result.document)}`);
       }
       console.log();
   
       // Query 5
       console.log('Query #5 - Lookup document:');
       let documentResult = await searchClient.getDocument('3');
       console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`);
       console.log();
   }
   
   function sleep(ms: number) {
       return new Promise(resolve => setTimeout(resolve, ms));
   }
   
   main().catch((err) => {
       console.error("The sample encountered an error:", err);
   });
   

3. Transpilovat z TypeScriptu do JavaScriptu.

   npx tsc
   

4. Aplikaci spusťte.

   node index.js
   

Výstup

Výstup by měl vypadat přibližně takto:

Checking if index exists...
Deleting index...
Creating index...
Index named hotels-quickstart has been created.
Uploading documents...
Index operations succeeded: true 
Querying the index...

Query #1 - search everything:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}
Result count: 4

Query #2 - search with filter, orderBy, and select:
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}

Query #3 - limit searchFields:
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #4 - limit searchFields and use facets:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}

Query #5 - Lookup document:
HotelId: 3; HotelName: Gastronomic Landscape Hotel

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření vyhledávacího klienta
2. Vytvoření indexu vyhledávání
3. Nahrání dokumentů do indexu
4. Dotazování indexu

Vytvoření vyhledávacího klienta

V index.tsaplikaci vytvoříte dva klienty:

• SearchIndexClient vytvoří index.
• SearchClient načte a dotazuje existující index.

Oba klienti vyžadují koncový bod služby a přihlašovací údaje pro ověřování. V tomto rychlém startu použijete DefaultAzureCredential pro ověřování bez klíčů pomocí Microsoft Entra ID.

const credential = new DefaultAzureCredential();
const searchIndexClient: SearchIndexClient = new SearchIndexClient(
    searchServiceEndpoint,
    credential
);

Vytvoření indexu vyhledávání

V tomto rychlém startu vytvoříte index hotelů, na který načítáte hotelová data a provádíte dotazy. V tomto kroku definujete pole v indexu.

Objekt indexDefinition definuje, jak Azure AI Vyhledávač funguje s dokumenty, které načtete v dalším kroku. Každé pole je identifikováno pomocí name a má zadané type. Každé pole má také řadu atributů indexu, které určují, zda může Azure AI Vyhledávač prohledávat, filtrovat, řadit a vytvářet fasety na základě pole. Většina polí je jednoduchých datových typů, ale některé, například Address, jsou komplexní typy, které umožňují vytvářet bohaté datové struktury v indexu. Můžete si přečíst více o podporovaných typech dat a atributech indexu popsaných v Vytvořit index (REST).

const indexDefinition: SearchIndex = {
    "name": "hotels-quickstart",
    "fields": [
        {
            "name": "HotelId",
            "type": "Edm.String" as SearchFieldDataType,
            "key": true,
            "filterable": true
        },
        {
            "name": "HotelName",
            "type": "Edm.String" as SearchFieldDataType,
            "searchable": true,
            "filterable": false,
            "sortable": true,
            "facetable": false
        },
        // REDACTED FOR BREVITY
    ],
    "suggesters": [
        {
            "name": "sg",
            "searchMode": "analyzingInfixMatching",
            "sourceFields": ["HotelName"]
        }
    ]
};

Tento rychlý start odstraní index, pokud už existuje, což je běžný postup pro testovací nebo ukázkový kód.

async function deleteIndexIfExists(searchIndexClient: SearchIndexClient, indexName: string) {
    try {
        await searchIndexClient.deleteIndex(indexName);
        console.log('Deleting index...');
    } catch {
        console.log('Index does not exist yet.');
    }
}

Potom se index vytvoří pomocí createIndex() metody.

let index: SearchIndex = await searchIndexClient.createIndex(indexDefinition);

Nahrání dokumentů do indexu

V Azure AI Vyhledávač jsou dokumenty datové struktury, které jsou vstupy indexování a výstupy z dotazů. Tato data můžete odeslat do indexu nebo použít indexer. V tomto rychlém průvodci odesíláte dokumenty do indexu pomocí programu.

Vstupy dokumentů můžou být řádky v databázi, objekty blob v Azure Blob Storage nebo dokumenty JSON na disku, jak je uvedeno v tomto rychlém startu. Data hotelu se naimportují v horní části souboru.

import hotelData from './hotels.json' with { type: "json" };

Pokud chcete data indexovat do vyhledávacího indexu, vytvořte SearchClient. Při SearchIndexClient vytváření a správě indexu SearchClient nahrává dokumenty a dotazuje se na index.

Tento rychlý start získá pomocí , který používá getSearchClient a znovu použije stejné přihlašovací údaje.

const searchClient: SearchClient<any> = searchIndexClient.getSearchClient(indexName);

Metoda mergeOrUploadDocuments() nahraje dokumenty nebo je sloučí s existujícím dokumentem, pokud už existuje dokument se stejným klíčem.

let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);

Dotazování indexu

Když jste vytvořili index a nahráli jste dokumenty, můžete do indexu odesílat dotazy. V této části se do indexu vyhledávání odešle pět různých dotazů, které vám předvádějí různé funkce dotazů.

Dotazy se zapisují do sendQueries() funkce, která je volána v hlavní funkci.

await sendQueries(searchClient);

Dotazy se odesílají pomocí search() metody searchClient. Prvním parametrem je hledaný text a druhý parametr určuje možnosti hledání.

Příklad dotazu 1

První dotaz vyhledá *, což je ekvivalent pro hledání všeho a vybere tři pole v indexu. Osvědčeným postupem je zahrnovat pouze pole, která potřebujete, protože zahrnování nepotřebných dat může do dotazů přidat latenci.

Pro searchOptions tento dotaz je includeTotalCount také nastavena true hodnota, která vrátí počet nalezených odpovídajících výsledků.

console.log('Query #1 - search everything:');
let searchOptions: any = {
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Rating"]
};

let searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}
console.log(`Result count: ${searchResults.count}`);

Příklad dotazu 2

V dalším dotazu je hledaný termín "wifi" zadán filtrem, který vrátí pouze výsledky, ve kterých je stav roven 'FL'. Výsledky jsou také seřazeny podle atributu hotelu Rating.

console.log('Query #2 - search with filter, orderBy, and select:');
let state = 'FL';
searchOptions = {
    filter: odata`Address/StateProvince eq ${state}`,
    orderBy: ["Rating desc"],
    select: ["HotelId", "HotelName", "Rating"]
};

searchResults = await searchClient.search("wifi", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 3

Hledání je omezeno na jedno prohledávatelné pole pomocí parametru searchFields . Tento přístup je skvělou možností, jak zefektivnit dotaz, pokud víte, že vás zajímají jenom shody v určitých polích.

console.log('Query #3 - limit searchFields:');
searchOptions = {
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("sublime palace", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 4

Další běžnou možností zahrnutí do dotazu je facets. Facety umožňují zajištění samoobslužného podrobného zkoumání dat z výsledků v uživatelském rozhraní. Výsledky omezujících vlastností se dají v podokně výsledků převést na zaškrtávací políčka.

console.log('Query #4 - limit searchFields and use facets:');
searchOptions = {
    facets: ["Category"],
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Příklad dotazu 5

Poslední dotaz používá getDocument() metodu searchClient. Díky tomu můžete dokument efektivně načíst podle jeho klíče.

console.log('Query #5 - Lookup document:');
let documentResult = await searchClient.getDocument('3');
console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`);

Souhrn dotazů

Předchozí dotazy zobrazují v dotazu několik způsobů párování termínů: fulltextové vyhledávání, filtry a vyhledávání dokumentů.

Metoda searchClient.search provádí fulltextové vyhledávání a filtry. V řetězci searchText můžete předat vyhledávací dotaz, zatímco ve vlastnosti filter třídy předáte výraz SearchOptions filtru. Pokud chcete filtrovat bez hledání, stačí předat "*" jako searchText parametr metody search. Pokud chcete hledat bez filtrování, nechejte filter vlastnost nenasazenou nebo vůbec nepředávejte SearchOptions instanci.

V tomto rychlém startu použijete rozhraní REST API Azure AI Vyhledávač k vytvoření, načtení a dotazování indexu vyhledávání pro vyhledávání full-text označovaného také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• Visual Studio Code s rozšířením klienta REST.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. Přejděte do složky rychlý start a otevřete ji v Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-keyword-search
   code .
   

3. Nahraďte v az-search-quickstart.rest zástupnou hodnotu @baseUrl adresou URL, kterou jste získali v Get endpoint.

4. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

5. Pro ověřování bez klíčů pomocí Microsoft Entra ID vygenerujte přístupový token.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
   

6. Nahraďte zástupnou hodnotu @token tokenem z předchozího kroku.

Spuštění kódu

1. V části ### List existing indexes by nameVyberte Odeslat žádost a ověřte připojení.

   V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující indexy, jsou uvedené. V opačném případě je seznam prázdný. Pokud je kód HTTP 200 OK, můžete pokračovat.

2. Odeslání zbývajících požadavků postupně za účelem vytvoření indexu, nahrání dokumentů a dotazování indexu.

Výstup

Každý požadavek vrátí jiný JSON na základě operace. Výstup klíče je z ### Run a query, který by měl vypadat nějak takto:

{
  "value": [
    {
      "@search.score": 0.5575875,
      "HotelId": "3",
      "HotelName": "Gastronomic Landscape Hotel",
      "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
      "Tags": [
        "restaurant",
        "bar",
        "continental breakfast"
      ]
    }
  ]
}

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření indexu vyhledávání
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vyhledávání

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje. Index je koncepčně podobný tabulce v relační databázi, ale je speciálně navržený pro operace hledání, jako je fulltextové vyhledávání.

Tento úvod do používání zavolá indexy – vytvoření (REST API) k sestavení vyhledávacího indexu s názvem hotels-quickstart a jeho fyzických datových struktur ve vaší vyhledávací službě.

Kolekce fields ve schématu indexu definuje strukturu hotelových dokumentů. Každé pole obsahuje namedata typea atributy, které určují jeho chování při indexování a dotazech. Pole HotelId je označené jako klíč, který Azure AI Vyhledávač vyžaduje jedinečnou identifikaci každého dokumentu v indexu.

### Create a new index
POST {{baseUrl}}/indexes?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "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}
            ]
        }
    ]
}

Klíčové body schématu indexu:

• Pomocí řetězcových polí (Edm.String) můžete číselná data prohledávat fulltextově. Jiné podporované datové typy, jako například Edm.Int32, jsou filtrovatelné, řaditelné, fasetovatelné a načitatelné, ale nedají se prohledávat.

• Většina polí je jednoduchých datových typů, ale můžete definovat složité typy, které představují vnořená data, například Address pole.

• Atributy polí určují povolené akce. Rozhraní REST API ve výchozím nastavení umožňují mnoho akcí. Například všechny řetězce jsou prohledávatelné a dohledatelné. S rozhraními REST API můžete používat pouze atributy, pokud potřebujete zakázat chování.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý začátek poskytuje ukázkové hotelové dokumenty jako vložený JSON. V produkčních scénářích se ale obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Tento rychlý start volá dokumenty – index (REST API) pro přidání čtyř ukázkových hotelových dokumentů do indexu. V porovnání s předchozím požadavkem je identifikátor URI rozšířen tak, aby zahrnoval kolekci docs a index operaci.

Každý dokument v value poli představuje hotel a obsahuje pole, která odpovídají schématu indexu. Parametr @search.action určuje operaci, která se má provést pro každý dokument. Tento příklad používá upload, který přidá dokument, pokud neexistuje nebo aktualizuje dokument, pokud existuje.

### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "upload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is fully-refurbished and 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.",
            "Category": "Boutique",
            "Tags": [ "view", "air conditioning", "concierge" ],
            "ParkingIncluded": false,
            "LastRenovationDate": "2022-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": "Old Century Hotel",
            "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. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
            "Category": "Boutique",
            "Tags": [ "pool", "free wifi", "concierge" ],
            "ParkingIncluded": false,
            "LastRenovationDate": "2019-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": "Gastronomic Landscape Hotel",
            "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
            "Category": "Suite",
            "Tags": [ "restaurant", "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 Palace Hotel",
            "Description": "Sublime Palace 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 19th century resort, updated for every modern convenience.",
            "Tags": [ "concierge", "view", "air conditioning" ],
            "ParkingIncluded": true,
            "LastRenovationDate": "2020-02-06T00:00:00Z",
            "Rating": 4.60,
            "Address": 
            {
                "StreetAddress": "7400 San Pedro Ave",
                "City": "San Antonio",
                "StateProvince": "TX",
                "PostalCode": "78216",
                "Country": "USA"
            }
        }
    ]
}

Dotazování indexu

Teď, když jsou dokumenty načtené do indexu, můžete pomocí fulltextového vyhledávání vyhledat konkrétní termíny nebo fráze v jejich polích.

Tento rychlý start volá dokumenty – vyhledávací příspěvek (REST API) k vyhledání hotelových dokumentů, které odpovídají vašim kritériím hledání. Identifikátor URI teď cílí na /docs/search operaci.

Požadavky fulltextového vyhledávání vždy obsahují search parametr, který obsahuje text dotazu. Text dotazu může obsahovat jeden nebo více termínů, frází nebo operátorů. Kromě searchtoho můžete zadat další parametry, které upřesní chování hledání a výsledky.

Dotaz vyhledá termíny "připojená restaurace" v Description polích Tags každého hotelového dokumentu. Parametr select omezuje pole vrácená v odpovědi na HotelId, HotelName, Tagsa Description. Parametr count požaduje celkový počet odpovídajících dokumentů.

### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "search": "attached restaurant",
    "select": "HotelId, HotelName, Tags, Description",
    "searchFields": "Description, Tags",
    "count": true
}

V tomto rychlém startu použijete PowerShell a Azure AI Vyhledávač rozhraní REST API k vytvoření, načtení a dotazování vyhledávacího indexu pro vyhledávání full-text označovaný také jako vyhledávání klíčových slov.

Fulltextové vyhledávání používá Apache Lucene k indexování a dotazům a algoritmu řazení BM25 pro bodování výsledků. V tomto rychlém startu se používají fiktivní hotelová data z úložiště azure-search-sample-data GitHub k naplnění indexu.

Návod

Chcete začít hned? Stáhněte zdrojový kód na GitHub.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet.

• Služba Azure AI Vyhledávač. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

• PowerShell 7 nebo novější.

• Git naklonuje ukázkové úložiště.

• Azure CLI pro ověřování bez klíčů pomocí Microsoft Entra ID.

Konfigurace přístupu

Než začnete, ujistěte se, že máte oprávnění pro přístup k obsahu a operacím v Azure AI Vyhledávač. Tento rychlý start používá Microsoft Entra ID pro ověřování a přístup na základě role k autorizaci. Abyste mohli přiřadit role, musíte být vlastníkem nebo správcem uživatelských přístupů . Pokud role nejsou proveditelné, použijte místo toho ověřování založené na klíči .

Konfigurace doporučeného přístupu na základě role:

1. Povolte přístup založený na rolích pro vaši vyhledávací službu.

2. Přiřaďte k uživatelskému účtu následující role.

   • Přispěvatel vyhledávací služby

   • Přispěvatel dat indexu vyhledávání

   • Čtečka dat vyhledávacího indexu

Získání koncového bodu

Každá služba Azure AI Vyhledávač má endpoint, což je jedinečná adresa URL, která identifikuje a poskytuje síťový přístup ke službě. V další části zadáte tento koncový bod pro připojení k vyhledávací službě prostřednictvím kódu programu.

Získání koncového bodu:

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. V levém podokně vyberte Přehled.

3. Poznamenejte si koncový bod, který by měl vypadat jako https://my-service.search.windows.net.

Nastavení prostředí

1. Pomocí Gitu naklonujte ukázkové úložiště.

   git clone https://github.com/Azure-Samples/azure-search-powershell-samples
   

2. Přejděte do složky rychlý start.

   cd azure-search-powershell-samples/Quickstart
   

3. Pro ověřování bez klíčů pomocí Microsoft Entra ID se přihlaste ke svému účtu Azure. Pokud máte více předplatných, vyberte předplatné, které obsahuje vaši službu Azure AI Vyhledávač.

   az login
   

4. Nahraďte v azure-search-quickstart.ps1 zástupnou hodnotu $baseUrl adresou URL, kterou jste získali v Get endpoint.

Spuštění kódu

Spuštěním následujícího skriptu PowerShellu ve stejném terminálu spusťte tento rychlý start.

.\azure-search-quickstart.ps1

Výstup

Skript odstraní všechny existující indexy, vytvoří nový index, nahraje dokumenty a spustí několik fulltextových vyhledávacích dotazů. Výstup zobrazuje úplné požadavky HTTP a odpovědi pro každou operaci. Následující příklad ukazuje odpověď při hledání "restaurant wifi".

{
  "value": [
    {
      "@search.score": 0.6931472,
      "HotelName": "Old Century Hotel",
      "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. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
      "Tags": ["pool", "free wifi", "concierge"]
    },
    {
      "@search.score": 0.5575875,
      "HotelName": "Gastronomic Landscape Hotel",
      "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
      "Tags": ["restaurant", "bar", "continental breakfast"]
    }
  ]
}

Vysvětlení kódu

Poznámka:

Fragmenty kódu v této části mohly být upraveny pro čitelnost. Kompletní funkční příklad najdete ve zdrojovém kódu.

Teď, když kód spustíte, si pojďme rozdělit klíčové kroky:

1. Vytvoření indexu vyhledávání
2. Nahrání dokumentů do indexu
3. Dotazování indexu

Vytvoření indexu vyhledávání

Než přidáte obsah do Azure AI Vyhledávač, musíte vytvořit index, který definuje, jak se obsah ukládá a strukturuje. Index je koncepčně podobný tabulce v relační databázi, ale je speciálně navržený pro operace hledání, jako je fulltextové vyhledávání.

Tento rychlý start nejprve odstraní všechny existující indexy se stejným názvem, což je běžný postup pro testovací nebo ukázkový kód, který se spouští opakovaně.

Send-Request DELETE "$baseUrl/indexes/hotels-quickstart?api-version=2025-09-01" $headers

Tento rychlý start pak zavolá indexy – vytvoření (REST API) k vytvoření indexu vyhledávání s názvem hotels-quickstart a jeho fyzickým datovým strukturám ve vyhledávací službě.

$body = @"
{
    "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"},
        ...
    ]
}
"@

Send-RequestWithBody POST "$baseUrl/indexes?api-version=2025-09-01" $headers $body

Kolekce fields ve schématu indexu definuje strukturu hotelových dokumentů. Každé pole obsahuje namedata typea atributy, které určují jeho chování při indexování a dotazech. Pole HotelId je označené jako klíč, který Azure AI Vyhledávač vyžaduje jedinečnou identifikaci každého dokumentu v indexu.

Klíčové body schématu indexu:

• Pomocí řetězcových polí (Edm.String) můžete číselná data prohledávat fulltextově. Jiné podporované datové typy, jako například Edm.Int32, jsou filtrovatelné, řaditelné, fasetovatelné a načitatelné, ale nedají se prohledávat.

• Většina polí je jednoduchých datových typů, ale můžete definovat složité typy, které představují vnořená data, například Address pole.

• Atributy polí určují povolené akce. Rozhraní REST API ve výchozím nastavení umožňují mnoho akcí. Například všechny řetězce jsou prohledávatelné a dohledatelné. S rozhraními REST API můžete používat pouze atributy, pokud potřebujete zakázat chování.

Nahrání dokumentů do indexu

Nově vytvořené indexy jsou prázdné. Pokud chcete naplnit index a nastavit, aby byl prohledávatelný, musíte nahrát dokumenty JSON, které odpovídají schématu indexu.

V Azure AI Vyhledávač slouží dokumenty jako vstupy pro indexování a výstupy pro dotazy. Pro zjednodušení tento rychlý začátek poskytuje ukázkové hotelové dokumenty jako vložený JSON. V produkčních scénářích se ale obsah často načítá z připojených zdrojů dat a transformuje se do FORMÁTU JSON pomocí indexerů.

Tento rychlý start volá dokumenty – index (REST API) pro přidání čtyř ukázkových hotelových dokumentů do indexu. V porovnání s předchozím požadavkem je identifikátor URI rozšířen tak, aby zahrnoval kolekci docs a index operaci.

$body = @"
{
    "value": [
        {
            "@search.action": "upload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is...",
            ...
        },
        ...
    ]
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/index?api-version=2025-09-01" $headers $body

Každý dokument v value poli představuje hotel a obsahuje pole, která odpovídají schématu indexu. Parametr @search.action určuje operaci, která se má provést pro každý dokument. Tento příklad používá upload, který přidá dokument, pokud neexistuje nebo aktualizuje dokument, pokud existuje.

Dotazování indexu

Teď, když jsou dokumenty načtené do indexu, můžete pomocí fulltextového vyhledávání vyhledat konkrétní termíny nebo fráze v jejich polích.

Tento rychlý start volá dokumenty – vyhledávací příspěvek (REST API) k vyhledání hotelových dokumentů, které odpovídají vašim kritériím hledání. Identifikátor URI cílí na /docs/search operaci.

Požadavky na fulltextové vyhledávání obsahují search parametr s textem dotazu, který může obsahovat termíny, fráze nebo operátory. Dotaz prohledává všechna prohledávatelná pole v každém dokumentu. Následující příklady ukazují běžné vzory dotazů.

Příklad dotazu 1

Následující dotaz vyhledá termíny "restaurant wifi" ve všech prohledávatelných polích. Ve výchozím nastavení Azure AI Vyhledávač vrací dokumenty, které odpovídají libovolnému hledanému výrazu.

$body = @"
{
    "search": "restaurant wifi",
    "select": "HotelName, Description, Tags"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Parametr select omezuje pole vrácená v odpovědi na HotelName, Descriptiona Tags.

Příklad dotazu 2

Následující dotaz používá filter výraz k vrácení pouze hotelů s hodnocením větším než 4.

$body = @"
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName,Rating"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Parametr search je nastaven na *hodnotu , která odpovídá všem dokumentům. Parametr filter použije logickou podmínku pro zúžení výsledků.

Příklad dotazu 3

Následující dotaz vyhledá "butik" a použije top k vrácení pouze prvních dvou výsledků.

$body = @"
{
    "search": "boutique",
    "select": "HotelName,Category",
    "top": 2
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Příklad dotazu 4

Následující dotaz vyhledá "pool" a používá orderby pro seřazení výsledků sestupně pomocí Rating.

$body = @"
{
    "search": "pool",
    "select": "HotelName,Description,Tags,Rating",
    "orderby": "Rating desc"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Vyčistěte zdroje

Když pracujete ve vlastním předplatném, je vhodné dokončit projekt odebráním prostředků, které už nepotřebujete. Prostředky, které zůstaly spuštěné, vám můžou stát peníze.

Na portálu Azure vyberte Všechny prostředky nebo Zdrojové skupiny v levém podokně a vyhledejte a spravujte prostředky. Prostředky můžete odstranit jednotlivě nebo odstranit skupinu prostředků a odebrat tak všechny prostředky najednou.

Pokud používáte bezplatnou vyhledávací službu, mějte na paměti, že jste omezeni na tři indexy, indexery a zdroje dat. Jednotlivé položky na portálu můžete odstranit , abyste zůstali pod limitem.

Související obsah

• Textové vyhledávání v Azure AI Vyhledávač
• Příklady jednoduchých vyhledávacích dotazů
• Příklady úplné syntaxe vyhledávání Lucene