Kurz: Indexování z více zdrojů dat pomocí sady .NET SDK

Článek
01/17/2024

Azure AI Search může importovat, analyzovat a indexovat data z více zdrojů dat do jednoho konsolidovaného vyhledávacího indexu.

Tento kurz jazyka C# používá klientskou knihovnu Azure.Search.Documents v sadě Azure SDK pro .NET k indexování ukázkových hotelových dat z instance služby Azure Cosmos DB a slučuje je s podrobnostmi o hotelových místnostech nakreslených z dokumentů azure Blob Storage. Výsledkem je kombinovaný index vyhledávání hotelů, který obsahuje hotelové dokumenty, s místnostmi jako komplexními datovými typy.

V tomto kurzu provedete následující úlohy:

Nahrání ukázkových dat a vytvoření zdrojů dat
Identifikace klíče dokumentu
Definování a vytvoření indexu
Indexování hotelových dat ze služby Azure Cosmos DB
Sloučení dat hotelových místností z úložiště objektů blob

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Přehled

V tomto kurzu se k vytváření a spouštění více indexerů používá Azure.Search.Documents . V tomto kurzu nastavíte dva zdroje dat Azure, abyste mohli nakonfigurovat indexer, který načítá z obou zdrojů, aby se naplnil jeden index vyhledávání. Pro podporu sloučení musí mít tyto dvě sady dat společnou hodnotu. V této ukázce je toto pole ID. Pokud je pro mapování společné pole, může indexer sloučit data z různorodých prostředků: strukturovaná data z Azure SQL, nestrukturovaná data ze služby Blob Storage nebo libovolná kombinace podporovaných zdrojů dat v Azure.

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

multiple-data-sources/v11 (GitHub)

Požadavky

Poznámka:

Pro účely tohoto kurzu můžete použít bezplatnou vyhledávací službu. Úroveň Free vás omezuje na tři indexy, tři indexery a tři zdroje dat. V tomto kurzu se vytváří od každého jeden. Než začnete, ujistěte se, že máte ve službě místo pro přijetí nových prostředků.

1. Vytvoření služeb

Tento kurz používá Azure AI Search k indexování a dotazům, Azure Cosmos DB pro jednu sadu dat a Azure Blob Storage pro druhou datovou sadu.

Pokud je to možné, vytvořte všechny služby ve stejné oblasti a skupině prostředků pro blízkost a správu. V praxi můžou být vaše služby v libovolné oblasti.

Tato ukázka používá dvě malé sady dat, které popisují sedm fiktivních hotelů. Jedna sada popisuje samotné hotely a načte se do databáze Azure Cosmos DB. Druhá sada obsahuje podrobnosti o hotelové místnosti a je k dispozici jako sedm samostatných souborů JSON, které se mají nahrát do Azure Blob Storage.

Začínáme se službou Azure Cosmos DB

Přihlaste se k webu Azure Portal a přejděte na stránku Přehled účtu služby Azure Cosmos DB.
Vyberte Průzkumník dat a pak vyberte Nová databáze.
Zadejte název hotel-rooms-db. Přijměte výchozí hodnoty pro zbývající nastavení.
Vytvořte nový kontejner. Použijte existující databázi, kterou jste právě vytvořili. Zadejte hotely pro název kontejneru a jako klíč oddílu použijte /HotelId .
V části hotely vyberte Položky a pak na panelu příkazů vyberte Nahrát položku. Přejděte do složky projektu a vyberte soubor cosmosdb/HotelsDataSubset_CosmosDb.json .
Pomocí tlačítka Aktualizovat aktualizujte zobrazení položek v kolekci hotelů. Mělo by se zobrazit sedm nových databázových dokumentů.
Zkopírujte připojovací řetězec ze stránky Klíče do Poznámkový blok. Tuto hodnotu budete potřebovat pro appsettings.json v pozdějším kroku. Pokud jste nepoužíli navrhovaný název databáze "hotel-rooms-db", zkopírujte také název databáze.

Azure Blob Storage

Přihlaste se k webu Azure Portal, přejděte do svého účtu úložiště Azure, vyberte Objekty blob a pak vyberte + Kontejner.
Vytvořte kontejner objektů blob s názvem hotel-rooms pro uložení souborů JSON ukázkových hotelových místností. Úroveň veřejného přístupu můžete nastavit na libovolnou z jejích platných hodnot.
Po vytvoření kontejneru ho otevřete a na panelu příkazů vyberte Nahrát . Přejděte do složky obsahující ukázkové soubory. Vyberte všechny a pak vyberte Nahrát.
Zkopírujte název účtu úložiště a připojovací řetězec ze stránky Přístupové klíče do Poznámkový blok. V pozdějším kroku budete potřebovat obě hodnoty pro appsettings.json .

Azure AI Vyhledávač

Třetí komponentou je Azure AI Search, kterou můžete vytvořit na portálu nebo ve svých prostředcích Azure najít existující vyhledávací službu .

Zkopírování klíče api-key a adresy URL správce pro Azure AI Search

K ověření ve vyhledávací službě budete potřebovat adresu URL služby a přístupový klíč.

Přihlaste se k webu Azure Portal a na stránce Přehled vyhledávací služby získejte adresu URL. Příkladem koncového bodu může být https://mydemo.search.windows.net.
V Nastavení> Klíči získejte klíč správce pro úplná práva ke službě. Existují dva zaměnitelné klíče správce, které jsou k dispozici pro zajištění kontinuity podnikových procesů v případě, že potřebujete jeden převést. Primární nebo sekundární klíč můžete použít u požadavků pro přidávání, úpravy a odstraňování objektů.

Platný klíč vytváří na základě žádosti vztah důvěryhodnosti mezi aplikací, která žádost odeslala, a službou, která ji zpracovává.

2. Nastavení prostředí

Spusťte Visual Studio a v nabídce Nástroje vyberte Správce balíčků NuGet a pak spravovat balíčky NuGet pro řešení....
Na kartě Procházet vyhledejte a nainstalujte Azure.Search.Documents (verze 11.0 nebo novější).
Vyhledejte balíčky NuGet Microsoft.Extensions.Configuration a Microsoft.Extensions.Configuration.Json a nainstalujte je také.
Otevřete soubor řešení /v11/AzureSearchMultipleDataSources.sln.

V Průzkumník řešení upravte soubor appsettings.json a přidejte informace o připojení.

{
  "SearchServiceUri": "<YourSearchServiceURL>",
  "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>",
  "BlobStorageAccountName": "<YourBlobStorageAccountName>",
  "BlobStorageConnectionString": "<YourBlobStorageConnectionString>",
  "CosmosDBConnectionString": "<YourCosmosDBConnectionString>",
  "CosmosDBDatabaseName": "hotel-rooms-db"
}

První dvě položky jsou adresa URL a klíče správce vyhledávací služby. Použijte úplný koncový bod, například: https://mydemo.search.windows.net.

Další položky určují názvy účtů a připojovací řetězec informace o zdrojích dat Azure Blob Storage a Azure Cosmos DB.

3. Mapování klíčových polí

Sloučení obsahu vyžaduje, aby oba datové proudy cílily na stejné dokumenty v indexu vyhledávání.

Ve službě Azure AI Search pole s klíčem jednoznačně identifikuje každý dokument. Každý index vyhledávání musí mít přesně jedno klíčové pole typu Edm.String. Toto pole klíče musí být k dispozici pro každý dokument ve zdroji dat, který je přidán do indexu. (Ve skutečnosti je to jediné povinné pole.)

Při indexování dat z více zdrojů dat se ujistěte, že každý příchozí řádek nebo dokument obsahuje společný klíč dokumentu ke sloučení dat ze dvou fyzicky odlišných zdrojových dokumentů do nového vyhledávacího dokumentu v kombinovaném indexu.

Často vyžaduje určité počáteční plánování identifikace smysluplného klíče dokumentu pro váš index a ujistěte se, že existuje v obou zdrojích dat. V této ukázce HotelId se klíč pro každý hotel ve službě Azure Cosmos DB nachází také v pokojích objektů blob JSON v úložišti objektů blob.

Indexery azure AI Search můžou pomocí mapování polí přejmenovat a dokonce přeformátovat datová pole během procesu indexování, aby zdrojová data byla směrována na správné pole indexu. Například ve službě Azure Cosmos DB se volá HotelIdidentifikátor hotelu . Ale v souborech objektů blob JSON pro hotelové pokoje se jmenuje Ididentifikátor hotelu . Program tuto nesrovnalost zpracovává mapováním Id pole z objektů blob na HotelId pole klíče v indexeru.

Poznámka:

Ve většině případů automaticky generované klíče dokumentu, například klíče vytvořené ve výchozím nastavení některými indexery, neprovádí vhodné klíče dokumentu pro kombinované indexy. Obecně platí, že budete chtít použít smysluplnou, jedinečnou hodnotu klíče, která už existuje, nebo ji můžete snadno přidat do zdrojů dat.

4. Prozkoumání kódu

Po nastavení dat a konfigurace by měl být ukázkový program v /v11/AzureSearchMultipleDataSources.sln připravený k sestavení a spuštění.

Tato jednoduchá konzolová aplikace C#/.NET provádí následující úlohy:

Vytvoří nový index založený na datové struktuře třídy C# Hotel (která také odkazuje na třídy Address a Room).
Vytvoří nový zdroj dat a indexer, který mapuje data azure Cosmos DB na pole indexu. Jedná se o oba objekty ve službě Azure AI Search.
Spustí indexer, který načte data hotelu ze služby Azure Cosmos DB.
Vytvoří druhý zdroj dat a indexer, který mapuje data objektů blob JSON na pole indexu.
Spustí druhý indexer, který načte data místností z úložiště objektů blob.

Než program spustíte, prostudujte si kód a definice indexeru a indexeru pro tuto ukázku. Důležitý kód je ve dvou souborech:

Hotel.cs obsahuje schéma, které definuje index.
Program.cs obsahuje funkce, které vytvářejí index, zdroje dat a indexery Azure AI Search a načítají kombinované výsledky do indexu.

Vytvoření indexu

Tento ukázkový program používá CreateIndexAsync k definování a vytvoření indexu Azure AI Search. Využívá výhod Třídy FieldBuilder k vygenerování struktury indexu z třídy datového modelu jazyka C#.

Datový model je definován třídou Hotel, která obsahuje také odkazy na třídy Adresa a místnost. FieldBuilder přejde k podrobnostem prostřednictvím více definic tříd a vygeneruje složitou datovou strukturu indexu. Značky metadat slouží k definování atributů jednotlivých polí, jako je například to, jestli je prohledávatelné nebo řaditelné.

Program před vytvořením nového indexu odstraní všechny existující indexy se stejným názvem, pokud chcete tento příklad spustit více než jednou.

Následující fragmenty kódu ze souboru Hotel.cs zobrazují jednotlivá pole následovaná odkazem na jinou třídu datového modelu Room[], která je zase definována v souboru Room.cs (není zobrazeno).

. . .
[SimpleField(IsFilterable = true, IsKey = true)]
public string HotelId { get; set; }

[SearchableField(IsFilterable = true, IsSortable = true)]
public string HotelName { get; set; }
. . .
public Room[] Rooms { get; set; }
. . .

V souboru Program.cs je searchIndex definován s názvem a kolekcí polí vygenerovanou metodou FieldBuilder.Build a poté vytvořen následujícím způsobem:

private static async Task CreateIndexAsync(string indexName, SearchIndexClient indexClient)
{
    // Create a new search index structure that matches the properties of the Hotel class.
    // The Address and Room classes are referenced from the Hotel class. The FieldBuilder
    // will enumerate these to create a complex data structure for the index.
    FieldBuilder builder = new FieldBuilder();
    var definition = new SearchIndex(indexName, builder.Build(typeof(Hotel)));

    await indexClient.CreateIndexAsync(definition);
}

Vytvoření zdroje dat a indexeru azure Cosmos DB

Dále hlavní program obsahuje logiku pro vytvoření zdroje dat Azure Cosmos DB pro data hotelů.

Nejprve zřetězí název databáze Azure Cosmos DB do připojovací řetězec. Pak definuje SearchIndexerDataSource Připojení ion objekt.

private static async Task CreateAndRunCosmosDbIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
    // Append the database name to the connection string
    string cosmosConnectString =
        configuration["CosmosDBConnectionString"]
        + ";Database="
        + configuration["CosmosDBDatabaseName"];

    SearchIndexerDataSourceConnection cosmosDbDataSource = new SearchIndexerDataSourceConnection(
        name: configuration["CosmosDBDatabaseName"],
        type: SearchIndexerDataSourceType.CosmosDb,
        connectionString: cosmosConnectString,
        container: new SearchIndexerDataContainer("hotels"));

    // The Azure Cosmos DB data source does not need to be deleted if it already exists,
    // but the connection string might need to be updated if it has changed.
    await indexerClient.CreateOrUpdateDataSourceConnectionAsync(cosmosDbDataSource);

Po vytvoření zdroje dat program nastaví indexer služby Azure Cosmos DB s názvem hotel-rooms-cosmos-indexer.

Program aktualizuje všechny existující indexery se stejným názvem a přepíše stávající indexer obsahem výše uvedeného kódu. Zahrnuje také akce resetování a spuštění, pokud chcete tento příklad spustit více než jednou.

Následující příklad definuje plán indexeru, aby se spustil jednou za den. Vlastnost plánu můžete z tohoto volání odebrat, pokud nechcete, aby se indexer v budoucnu automaticky spustil znovu.

SearchIndexer cosmosDbIndexer = new SearchIndexer(
    name: "hotel-rooms-cosmos-indexer",
    dataSourceName: cosmosDbDataSource.Name,
    targetIndexName: indexName)
{
    Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};

// Indexers keep metadata about how much they have already indexed.
// If we already ran the indexer, it "remembers" and does not run again.
// To avoid this, reset the indexer if it exists.
try
{
    await indexerClient.GetIndexerAsync(cosmosDbIndexer.Name);
    // Reset the indexer if it exists.
    await indexerClient.ResetIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    // If the indexer does not exist, 404 will be thrown.
}

await indexerClient.CreateOrUpdateIndexerAsync(cosmosDbIndexer);

Console.WriteLine("Running Azure Cosmos DB indexer...\n");

try
{
    // Run the indexer.
    await indexerClient.RunIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

Tento příklad obsahuje jednoduchý blok try-catch, který hlásí všechny chyby, ke kterým může dojít během provádění.

Po spuštění indexeru Azure Cosmos DB bude index vyhledávání obsahovat úplnou sadu ukázkových hotelových dokumentů. Pole místností pro každý hotel však bude prázdné pole, protože zdroj dat Azure Cosmos DB vynechá podrobnosti o místnosti. V dalším kroku program načte a sloučí data místnosti z úložiště objektů blob.

Vytvoření zdroje dat a indexeru úložiště objektů blob

Pokud chcete získat podrobnosti o místnosti, program nejprve nastaví zdroj dat úložiště objektů blob tak, aby odkazovat na sadu jednotlivých souborů objektů blob JSON.

private static async Task CreateAndRunBlobIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
    SearchIndexerDataSourceConnection blobDataSource = new SearchIndexerDataSourceConnection(
        name: configuration["BlobStorageAccountName"],
        type: SearchIndexerDataSourceType.AzureBlob,
        connectionString: configuration["BlobStorageConnectionString"],
        container: new SearchIndexerDataContainer("hotel-rooms"));

    // The blob data source does not need to be deleted if it already exists,
    // but the connection string might need to be updated if it has changed.
    await indexerClient.CreateOrUpdateDataSourceConnectionAsync(blobDataSource);

Po vytvoření zdroje dat program nastaví indexer objektů blob s názvem hotel-rooms-blob-indexer, jak je znázorněno níže.

Objekty blob JSON obsahují pole klíče s názvem Id místo HotelId. Kód používá FieldMapping třídu k tomu, aby indexeru řekl, aby hodnotu pole směrovat Id na HotelId klíč dokumentu v indexu.

Indexery úložiště objektů blob můžou použít indexingParameters k určení režimu analýzy. V závislosti na tom, jestli objekty blob představují jeden dokument nebo více dokumentů ve stejném objektu blob, byste měli nastavit různé režimy analýzy. V tomto příkladu každý objekt blob představuje jeden dokument JSON, takže kód používá json režim analýzy. Další informace o parsování parametrů indexeru pro objekty blob JSON najdete v tématu Indexování objektů blob JSON.

Tento příklad definuje plán indexeru, aby se spustil jednou denně. Vlastnost plánu můžete z tohoto volání odebrat, pokud nechcete, aby se indexer v budoucnu automaticky spustil znovu.

IndexingParameters parameters = new IndexingParameters();
parameters.Configuration.Add("parsingMode", "json");

SearchIndexer blobIndexer = new SearchIndexer(
    name: "hotel-rooms-blob-indexer",
    dataSourceName: blobDataSource.Name,
    targetIndexName: indexName)
{
    Parameters = parameters,
    Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};

// Map the Id field in the Room documents to the HotelId key field in the index
blobIndexer.FieldMappings.Add(new FieldMapping("Id") { TargetFieldName = "HotelId" });

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

try
{
    // Run the indexer.
    await searchService.Indexers.RunAsync(blobIndexer.Name);
}
catch (CloudException e) when (e.Response.StatusCode == (HttpStatusCode)429)
{
    Console.WriteLine("Failed to run indexer: {0}", e.Response.Content);
}

Vzhledem k tomu, že index je již naplněný hotelovými daty z databáze Azure Cosmos DB, indexer objektů blob aktualizuje existující dokumenty v indexu a přidá podrobnosti o místnosti.

Poznámka:

Pokud máte v obou zdrojích dat stejná pole bez klíče a data v těchto polích se neshodují, index bude obsahovat hodnoty podle toho, co indexer naposledy spustil. V našem příkladu oba zdroje dat obsahují pole HotelName . Pokud se data v tomto poli z nějakého důvodu liší, pro dokumenty se stejnou hodnotou klíče budou data HotelName ze zdroje dat, který byl indexován naposledy, hodnotou uloženou v indexu.

5. Hledání

Vyplněný index vyhledávání můžete prozkoumat po spuštění programu pomocí Průzkumníka služby Search na portálu.

Na webu Azure Portal otevřete stránku Přehled vyhledávací služby a v seznamu Indexy vyhledejte index hotel-rooms-sample.

Seznam indexů Azure AI Search

V seznamu vyberte index s ukázkou hotelových místností. Zobrazí se rozhraní Průzkumníka služby Search pro index. Zadejte dotaz pro termín, jako je "Luxury". Ve výsledcích by se měl zobrazit alespoň jeden dokument a tento dokument by měl v poli místností zobrazit seznam objektů místnosti.

Resetování a opětovné spuštění

V počátečních experimentálních fázích vývoje je nejproktičtějším přístupem k iteraci návrhu odstranit objekty z Azure AI Search a umožnit kódu jejich opětovné sestavení. Názvy prostředků jsou jedinečné. Když se objekt odstraní, je možné ho znovu vytvořit se stejným názvem.

Vzorový kód zkontroluje existující objekty a odstraní nebo aktualizuje, abyste mohli program spustit znovu.

Pomocí portálu můžete také odstranit indexy, indexery a zdroje dat.

Vyčištění prostředků

Když pracujete ve vlastním předplatném, je na konci projektu vhodné odebrat prostředky, které už nepotřebujete. Prostředky, které necháte spuštěné, vás stojí peníze. Prostředky můžete odstraňovat jednotlivě nebo můžete odstranit skupinu prostředků, a odstranit tak celou sadu prostředků najednou.

Prostředky můžete najít a spravovat na portálu pomocí odkazu Všechny prostředky nebo skupiny prostředků v levém navigačním podokně.

Další kroky

Teď, když znáte koncept ingestování dat z více zdrojů, se podrobněji podíváme na konfiguraci indexeru počínaje službou Azure Cosmos DB.

Konfigurace indexeru Azure Cosmos DB for NoSQL

Kurz: Indexování z více zdrojů dat pomocí sady .NET SDK

Přehled

Požadavky

1. Vytvoření služeb

Začínáme se službou Azure Cosmos DB

Azure Blob Storage

Azure AI Vyhledávač

Zkopírování klíče api-key a adresy URL správce pro Azure AI Search

2. Nastavení prostředí

3. Mapování klíčových polí

4. Prozkoumání kódu

Vytvoření indexu

Vytvoření zdroje dat a indexeru azure Cosmos DB

Vytvoření zdroje dat a indexeru úložiště objektů blob

5. Hledání

Resetování a opětovné spuštění

Vyčištění prostředků

Další kroky

Další materiály