Oktatóanyag: Indexelés több adatforrásból a .NET SDK használatával

Az Azure AI Search több adatforrásból származó adatokat importálhat, elemezhet és indexelhet egyetlen összevont keresési indexbe.

Ez a C# oktatóanyag az Azure.Search.Documents ügyfélkódtárat használja az Azure SDK for .NET-ben egy Azure Cosmos DB-példányból származó minta szállodai adatok indexelésére, és egyesíti azOkat az Azure Blob Storage-dokumentumokból kinyert szállodai szobák adataival. Az eredmény egy szállodai dokumentumokat tartalmazó kombinált szállodai keresési index, amely a szobákat összetett adattípusként tartalmazza.

Ebben az oktatóanyagban a következő feladatokat fogja elvégezni:

• Mintaadatok feltöltése és adatforrások létrehozása
• A dokumentumkulcs azonosítása
• Az index definiálása és létrehozása
• Szállodai adatok indexelése az Azure Cosmos DB-ből
• Szállodai szoba adatainak egyesítése a Blob Storage-ból

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.

Áttekintés

Ez az oktatóanyag az Azure.Search.Documents használatával hoz létre és futtat több indexelőt. Ebben az oktatóanyagban két Azure-adatforrást fog beállítani, hogy konfigurálhassa a mindkettőből lekérhető indexelőt egyetlen keresési index feltöltéséhez. A két adathalmaznak közös értékkel kell rendelkeznie az egyesítés támogatásához. Ebben a mintában ez a mező egy azonosító. Mindaddig, amíg egy mező közösen támogatja a leképezést, az indexelők egyesíthetik az adatokat különböző erőforrásokból: strukturált adatok az Azure SQL-ből, strukturálatlan adatok a Blob Storage-ból vagy a támogatott adatforrások bármilyen kombinációja az Azure-ban.

Az oktatóanyagban szereplő kód egy kész verziója a következő projektben található:

• több adatforrás/v11 (GitHub)

Előfeltételek

• Azure Cosmos DB for NoSQL
• Azure Storage
• Visual Studio
• Azure AI Search (11.x-es verzió) NuGet-csomag
• Azure AI Search

Feljegyzés

Ehhez az oktatóanyaghoz ingyenes keresési szolgáltatást használhat. Az ingyenes szint három indexre, három indexelőre és három adatforrásra korlátozza. Az oktatóanyagban mindegyikből egyet hozhat majd létre. Mielőtt hozzákezdene, győződjön meg arról, hogy van helye a szolgáltatásban az új erőforrások elfogadásához.

1 – Szolgáltatások létrehozása

Ez az oktatóanyag az Azure AI Search szolgáltatást használja indexeléshez és lekérdezésekhez, az Azure Cosmos DB-t egy adatkészlethez, az Azure Blob Storage-t pedig a második adatkészlethez.

Ha lehetséges, hozzon létre minden szolgáltatást ugyanabban a régióban és erőforráscsoportban a közelség és a kezelhetőség érdekében. A gyakorlatban a szolgáltatások bármely régióban lehetnek.

Ez a minta két kis adatkészletet használ, amelyek hét fiktív szállodát írnak le. Az egyik készlet maga írja le a szállodákat, és betöltődik egy Azure Cosmos DB-adatbázisba. A másik készlet a szállodai szoba adatait tartalmazza, és hét különálló JSON-fájlként van megadva, amelyet fel kell tölteni az Azure Blob Storage-ba.

Első lépések az Azure Cosmos DB-vel

1. Jelentkezzen be az Azure Portalra, majd navigáljon az Azure Cosmos DB-fiók áttekintési oldalán.

2. Válassza az Adatkezelő, majd az Új adatbázis lehetőséget.

   

3. Adja meg a hotel-rooms-db nevet. Fogadja el a fennmaradó beállítások alapértelmezett értékeit.

   

4. Hozzon létre egy új tárolót. Használja az imént létrehozott adatbázist. Adja meg a tároló nevét, és használja a /HotelId parancsot a partíciókulcshoz.

   

5. Válassza az Elemek elemet a szállodák alatt, majd válassza az Elem feltöltése lehetőséget a parancssávon. Lépjen a projektmappába, és válassza ki a cosmosdb/HotelsDataSubset_CosmosDb.json fájlt.

   

6. A Frissítés gombbal frissítheti a szállodagyűjtemény elemeinek nézetét. A listában hét új adatbázis-dokumentumnak kell megjelennie.

7. Másolja a kapcsolati sztring a Kulcsok lapról a Jegyzettömb. Egy későbbi lépésben szüksége lesz erre az értékre appsettings.json . Ha nem a "hotel-rooms-db" javasolt adatbázisnevet használta, másolja ki az adatbázis nevét is.

Azure Blob Storage

1. Jelentkezzen be az Azure Portalra, lépjen az Azure Storage-fiókjához, válassza a Blobok lehetőséget, majd a + Tároló lehetőséget.

2. Hozzon létre egy szállodai szobák nevű blobtárolót a szállodai mintaszoba JSON-fájljainak tárolásához. A nyilvános hozzáférési szintet bármely érvényes értékre beállíthatja.

   

3. A tároló létrehozása után nyissa meg, és válassza a Feltöltés lehetőséget a parancssávon. Keresse meg a mintafájlokat tartalmazó mappát. Jelölje ki az összeset, majd válassza a Feltöltés lehetőséget.

   

4. Másolja a tárfiók nevét és egy kapcsolati sztring a Hozzáférési kulcsok lapról a Jegyzettömb. Egy későbbi lépésben mindkét értékre szüksége lesz a appsettings.json .

Azure AI Keresés

A harmadik összetevő az Azure AI Search, amelyet létrehozhat a portálon, vagy megkereshet egy meglévő keresési szolgáltatást az Azure-erőforrásokban.

Rendszergazdai API-kulcs és URL-cím másolása az Azure AI Search szolgáltatáshoz

A keresési szolgáltatásban való hitelesítéshez szüksége lesz a szolgáltatás URL-címére és egy hozzáférési kulcsra.

1. Jelentkezzen be az Azure Portalra, és a keresési szolgáltatás áttekintési lapján kérje le az URL-címet. A végpontok például a következőképpen nézhetnek ki: https://mydemo.search.windows.net.

2. A Gépház> Keysben szerezze be a szolgáltatás teljes jogosultságainak rendszergazdai kulcsát. Két felcserélhető rendszergazdai kulcs áll rendelkezésre az üzletmenet folytonossága érdekében, ha át kell gördítenie egyet. Az elsődleges vagy a másodlagos kulcsot használhatja objektumok hozzáadására, módosítására és törlésére vonatkozó kérelmekhez.

   

Érvényes kulcs birtokában kérelmenként bizalom hozható létre a kérelmet küldő alkalmazás és a kérelmet kezelő szolgáltatás között.

2 – A környezet beállítása

1. Indítsa el a Visual Studiót, és az Eszközök menüben válassza a NuGet Csomagkezelő, majd a NuGet-csomagok kezelése megoldáshoz... lehetőséget.

2. A Tallózás lapon keresse meg és telepítse az Azure.Search.Documentsot (11.0-s vagy újabb verzió).

3. Keresse meg a Microsoft.Extensions.Configuration és a Microsoft.Extensions.Configuration.Json NuGet csomagokat, és telepítse őket is.

4. Nyissa meg a /v11/AzureSearchMultipleDataSources.sln megoldásfájlt.

5. A Megoldáskezelő szerkessze a appsettings.json fájlt a kapcsolati adatok hozzáadásához.

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

Az első két bejegyzés a keresési szolgáltatás URL-címe és rendszergazdai kulcsa. Használja a teljes végpontot, például: https://mydemo.search.windows.net.

A következő bejegyzések az Azure Blob Storage és az Azure Cosmos DB adatforrásainak fiókneveit és kapcsolati sztring adatait határozzák meg.

3 – Kulcsmezők leképezése

A tartalom egyesítéséhez mindkét adatfolyam ugyanazt a dokumentumot célozza meg a keresési indexben.

Az Azure AI Searchben a kulcsmező egyedileg azonosítja az egyes dokumentumokat. Minden keresési indexnek pontosan egy típusú Edm.Stringkulcsmezővel kell rendelkeznie. Ennek a kulcsmezőnek minden dokumentumnál jelen kell lennie az indexhez hozzáadott adatforrásban. (Valójában ez az egyetlen kötelező mező.)

Ha több adatforrásból származó adatokat indexel, győződjön meg arról, hogy minden bejövő sor vagy dokumentum tartalmaz egy közös dokumentumkulcsot, amely két fizikailag különálló forrásdokumentum adatait egyesíti egy új keresési dokumentumba az egyesített indexben.

Gyakran előzetes tervezésre van szükség ahhoz, hogy az indexhez megfelelő dokumentumkulcsot azonosítson, és győződjön meg arról, hogy mindkét adatforrásban létezik. Ebben a bemutatóban az HotelId Azure Cosmos DB minden szállodájának kulcsa megtalálható a Blob Storage JSON-blobjaiban is.

Az Azure AI Search-indexelők mezőleképezésekkel átnevezhetik és újraformázhatják az adatmezőket az indexelési folyamat során, így a forrásadatok a megfelelő indexmezőbe irányíthatók. Az Azure Cosmos DB-ben például a szállodaazonosító neve HotelId. A szállodai szobák JSON-blobfájljaiban azonban a szállodaazonosító neve Id. A program ezt az eltérést úgy kezeli, hogy megfelelteti a mezőt a Id blobokból az HotelId indexelő kulcsmezőjére.

Feljegyzés

A legtöbb esetben az automatikusan létrehozott dokumentumkulcsok, például az egyes indexelők által alapértelmezés szerint létrehozott kulcsok nem tesznek jó dokumentumkulcsokat a kombinált indexekhez. Általában olyan értelmes, egyedi kulcsértéket szeretne használni, amely már létezik, vagy könnyen hozzáadható az adatforrásokhoz.

4 – A kód megismerése

Az adatok és a konfigurációs beállítások megadása után a /v11/AzureSearchMultipleDataSources.sln mintaprogramjának készen kell állnia a létrehozásra és a futtatásra.

Ez az egyszerű C#/.NET-konzolalkalmazás a következő feladatokat hajtja végre:

• Létrehoz egy új indexet a C# Hotel osztály adatstruktúrája alapján (amely a Cím és a Szoba osztályra is hivatkozik).
• Létrehoz egy új adatforrást és egy indexelőt, amely az Azure Cosmos DB-adatokat indexmezőkké képezi le. Ezek mindkét objektum az Azure AI Searchben.
• Az indexelő futtatásával betölti a szállodai adatokat az Azure Cosmos DB-ből.
• Létrehoz egy második adatforrást és egy indexelőt, amely JSON-blobadatokat képez le indexmezőkre.
• Futtatja a második indexelőt a Szobák adatok Blob Storage-ból való betöltéséhez.

A program futtatása előtt szánjon egy percet a minta kódjának, index- és indexelődefinícióinak tanulmányozására. A megfelelő kód a következő két fájlban található meg:

• Hotel.cs az indexet meghatározó sémát tartalmazza
• Program.cs olyan függvényeket tartalmaz, amelyek létrehozzák az Azure AI Search-indexet, az adatforrásokat és az indexelőket, és betöltik az összesített eredményeket az indexbe.

Index létrehozása

Ez a mintaprogram a CreateIndexAsync használatával definiál és hoz létre egy Azure AI Search-indexet. A FieldBuilder osztály segítségével indexstruktúrát hozhat létre egy C#-adatmodell-osztályból.

Az adatmodellt a Szálloda osztály határozza meg, amely a Cím és a Helyiség osztályra mutató hivatkozásokat is tartalmaz. A FieldBuilder több osztálydefiníción keresztül részletezi az index összetett adatstruktúráját. A metaadatcímkék az egyes mezők attribútumainak meghatározására szolgálnak, például azt, hogy kereshető vagy rendezhető-e.

A program törli az azonos nevű meglévő indexeket az új létrehozása előtt, ha ezt a példát többször szeretné futtatni.

A Hotel.cs fájl alábbi kódrészletei egyetlen mezőket mutatnak, majd egy másik adatmodell-osztályra, a Room[]-ra mutató hivatkozást, amely viszont Room.cs fájlban van definiálva (nem jelenik meg).

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

A Program.cs fájlban a SearchIndex a metódus által létrehozott névvel és mezőgyűjteménysel van definiálva, majd a FieldBuilder.Build következőképpen jön létre:

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

Azure Cosmos DB-adatforrás és indexelő létrehozása

A fő program a szállodai adatokHoz tartozó Azure Cosmos DB-adatforrás létrehozásához szükséges logikát tartalmazza.

Először összefűzi az Azure Cosmos DB-adatbázis nevét a kapcsolati sztring. Ezután definiál egy SearchIndexerDataSource Csatlakozás ion objektumot.

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

Az adatforrás létrehozása után a program beállít egy Hotel-rooms-cosmos-indexer nevű Azure Cosmos DB-indexelőt.

A program frissíti a meglévő indexelőket ugyanazzal a névvel, felülírva a meglévő indexelőt a fenti kód tartalmával. Emellett alaphelyzetbe állítási és futtatási műveleteket is tartalmaz, ha ezt a példát többször szeretné futtatni.

Az alábbi példa az indexelő ütemezését határozza meg, hogy naponta egyszer fusson. Eltávolíthatja a hívás ütemezési tulajdonságát, ha nem szeretné, hogy az indexelő a jövőben automatikusan újra fusson.

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

Ez a példa egy egyszerű kipróbálási blokkot tartalmaz a végrehajtás során esetlegesen előforduló hibák jelentésére.

Az Azure Cosmos DB-indexelő futtatása után a keresési index teljes minta szállodai dokumentumokat fog tartalmazni. Az egyes hotelek helyiségmezője azonban üres tömb lesz, mivel az Azure Cosmos DB-adatforrás kihagyja a szobák részleteit. Ezután a program lekéri a Blob Storage-ból a helyiségadatok betöltéséhez és egyesítéséhez.

Blob Storage-adatforrás és indexelő létrehozása

A helyiség részleteinek lekéréséhez a program először beállít egy Blob Storage-adatforrást, amely az egyes JSON-blobfájlokra hivatkozik.

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

Az adatforrás létrehozása után a program beállít egy hotel-rooms-blob-indexer nevű blobindexert, ahogy az alább látható.

A JSON-blobok a helyett HotelIdegy kulcsmezőt Id tartalmaznak. A kód az FieldMapping osztály használatával utasítja az indexelőt, hogy a Id mező értékét az HotelId index dokumentumkulcsához irányítsa.

A Blob Storage indexelői az IndexingParameters használatával adhatnak meg elemzési módot. Különböző elemzési módokat kell beállítania attól függően, hogy a blobok egyetlen dokumentumot vagy több dokumentumot jelölnek-e ugyanazon a blobon belül. Ebben a példában minden blob egyetlen JSON-dokumentumot jelöl, így a kód az elemzési json módot használja. További információ a JSON-blobok indexelő elemzési paramétereiről: Index JSON-blobok.

Ez a példa meghatározza az indexelő ütemezését, hogy naponta egyszer fusson. Eltávolíthatja a hívás ütemezési tulajdonságát, ha nem szeretné, hogy az indexelő a jövőben automatikusan újra fusson.

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

Mivel az indexet már feltöltötték az Azure Cosmos DB-adatbázisból származó szállodai adatokkal, a blobindexelő frissíti az indexben lévő meglévő dokumentumokat, és hozzáadja a helyiség részleteit.

Feljegyzés

Ha mindkét adatforrásban ugyanazok a nem kulcsmezők szerepelnek, és a mezők adatai nem egyeznek, akkor az index azokat az értékeket fogja tartalmazni, amelyekből az indexelő legutóbb futott. A példánkban mindkét adatforrás tartalmaz egy HotelName mezőt. Ha valamilyen okból a mezőben szereplő adatok eltérnek, az azonos kulcsértékkel rendelkező dokumentumok esetében az indexben tárolt érték lesz az indexben tárolt HotelName-adatok az adatforrásból.

5 – Keresés

A kitöltött keresési indexet a program futtatása után, a Portál Keresőböngészője segítségével ismerheti meg.

Az Azure Portalon nyissa meg a keresési szolgáltatás áttekintési oldalát, és keresse meg a hotel-rooms-sample indexet az Indexek listában.

Válassza ki a szálloda-szobák mintaindexét a listában. Megjelenik az index Keresési kezelő felülete. Adjon meg egy lekérdezést egy olyan kifejezéshez, mint a "Luxus". Az eredményekben legalább egy dokumentumnak szerepelnie kell, és ennek a dokumentumnak a helyiségobjektumok listáját kell megjelenítenie a helyiségtömbben.

Alaphelyzetbe állítás és ismételt futtatás

A fejlesztés korai kísérleti fázisaiban a tervezési iteráció legpraktikusabb módszere az objektumok törlése az Azure AI Searchből, és a kód újraépítésének engedélyezése. Az erőforrásnevek egyediek. Egy objektum törlése révén újból létrehozhatja azt ugyanazzal a névvel.

A mintakód ellenőrzi a meglévő objektumokat, és törli vagy frissíti őket, hogy újrafuttassa a programot.

A portálon indexeket, indexelőket és adatforrásokat is törölhet.

Az erőforrások eltávolítása

Ha a saját előfizetésében dolgozik, a projekt végén célszerű eltávolítania a már nem szükséges erőforrásokat. A továbbra is futó erőforrások költségekkel járhatnak. Az erőforrásokat törölheti egyesével, vagy az erőforráscsoport törlésével eltávolíthatja a benne lévő összes erőforrást is.

A portálon a bal oldali navigációs panel Minden erőforrás vagy Erőforráscsoport hivatkozásával kereshet és kezelhet erőforrásokat.

Következő lépések

Most, hogy már ismeri a több forrásból származó adatok betöltésének fogalmát, nézzük meg közelebbről az Indexelő konfigurációját az Azure Cosmos DB-től kezdve.

Azure Cosmos DB konfigurálása NoSQL-indexelőhöz