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

Zjistěte, jak nakonfigurovat indexer tak, aby extrahoval prohledávatelná data z Azure SQL Database a odeslal je do vyhledávacího indexu v Azure AI Vyhledávač.

V tomto kurzu použijete jazyk C# a sadu Azure SDK pro .NET k:

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Azure SQL Database pomocí ověřování Serveru SQL.
• Azure AI Vyhledávač. Vytvořit službu nebo najít existující službu ve vašem aktuálním předplatném.
• Visual Studio.

Stažení souborů

Zdrojový kód pro tento kurz se nachází ve složce DotNetHowToIndexer v repozitáři Azure-Samples/search-dotnet-getting-started na GitHubu.

Vytváření služeb

Tento kurz používá Azure AI Vyhledávač pro indexování a dotazy 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 s Azure SQL Database

Tento kurz poskytuje soubor hotels.sql v ukázkovém stažení pro naplnění databáze. Azure AI Vyhledávač využívá zploštěné sady řádků, například sady řádků vygenerované 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ěj přidat tabulku hotelů počínaje krokem Otevření dotazu.

1. Vytvořte Azure SQL database. Konfigurace serveru pro databázi je důležitá:

   • Zvolte možnost ověřování SQL Server, 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í, které usnadňuje dokončení tohoto kurzu. Veřejný přístup není doporučen v produkčním prostředí a doporučujeme odstranit tento prostředek na konci tutoriálu.

   

2. V portálu Azure přejděte na prostředek nový.

3. Přidejte pravidlo brány firewall, které umožňuje přístup z vašeho klienta. Ip adresu můžete získat spuštěním ipconfig z příkazového řádku.

4. K načtení ukázkových dat použijte Query editor. V navigačním podokně vyberte Query editor (Preview) a zadejte uživatelské jméno a heslo správce serveru.

   Pokud dojde k chybě přístupu odepřen, 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.

5. V Query editor vyberte Otevřet dotaz a přejděte do umístění souboru hotels.sql na místním počítači.

6. Vyberte soubor a vyberte Otevřít. Váš skript by měl vypadat jako na následujícím snímku obrazovky:

   

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

8. Pokud chcete vrátit sadu řádků z této tabulky, můžete jako krok ověření spustit následující dotaz:

   SELECT * FROM Hotels
   

9. Zkopírujte ADO.NET připojovací řetězec pro databázi. V části Settings>Connection Strings zkopírujte ADO.NET připojovací řetězec, což by mělo vypadat 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 k nastavení prostředí v dalším kroku.

Azure AI Vyhledávač

Další komponenta je Azure AI Vyhledávač, kterou můžete vytvořit v Azure portal. K dokončení tohoto kurzu můžete použít úroveň Free.

Získání klíče správce a adresy URL pro Azure AI Vyhledávač

Volání rozhraní API vyžadují adresu URL služby a přístupový klíč. V obou případech se vytvoří search service, takže pokud jste do předplatného přidali Azure AI Vyhledávač, získejte potřebné informace pomocí následujícího postupu:

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

2. Na stránce Přehled zkopírujte adresu URL koncového bodu. Příklad koncového bodu může vypadat jako https://mydemo.search.windows.net.

3. V Nastavení>Klíče 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. Objekty můžete přidávat, upravovat nebo odstraňovat pomocí klíče u požadavků.

   

Nastavení prostředí

1. Spusťte Visual Studio a otevřete DotNetHowToIndexers.sln.

2. V Průzkumník řešení otevřete appsettings.json a zadejte informace o připojení.

3. Pokud je úplná adresa URL na stránce SearchServiceEndPoint vaší služby Přehledhttps://my-demo-service.search.windows.net, zadejte celou tuto adresu URL.

4. Pro AzureSqlConnectionString je formát řetězce podobný "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",
   }
   

5. 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í, musíte heslo zadat ručně.

Vytvoř potrubí

Indexery vyžadují objekt zdroje dat a index. Důležitý kód je ve dvou souborech:

• hotel.cs obsahuje schéma, které definuje index.
• Program.cs obsahuje funkce pro vytváření a správu struktur ve vaší službě.

Soubor hotel.cs

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

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

Schéma může také obsahovat další prvky, například bodovací profily pro zvýšení skóre hledání a vlastních analyzátorů. Pro účely tohoto kurzu je však schéma řídce definované a skládá se pouze z polí nalezených v ukázkových datových sadách.

Soubor Program.cs

Hlavní program obsahuje logiku pro vytváření klienta an indexeru, indexu, zdroje dat a indexeru. Kód kontroluje a odstraňuje existující prostředky se stejným názvem za předpokladu, že byste mohli tento program spustit vícekrát.

Objekt zdroje dat je nakonfigurovaný s prostředky služby Azure SQL Database, včetně částečného nebo přírůstkového indexování pro použití integrovaných funkcí detekce změn v Azure SQL. Databáze zdrojových ukázkových hotelů v Azure SQL má sloupec "měkké 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 Vyhledávač.

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 a možnost resetování, která vymaže historii indexeru. Volá také metodu pro vytvoření a spuštění indexeru okamžitě. Pokud chcete vytvořit nebo aktualizovat indexer, 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 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);
}

Sestavení řešení

Výběrem 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í.

Kód běží místně v Visual Studio a připojuje se k search service na Azure, který se zase připojí k 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:

• Informace o připojení k vyhledávací službě, které zadáte, je ú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 to být ADO.NET připojovací řetězec získané z Azure portal a mělo by se změnit 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ý pro 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.

Search

Pomocí Azure portal ověřte vytvoření objektu a pak pomocí průzkumníka Search dotazujte index.

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

2. V levém podokně otevřete každou stránku a ověřte, že objekty jsou vytvořené. Indexy, indexery a zdroje dat by měly mít hotely-sql-idx, hotely-sql-idxr a hotely-sql-ds.

3. Na kartě Indexy vyberte index hotels-sql-idx . Na stránce hotelů je první karta hledání průzkumník.

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

   

5. 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. Výsledek obsahuje počet odpovídajících dokumentů. Vrácení počtu odpovídajících dokumentů je užitečné v testovacích scénářích, kdy máte velký index s tisíci nebo miliony dokumentů. V tomto případě dotazu odpovídá pouze jeden dokument.

6. 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 Vyhledávač 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í Azure portal můžete také odstranit indexy, indexery a zdroje dat.

Vyčistěte prostředky

Po dokončení projektu ve vašem vlastním předplatném je 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 v 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: