Zelfstudie: Azure SQL-gegevens indexeren met behulp van de .NET SDK

Artikel
09/23/2024

Configureer een indexeerfunctie voor het extraheren van doorzoekbare gegevens uit Azure SQL Database en verzend deze naar een zoekindex in Azure AI Search.

In deze zelfstudie worden C# en de Azure SDK voor .NET gebruikt om de volgende taken uit te voeren:

Een gegevensbron maken dat verbinding maakt met Azure SQL Database
Een indexeerfunctie maken
Een indexeerfunctie uitvoeren om gegevens in een index te laden
Een query uitvoeren op een index als een verificatiestap

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Azure SQL Database met behulp van SQL Server-verificatie
Visual Studio
Azure AI Search. Maak of vind een bestaande zoekservice

Notitie

U kunt een gratis zoekservice gebruiken voor deze zelfstudie. De gratis laag beperkt u tot drie indexen, drie indexeerfuncties en drie gegevensbronnen. In deze zelfstudie wordt één exemplaar van elk onderdeel gemaakt. Voordat u aan de slag gaat, zorg ervoor dat uw service voldoende ruimte heeft voor de nieuwe resources.

Bestanden downloaden

De broncode voor deze zelfstudie bevindt zich in de map DotNetHowToIndexer in de GitHub-opslagplaats Azure-Samples/search-dotnet-getting-started.

1- Services maken

In deze zelfstudie wordt Gebruikgemaakt van Azure AI Search voor indexering en query's en Azure SQL Database als een externe gegevensbron. Maak, indien mogelijk, beide services in dezelfde regio en resourcegroep voor nabijheid en beheerbaarheid. In de praktijk kan Azure SQL Database zich in elke regio bevinden.

Aan de slag met Azure SQL Database

Deze zelfstudie biedt hotels.sql bestand in het voorbeelddownload om de database te vullen. Azure AI Search verbruikt afgevlakte rijensets, zoals eenset die is gegenereerd op basis van een weergave of query. Het SQL-bestand in de voorbeeldoplossing maakt en vult één tabel.

Als u een bestaande Azure SQL Database-resource hebt, kunt u de tabel hotels eraan toevoegen, te beginnen bij de querystap Openen.

Maak een Azure SQL-database met behulp van de instructies in quickstart: Een individuele database maken.

Serverconfiguratie voor de database is belangrijk.
- Kies de sql Server-verificatieoptie waarmee u wordt gevraagd een gebruikersnaam en wachtwoord op te geven. U hebt dit nodig voor de ADO.NET verbindingsreeks die door de indexeerfunctie wordt gebruikt.
- Kies een openbare verbinding. Hierdoor is deze zelfstudie eenvoudiger te voltooien. Openbaar wordt niet aanbevolen voor productie en we raden u aan deze resource aan het einde van de zelfstudie te verwijderen.
Ga in Azure Portal naar de nieuwe resource.
Voeg een firewallregel toe om toegang vanaf uw client toe te staan met behulp van de instructies in Quickstart: Een firewallregel op serverniveau maken in Azure Portal. U kunt uitvoeren ipconfig vanaf een opdrachtprompt om uw IP-adres op te halen.
Gebruik de Query-editor om de voorbeeldgegevens te laden. Selecteer query-editor (preview) in het navigatiedeelvenster en voer de gebruikersnaam en het wachtwoord van de serverbeheerder in.

Als u een fout krijgt dat toegang is geweigerd, kopieert u het IP-adres van de client uit het foutbericht, opent u de netwerkbeveiligingspagina voor de server en voegt u een regel voor binnenkomend verkeer toe die toegang vanaf uw client toestaat.
Selecteer query openen in query-editor en navigeer naar de locatie van hotels.sql bestand op uw lokale computer.
Selecteer het bestand en selecteer Openen. Het script moet er ongeveer uitzien als in de volgende schermafbeelding:
Selecteer Uitvoeren om de query uit te voeren. In het deelvenster Resultaten ziet u een bericht dat de query is voltooid, voor drie rijen.
Als u een rijenset uit deze tabel wilt retourneren, kunt u de volgende query uitvoeren als verificatiestap:
```
SELECT * FROM Hotels
```

Kopieer de verbindingsreeks voor ADO.NET voor de database. Kopieer onder Instellingen>Verbindingsreeksen de ADO.NET-verbindingsreeks, vergelijkbaar met het voorbeeld hieronder.

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;

U hebt deze verbindingsreeks nodig in de volgende oefening, waarbij u uw omgeving instelt.

Azure AI Search

Het volgende onderdeel is Azure AI Search, dat u kunt maken in Azure Portal. U kunt de gratis laag gebruiken om dit voorbeeld te voltooien.

Een api-sleutel en URL voor beheerders ophalen voor Azure AI Search

Voor API-aanroepen is de service-URL en een toegangssleutel vereist. Er wordt een zoekservice gemaakt met beide, dus als u Azure AI Search aan uw abonnement hebt toegevoegd, volgt u deze stappen om de benodigde informatie op te halen:

Meld u aan bij Azure Portal en haal op de pagina Overzicht van de zoekservice de URL op. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Haal onder Instellingen>Sleutels een beheersleutel op voor volledige rechten op de service. Er zijn twee uitwisselbare beheersleutels die voor bedrijfscontinuïteit worden verstrekt voor het geval u een moet overschakelen. U kunt de primaire of secundaire sleutel gebruiken op aanvragen voor het toevoegen, wijzigen en verwijderen van objecten.

2 - De omgeving instellen

Start Visual Studio en open DotNetHowToIndexers.sln.
Open appsettings.json in Solution Explorer om verbindingsgegevens op te geven.
Als SearchServiceEndPointde volledige URL op de overzichtspagina van de service 'https://my-demo-service.search.windows.net" is, is de waarde die u moet opgeven de volledige URL.
Voor AzureSqlConnectionString is de tekenreeksindeling vergelijkbaar met het volgende: "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",
}
```
Vervang het gebruikerswachtwoord in de SQL-verbindingsreeks door een geldig wachtwoord. Terwijl de database en gebruikersnamen worden gekopieerd, moet het wachtwoord handmatig worden ingevoerd.

3: Maak de pijplijn

Voor indexeerfuncties is een gegevensbronobject en een index vereist. Relevante code staat in twee bestanden:

hotel.cs, dat een schema bevat dat de index definieert
Program.cs, dat functies bevat die de structuren in uw service maken en beheren

In hotel.cs

Het indexschema definieert de verzameling met velden, met inbegrip van kenmerken die toegestane bewerkingen opgeven, bijvoorbeeld of de volledige tekst van een veld kan worden doorzocht, gefilterd of gesorteerd zoals wordt weergegeven in de volgende velddefinitie voor HotelName. Een SearchableField is per definitie doorzoekbaar in volledige tekst. Andere kenmerken worden expliciet toegewezen.

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

Een schema kan ook andere elementen bevatten, zoals scoreprofielen om een zoekscore te verbeteren, aangepaste analysefuncties en andere constructies. In dit geval is het schema echter beperkt gedefinieerd en bestaat het alleen uit velden in de voorbeeldgegevenssets.

In Program.cs

Het hoofdprogramma bevat logica voor het maken van een indexeerclient, een index, een gegevensbron en een indexeerfunctie. De code controleert op en verwijdert bestaande resources met dezelfde naam, waarbij ervan wordt uitgegaan dat u dit programma meerdere keren uitvoert.

Het gegevensbronobject wordt geconfigureerd met instellingen die specifiek zijn voor Azure SQL Database-resources, inclusief gedeeltelijke of incrementele indexering voor het gebruik van de ingebouwde functies voor wijzigingsdetectie van Azure SQL. De database met brondemohotels in Azure SQL heeft een kolom met de naam Voorlopig verwijderen met de naam IsDeleted. Wanneer deze kolom is ingesteld op true in de database, verwijdert de indexeerfunctie het bijbehorende document uit de Azure AI Search-index.

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

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

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Een indexeerfunctie-object is platform-neutraal, waarbij de configuratie, planning en aanroep hetzelfde zijn, ongeacht de bron. Dit voorbeeld bevat een schema, een hersteloptie waarmee de indexeringsgeschiedenis wordt gewist en een methode wordt aangeroepen om de indexeerfunctie direct te maken en uit te voeren. Als u een indexeerfunctie wilt maken of bijwerken, gebruikt u 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);

Indexeerfunctieuitvoeringen worden meestal gepland, maar tijdens de ontwikkeling wilt u de indexeerfunctie mogelijk onmiddellijk uitvoeren met Behulp van 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 - De oplossing bouwen

Druk op F5 om de oplossing te bouwen en uit te voeren. Het programma wordt uitgevoerd in de foutopsporingsmodus. De status van elke bewerking wordt weergegeven in een consolevenster.

Uw code wordt lokaal uitgevoerd in Visual Studio en maakt verbinding met uw zoekservice in Azure, die op zijn beurt verbinding maakt met Azure SQL Database en de gegevensset op te halen. Met dit aantal bewerkingen zijn er verschillende mogelijke foutpunten. Als er een fout optreedt, controleert u eerst de volgende voorwaarden:

Search-service verbindingsgegevens die u opgeeft, is de volledige URL. Als u alleen de servicenaam hebt ingevoerd, stoppen bewerkingen bij het maken van de index, met een fout bij het maken van verbinding.
Gegevens over de databaseverbinding in appsettings.json. Dit moet de ADO.NET verbindingsreeks zijn die u hebt verkregen via Azure Portal, gewijzigd om een gebruikersnaam en wachtwoord op te nemen die geldig zijn voor uw database. Het gebruikersaccount moet machtigingen hebben om gegevens op te halen. Het IP-adres van uw lokale client moet binnenkomende toegang via de firewall zijn toegestaan.
Bronlimieten. Zoals u weet, heeft de gratis laag limieten van drie indexen, indexeerfuncties en gegevensbronnen. Een service met de maximale limiet kan geen nieuwe objecten maken.

5 - Zoeken

Gebruik de Azure-portal om het maken van objecten te controleren en gebruik vervolgens Search Explorer om de index op te vragen.

Meld u aan bij Azure Portal en open in het linkernavigatiedeelvenster van uw zoekservice elke pagina om te controleren of het object is gemaakt. Indexen, indexeerfuncties en gegevensbronnen hebben respectievelijk 'hotels-sql-idx', 'hotels-sql-indexer' en 'hotels-sql-ds'.
Selecteer op het tabblad Indexen de index hotels-sql-idx. Search Explorer is het eerste tabblad op de pagina hotels.
Selecteer Zoeken om een lege query uit te voeren.

De drie vermeldingen in de index worden geretourneerd als JSON-documenten. Search Explorer retourneert documenten in JSON, zodat u de volledige structuur kunt bekijken.
Schakel vervolgens over naar de JSON-weergave, zodat u queryparameters kunt invoeren:
```
{
     "search": "river",
     "count": true
}
```
Deze query roept een zoekopdracht aan die in de volledige tekst zoekt naar de term river en het resultaat bevat het aantal overeenkomende documenten. Het aantal overeenkomende documenten retourneren kan handig zijn in testscenario's wanneer u een grote index met duizenden of miljoenen documenten hebt. In dit geval komt slechts één document overeen met de query.
Voer tot slot parameters in waarmee zoekresultaten worden beperkt tot interessevelden:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
De respons van de query wordt beperkt tot geselecteerde velden, wat resulteert in een beknoptere uitvoer.

Opnieuw instellen en uitvoeren

In de vroege experimentele ontwikkelingsfasen is de meest praktische benadering voor het ontwerpen van iteratie het verwijderen van de objecten uit Azure AI Search en het mogelijk maken van uw code om ze opnieuw te bouwen. Resourcenamen zijn uniek. Na het verwijderen van een object kunt u het opnieuw maken met dezelfde naam.

In de voorbeeldcode voor deze zelfstudie wordt gecontroleerd op bestaande objecten. Deze worden verwijderd, zodat u de code opnieuw kunt uitvoeren.

U kunt azure Portal ook gebruiken om indexen, indexeerfuncties en gegevensbronnen te verwijderen.

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog steeds nodig hebt en of u deze moet verwijderen. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in Azure Portal met behulp van de koppeling Alle resources of resourcegroepen in het linkernavigatiedeelvenster.

Volgende stappen

Nu u bekend bent met de basisprincipes van het indexeren van SQL Database, gaan we de configuratie van de indexeerfunctie nader bekijken.

Een SQL Database-indexeerfunctie configureren

Delen via