Självstudie: Indexering av Azure SQL-data med hjälp av .NET SDK

Artikel
09/23/2024

Konfigurera en indexerare för att extrahera sökbara data från Azure SQL Database och skicka dem till ett sökindex i Azure AI Search.

I den här självstudien används C# och Azure SDK för .NET för att utföra följande uppgifter:

Skapa en datakälla som ansluter till Azure SQL Database
Skapa en indexerare
Kör en indexerare för att läsa in data till ett index
Köra frågor mot ett index som ett verifieringssteg

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.

Förutsättningar

Azure SQL Database med SQL Server-autentisering
Visual Studio
Azure AI Search. Skapa eller hitta en befintlig söktjänst

Kommentar

Du kan använda en kostnadsfri söktjänst för den här självstudien. Den kostnadsfria nivån begränsar dig till tre index, tre indexerare och tre datakällor. I den här kursen skapar du en av varje. Innan du börjar bör du se till att du har plats för din tjänst för att acceptera de nya resurserna.

Ladda ned filer

Källkoden för den här självstudien finns i mappen DotNetHowToIndexer i GitHub-lagringsplatsen Azure-Samples/search-dotnet-getting-started .

1 – Skapa tjänster

I den här självstudien används Azure AI Search för indexering och frågor samt Azure SQL Database som en extern datakälla. Skapa om möjligt båda tjänsterna i samma region och resursgrupp för närhet och hanterbarhet. I praktiken kan Azure SQL Database finnas i valfri region.

Börja med Azure SQL Database

Den här självstudien innehåller hotels.sql fil i exempelnedladdningen för att fylla i databasen. Azure AI Search använder utplattade raduppsättningar, till exempel en som genereras från en vy eller fråga. SQL-filen i exempellösningen skapar och fyller i en enskild tabell.

Om du har en befintlig Azure SQL Database-resurs kan du lägga till tabellen hotels i den, med början i frågesteget Öppna.

Skapa en Azure SQL-databas med hjälp av anvisningarna i Snabbstart: Skapa en enkel databas.

Serverkonfigurationen för databasen är viktig.
- Välj alternativet SQL Server-autentisering som uppmanar dig att ange ett användarnamn och lösenord. Du behöver detta för den ADO.NET anslutningssträng som används av indexeraren.
- Välj en offentlig anslutning. Det gör den här självstudien enklare att slutföra. Offentlig rekommenderas inte för produktion och vi rekommenderar att du tar bort den här resursen i slutet av självstudien.
I Azure Portal går du till den nya resursen.
Lägg till en brandväggsregel för att tillåta åtkomst från klienten med hjälp av anvisningarna i Snabbstart: Skapa en brandväggsregel på servernivå i Azure Portal. Du kan köra ipconfig från en kommandotolk för att hämta din IP-adress.
Använd frågeredigeraren för att läsa in exempeldata. I navigeringsfönstret väljer du Frågeredigeraren (förhandsversion) och anger användarnamnet och lösenordet för serveradministratören.

Om du får ett felmeddelande om nekad åtkomst kopierar du klientens IP-adress från felmeddelandet, öppnar nätverkssäkerhetssidan för servern och lägger till en inkommande regel som tillåter åtkomst från klienten.
I Frågeredigeraren väljer du Öppna fråga och navigerar till platsen för hotels.sql fil på den lokala datorn.
Välj filen och välj Öppna. Skriptet bör se ut ungefär som på följande skärmbild:
Välj Kör för att köra frågan. I fönstret Resultat bör du se ett meddelande om att frågan har slutförts för tre rader.
Om du vill returnera en raduppsättning från den här tabellen kan du köra följande fråga som ett verifieringssteg:
```
SELECT * FROM Hotels
```

Kopiera ADO.NET anslutningssträng för databasen. Under Inställningar>Anslutningssträngar kopierar du ADO.NET anslutningssträng, ungefär som i exemplet nedan.

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;

Du behöver den här anslutningssträng i nästa övning för att konfigurera din miljö.

Azure AI-sökning

Nästa komponent är Azure AI Search, som du kan skapa i Azure Portal. Du kan använda den kostnadsfria nivån för att slutföra den här genomgången.

Hämta en api-nyckel för administratör och URL för Azure AI Search

API-anrop kräver tjänstens URL och en åtkomstnyckel. En söktjänst skapas med båda, så om du har lagt till Azure AI Search i din prenumeration följer du dessa steg för att hämta nödvändig information:

Logga in på Azure Portal och hämta URL:en i söktjänstens översiktssida. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.
I Inställningar>Nycklar hämtar du en administratörsnyckel för fullständiga rättigheter för tjänsten. Det finns två utbytbara administratörsnycklar som tillhandahålls för affärskontinuitet om du behöver rulla över en. Du kan använda antingen den primära eller sekundära nyckeln på begäranden för att lägga till, ändra och ta bort objekt.

2 – Konfigurera din miljö

Starta Visual Studio och öppna DotNetHowToIndexers.sln.
Öppna appsettings.json i Solution Explorer för att ange anslutningsinformation.
För SearchServiceEndPoint, om den fullständiga URL:en på tjänstöversiktssidan är "https://my-demo-service.search.windows.net", är värdet som ska anges hela URL:en.
För AzureSqlConnectionStringliknar strängformatet följande: "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",
}
```
Ersätt användarlösenordet i SQL-anslutningssträng med ett giltigt lösenord. Även om databasen och användarnamnen kopieras måste lösenordet anges manuellt.

3 – Skapa pipelinen

Indexerare kräver ett datakällans objekt och ett index. Relevant kod finns i två filer:

hotel.cs som innehåller ett schema som definierar indexet
Program.cs, som innehåller funktioner för att skapa och hantera strukturer i din tjänst

I hotel.cs

Indexschemat definierar fältsamlingen, inklusive attribut som anger tillåtna åtgärder, till exempel om ett fält är fulltextsökbart, filtrerbart eller sorterbart som i följande fältdefinition för HotelName. Ett SearchableField kan sökas i fulltext per definition. Andra attribut tilldelas uttryckligen.

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

Ett schema kan även innehålla andra element, till exempel poängprofiler för att ge högre sökpoäng, anpassade analysverktyg och andra konstruktioner. Men för vårt ändamål har schemat en enkel definition med endast de fält som finns i exempeldatauppsättningarna.

I Program.cs

Huvudprogrammet innehåller logik för att skapa en indexerareklient, ett index, en datakälla och en indexerare. Koden söker efter och tar bort befintliga resurser med samma namn, under förutsättning att du kan köra det här programmet flera gånger.

Datakällans objekt konfigureras med inställningar som är specifika för Azure SQL Database-resurser, inklusive partiell eller inkrementell indexering för användning av de inbyggda funktionerna för ändringsidentifiering i Azure SQL. Källdemohotelldatabasen i Azure SQL har en kolumn med namnet "mjuk borttagning" med namnet IsDeleted. När den här kolumnen är inställd på true i databasen tar indexeraren bort motsvarande dokument från Azure AI Search-indexet.

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

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

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Ett indexerarobjekt är plattformsoberoende, där konfiguration, schemaläggning och anrop är desamma oavsett källa. Det här exemplet innehåller ett schema, ett återställningsalternativ som rensar indexerarens historik och anropar en metod för att skapa och köra indexeraren omedelbart. Om du vill skapa eller uppdatera en indexerare använder du 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);

Indexerarkörningar schemaläggs vanligtvis, men under utvecklingen kanske du vill köra indexeraren omedelbart med Hjälp av 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 – Skapa lösningen

Tryck på F5 för att skapa och köra lösningen. Programmet körs i felsökningsläge. I ett konsolfönster rapporteras status för varje åtgärd.

Koden körs lokalt i Visual Studio och ansluter till söktjänsten i Azure, som i sin tur ansluter till Azure SQL Database och hämtar datamängden. Med så här många åtgärder finns det flera potentiella felpunkter. Om du får ett fel kontrollerar du följande villkor först:

tjänsten Search anslutningsinformation som du anger är den fullständiga URL:en. Om du bara angav tjänstnamnet stoppas åtgärderna vid skapandet av indexet, med ett fel vid anslutning.
Informationen för databasanslutningen i appsettings.json. Det bör vara den ADO.NET anslutningssträng som hämtas från Azure Portal, ändrad så att den innehåller ett användarnamn och lösenord som är giltiga för databasen. Användarkontot måste ha behörighet att hämta data. Din lokala klient-IP-adress måste tillåtas inkommande åtkomst via brandväggen.
Resursbegränsningar. Kom ihåg att den kostnadsfria nivån har gränser för tre index, indexerare och datakällor. En tjänst med maxgränsen kan inte skapa nya objekt.

5 – Sök

Använd Azure Portal för att verifiera att objektet har skapats och använd sedan Sökutforskaren för att fråga indexet.

Logga in på Azure Portal och öppna varje sida i söktjänstens vänstra navigeringsfönster för att kontrollera att objektet har skapats. Index, indexerare och datakällor har "hotels-sql-idx", "hotels-sql-indexer" respektive "hotels-sql-ds".
På fliken Index väljer du indexet hotels-sql-idx. På hotellsidan är Sökutforskaren den första fliken.
Välj Sök för att utfärda en tom fråga.

De tre posterna i ditt index returneras som JSON-dokument. Sökutforskaren returnerar dokument i JSON så att du kan se hela strukturen.
Växla sedan till JSON-vy så att du kan ange frågeparametrar:
```
{
     "search": "river",
     "count": true
}
```
Den här frågan kör en fulltextsökning på termen river, och resultatet innefattar en räkning av matchande dokument. Att returnera antalet matchande dokument är användbart i testscenarier när du har ett stort index med tusentals eller miljontals dokument. I det här fallet är det bara ett dokument som matchar frågan.
Slutligen anger du parametrar som begränsar sökresultat till intressanta fält:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Svaret på frågan begränsas till valda fält, vilket ger mer koncisa utdata.

Återställa och köra igen

I de tidiga experimentella utvecklingsfaserna är det mest praktiska sättet att utforma iteration att ta bort objekten från Azure AI Search och låta koden återskapa dem. Resursnamn är unika. Om du tar bort ett objekt kan du återskapa det med samma namn.

Exempelkoden för den här självstudien söker efter befintliga objekt och tar bort dem så att du kan köra koden igen.

Du kan också använda Azure Portal för att ta bort index, indexerare och datakällor.

Rensa resurser

När du arbetar i din egen prenumeration i slutet av ett projekt är det en bra idé att ta bort de resurser som du inte längre behöver. Resurser som fortsätter att köras kostar pengar. Du kan ta bort enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

Du kan hitta och hantera resurser i Azure Portal med hjälp av länken Alla resurser eller Resursgrupper i det vänstra navigeringsfönstret.

Nästa steg

Nu när du är bekant med grunderna i SQL Database-indexering ska vi ta en närmare titt på indexerarens konfiguration.

Konfigurera en SQL Database-indexerare

Dela via