Kurz: Indexování dat Azure SQL pomocí sady .NET SDK

Článek
09/23/2024

Nakonfigurujte indexer tak, aby extrahovali prohledávatelná data ze služby Azure SQL Database a odeslali je do indexu vyhledávání ve službě Azure AI Search.

Tento kurz používá jazyk C# a sadu Azure SDK pro .NET k provádění následujících úloh:

Vytvoření zdroje dat, který se připojuje ke službě Azure SQL Database
Vytvoření indexeru
Spuštění indexeru pro načtení dat do indexu
Dotazování indexu jako ověřovacího kroku

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

Požadavky

Azure SQL Database s využitím ověřování SQL Serveru
Visual Studio
Azure AI Search. Vytvoření nebo vyhledání existující vyhledávací služby

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

Stažení souborů

Zdrojový kód pro tento kurz je ve složce DotNetHowToIndexer v úložišti GitHub Azure-Samples/search-dotnet-getting-started .

1. Vytvoření služeb

Tento kurz používá Azure AI Search k indexování a dotazům a Azure SQL Database jako externí zdroj dat. Pokud je to možné, vytvořte obě služby ve stejné oblasti a skupině prostředků pro zajištění blízkosti a možností správy. V praxi může být Azure SQL Database v libovolné oblasti.

Začínáme se službou Azure SQL Database

Tento kurz poskytuje hotels.sql soubor v ukázkovém stažení pro naplnění databáze. Azure AI Search využívá zploštěné sady řádků, například sadu řádků vygenerovanou ze zobrazení nebo dotazu. Soubor SQL v ukázkovém řešení vytvoří a naplní jednu tabulku.

Pokud máte existující prostředek azure SQL Database, můžete do ní přidat tabulku hotelů, a to od kroku Otevřít dotaz .

Vytvořte databázi Azure SQL pomocí pokynů v rychlém startu: Vytvoření izolované databáze.

Konfigurace serveru pro databázi je důležitá.
- Zvolte možnost ověřování SQL Serveru, která vás vyzve k zadání uživatelského jména a hesla. Potřebujete to pro ADO.NET připojovací řetězec používané indexerem.
- Zvolte veřejné připojení. Tento kurz usnadňuje dokončení. Veřejný se nedoporučuje pro produkční prostředí a doporučujeme odstranit tento prostředek na konci kurzu.
Na webu Azure Portal přejděte na nový prostředek.
Přidejte pravidlo brány firewall pro povolení přístupu z klienta pomocí pokynů v rychlém startu: Vytvoření pravidla brány firewall na úrovni serveru na webu Azure Portal. Ip adresu můžete získat spuštěním ipconfig z příkazového řádku.
Pomocí editoru dotazů načtěte ukázková data. V navigačním podokně vyberte Editor dotazů (Preview) a zadejte uživatelské jméno a heslo správce serveru.

Pokud se zobrazí chyba odepření přístupu, zkopírujte IP adresu klienta z chybové zprávy, otevřete stránku zabezpečení sítě pro server a přidejte příchozí pravidlo, které umožňuje přístup z vašeho klienta.
V editoru dotazů vyberte Otevřít dotaz a přejděte do umístění souboru hotels.sql na místním počítači.
Vyberte soubor a vyberte Otevřít. Váš skript by měl vypadat jako na následujícím snímku obrazovky:
Vyberte Spustit a spusťte dotaz. V podokně Výsledky by se měla zobrazit zpráva o úspěšném dotazu pro tři řádky.
Pokud chcete vrátit sadu řádků z této tabulky, můžete jako krok ověření spustit následující dotaz:
```
SELECT * FROM Hotels
```

Zkopírujte ADO.NET připojovací řetězec databáze. V části Připojovací řetězce nastavení>zkopírujte ADO.NET připojovací řetězec, podobně jako v následujícím příkladu.

Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;

Tento připojovací řetězec budete potřebovat v dalším cvičení a nastavíte prostředí.

Azure AI Vyhledávač

Další komponentou je Azure AI Search, kterou můžete vytvořit na webu Azure Portal. K dokončení tohoto názorného postupu můžete použít úroveň Free.

Získání klíče api-key a adresy URL pro správce služby Azure AI Search

Volání rozhraní API vyžadují adresu URL služby a přístupový klíč. Vytvoří se vyhledávací služba s oběma službami, takže pokud jste do svého předplatného přidali Azure AI Search, získejte potřebné informace pomocí následujícího postupu:

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 části Klíče nastavení>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ů.

2. Nastavení prostředí

Spusťte Visual Studio a otevřete DotNetHowToIndexers.sln.
V Průzkumník řešení otevřete appsettings.json a zadejte informace o připojení.
Pokud SearchServiceEndPointje úplná adresa URL na stránce přehledu služby "https://my-demo-service.search.windows.net", pak hodnota, která se má zadat, je celá adresa URL.
Formát AzureSqlConnectionStringřetězce je podobný tomuto: "Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
```
{
  "SearchServiceEndPoint": "<placeholder-search-full-url>",
  "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
  "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
}
```
Nahraďte uživatelské heslo v sql připojovací řetězec platným heslem. I když se databáze a uživatelská jména zkopírují, heslo se musí zadat ručně.

3. Vytvoření kanálu

Indexery vyžadují objekt zdroje dat a index. Relevantní kód je ve dvou souborech:

hotel.cs obsahující schéma definující index
Program.cs obsahující funkce pro vytváření a správu struktur ve vaší službě

Soubor hotel.cs

Schéma indexu definuje kolekci polí, včetně atributů určujících povolené operace, například jestli je pole fulltextově prohledávatelné, filtrovatelné nebo seřaditelné, jak je znázorněno v následující definici pole pro HotelName. Pole SearchableField je prohledávatelné podle definice. Další atributy jsou explicitně přiřazeny.

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

Schéma může obsahovat také další elementy, včetně profilů vyhodnocování pro zvýšení skóre vyhledávání, vlastních analyzátorů a dalších konstrukcí. Pro naše účely je však schéma definováno řídce a skládá se pouze z polí, která jsou v ukázkových datových sadách.

Soubor Program.cs

Hlavní program obsahuje logiku pro vytvoření klienta indexeru, indexu, zdroje dat a indexeru. Kód předpokládá, že byste tento program mohli spustit několikrát, a proto kontroluje a odstraňuje existující prostředky se stejným názvem.

Objekt zdroje dat je nakonfigurovaný s nastavením specifickými pro prostředky Azure SQL Database, včetně částečného nebo přírůstkového indexování pro použití integrovaných funkcí detekce změn Azure SQL. Zdrojová ukázková databáze hotelů v Azure SQL má sloupec obnovitelného odstranění s názvem IsDeleted. Pokud je tento sloupec v databázi nastavený na true, indexer odebere odpovídající dokument z indexu Azure AI Search.

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSQLConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Objekt indexeru je nezávislý na platformě, kde konfigurace, plánování a vyvolání jsou stejné bez ohledu na zdroj. Tento ukázkový indexer obsahuje plán, možnost resetování, která vymaže historii indexeru a volá metodu pro vytvoření a spuštění indexeru okamžitě. K vytvoření nebo aktualizaci indexeru použijte CreateOrUpdateIndexerAsync.

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

Spuštění indexeru jsou obvykle naplánovaná, ale během vývoje můžete chtít indexer spustit okamžitě pomocí RunIndexerAsync.

Console.WriteLine("Running Azure SQL indexer...");

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

4. Sestavení řešení

Stisknutím klávesy F5 sestavte a spusťte řešení. Program se spustí v režimu ladění. V okně konzoly se bude hlásit stav jednotlivých operací.

Váš kód běží místně v sadě Visual Studio a připojuje se k vaší vyhledávací službě v Azure, která se zase připojí ke službě Azure SQL Database a načte datovou sadu. Při těchto mnoha operacích existuje několik potenciálních bodů selhání. Pokud se zobrazí chyba, nejprve zkontrolujte následující podmínky:

Search informace o připojení, které zadáte, jsou úplná adresa URL. Pokud jste zadali pouze název služby, operace se zastaví při vytváření indexu s chybou připojení.
Informace o připojení k databázi v souboru appsettings.json. Mělo by se jednat o ADO.NET připojovací řetězec získané z webu Azure Portal, které se změnilo tak, aby obsahovalo uživatelské jméno a heslo platné pro vaši databázi. Uživatelský účet musí mít oprávnění k načtení dat. Ip adresa místního klienta musí být povolená příchozí přístup přes bránu firewall.
Omezení prostředků. Vzpomeňte si, že úroveň Free má omezení tří indexů, indexerů a zdrojů dat. Služba s maximálním limitem nemůže vytvářet nové objekty.

5. Hledání

Pomocí webu Azure Portal ověřte vytvoření objektu a pak pomocí Průzkumníka služby Search dotazujte index.

Přihlaste se k webu Azure Portal a v levém navigačním podokně vyhledávací služby otevřete každou stránku a ověřte, že se objekt vytvořil. Indexy, indexery a zdroje dat budou mít "hotels-sql-idx", "hotels-sql-indexer" a "hotels-sql-ds".
Na kartě Indexy vyberte index hotels-sql-idx. Na stránce hotelů je průzkumník služby Search první kartou.
Výběrem možnosti Hledat vydáte prázdný dotaz.

Vrátí se tři položky ve vašem indexu jako dokumenty JSON. Průzkumník služby Search vrací dokumenty ve formátu JSON, abyste mohli zobrazit celou jejich strukturu.
Pak přepněte do zobrazení JSON, abyste mohli zadat parametry dotazu:
```
{
     "search": "river",
     "count": true
}
```
Tento dotaz vyvolá fulltextové vyhledávání výrazu river a výsledek bude obsahovat počet odpovídajících dokumentů. Vrácení počtu odpovídajících dokumentů je užitečné ve scénářích testování, když máte velký index s tisíci nebo miliony dokumentů. V tomto případě dotazu odpovídá pouze jeden dokument.
Nakonec zadejte parametry, které omezují výsledky hledání na pole, která zajímají:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Odpověď na dotaz je omezená na vybraná pole, což ve výsledku znamená stručnější výstup.

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 pro tento kurz zkontroluje existující objekty a odstraní je, abyste mohli znovu spustit kód.

Pomocí webu Azure Portal 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 webu Azure Portal pomocí odkazu Všechny prostředky nebo skupiny prostředků v levém navigačním podokně.

Další kroky

Teď, když znáte základy indexování služby SQL Database, se podrobněji podíváme na konfiguraci indexeru.

Konfigurace indexeru služby SQL Database

Sdílet prostřednictvím