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

Meer informatie over het configureren van een indexeerfunctie voor het extraheren van doorzoekbare gegevens uit Azure SQL Database en het verzenden ervan naar een zoekindex in Azure AI Search.

In deze zelfstudie gebruikt u C# en de Azure SDK voor .NET om:

Vereisten

• Een Azure-account met een actief abonnement. Gratis een account maken
• Azure SQL Database met behulp van SQL Server-verificatie.
• Azure AI Search-. Maak een service of zoek een bestaande service in uw huidige abonnement.
• Visual Studio.

Bestanden downloaden

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

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 bevat het hotels.sql-bestand in het voorbeelddownload om de database te vullen. Azure AI Search consumeert afgevlakte rijensets, zoals een set die is gegenereerd op basis van een query of weergave. 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, vanaf de stap Query openen.

1. Maak een Azure SQL database. 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, waardoor deze zelfstudie eenvoudiger te voltooien is. Publiek gebruik wordt niet aanbevolen voor productie, en we raden u aan deze resource aan het einde van de handleiding te verwijderen.

   

2. Ga in Azure Portal naar de nieuwe resource.

3. Voeg een firewallregel toe die toegang vanaf uw client toestaat. U kunt uitvoeren ipconfig vanaf een opdrachtprompt om uw IP-adres op te halen.

4. Gebruik de Query-editor om de voorbeeldgegevens te laden. Selecteer queryeditor (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.

5. Selecteer query openen in query-editor en navigeer naar de locatie van hotels.sql bestand op uw lokale computer.

6. Selecteer het bestand en selecteer Openen. Het script moet er ongeveer uitzien als in de volgende schermafbeelding:

   

7. Selecteer Uitvoeren om de query uit te voeren. In het deelvenster Resultaten ziet u een bericht dat de query is voltooid voor drie rijen.

8. Als u een rijenset uit deze tabel wilt retourneren, kunt u de volgende query uitvoeren als verificatiestap:

   SELECT * FROM Hotels
   

9. Kopieer de verbindingsreeks voor ADO.NET voor de database. Kopieer onderVerbindingsreeksen> de ADO.NET verbindingsreeks, die vergelijkbaar moet zijn met het volgende voorbeeld:

   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 om uw omgeving in te stellen in de volgende stap.

Azure AI Search

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

Een beheerderssleutel en URL voor Azure AI Search ophalen

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:

1. Meld u aan bij het Azure-portaal. Kopieer de eindpunt-URL op de pagina Overzicht van uw service. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.

2. InInstellingensleutels> haalt u een beheerderssleutel op voor volledige rechten voor de service. Er zijn twee uitwisselbare beheersleutels die voor bedrijfscontinuïteit worden verstrekt voor het geval u een moet overschakelen. U kunt één van beide sleutels gebruiken om objecten toe te voegen, wijzigen of verwijderen.

   

Uw omgeving instellen

1. Start Visual Studio en open vervolgens DotNetHowToIndexers.sln.

2. Open appsettings.json in Solution Explorer om verbindingsgegevens op te geven.

3. Voor SearchServiceEndPoint: als de volledige URL op de pagina Overzicht van uw service https://my-demo-service.search.windows.net is, geef dan de volledige URL op.

4. Voor AzureSqlConnectionStringis de tekenreeksindeling vergelijkbaar met "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. Vervang het gebruikerswachtwoord in de SQL-verbindingsreeks door een geldig wachtwoord. Terwijl de database en gebruikersnamen worden gekopieerd, moet u het wachtwoord handmatig invoeren.

De pijplijn maken

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

• hotel.cs een schema bevat waarmee de index wordt gedefinieerd
• Program.cs bevat functies voor het maken en beheren van structuren in uw service

In hotel.cs

Het indexschema definieert de verzameling velden, inclusief kenmerken die toegestane bewerkingen opgeven, zoals of een veld doorzoekbaar, filterbaar of sorteerbaar is, 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 voor het stimuleren van een zoekscore en aangepaste analyse. Voor deze zelfstudie is het schema echter spaarzaam gedefinieerd, dat alleen bestaat uit velden die in de voorbeelddatasets worden aangetroffen.

In Program.cs

Het hoofdprogramma bevat logica voor het maken van een indexeerclient, een index, een gegevensbron en een indexeerfunctie. De code controleert en verwijdert bestaande resources van dezelfde naam, ervan uitgaande dat u dit programma meerdere keren kunt uitvoeren.

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 demohotels als bron in Azure SQL heeft een kolom genaamd IsDeleted voor soft delete. 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 indexeerobject is platformneutraal, waarbij configuratie, planning en aanroep hetzelfde zijn, ongeacht de bron. Deze voorbeeldindexeerfunctie bevat een schema en een optie voor opnieuw instellen waarmee de geschiedenis van de indexeerfunctie wordt gewist. Er wordt ook een methode aangeroepen om de indexeerfunctie onmiddellijk te maken en uit te voeren. Om een indexer te maken of bij te werken, 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);
}

De oplossing bouwen

Selecteer 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:

• Verbindingsgegevens van de zoekservice die u opgeeft, zijn de volledige URL. Als u alleen de servicenaam hebt ingevoerd, stoppen de bewerkingen tijdens het maken van de index, met een verbindingsfout.

• 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 toegang hebben tot de firewall voor binnenkomende verbindingen.

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

Zoeken

Gebruik Azure Portal om het maken van objecten te verifiëren en gebruik vervolgens Search Explorer om een query uit te voeren op de index.

1. Meld u aan bij Azure Portal en ga naar uw zoekservice. Open in het linkerdeelvenster elke pagina om te controleren of de objecten zijn gemaakt. Indexen, indexeerfuncties en gegevensbronnen moeten respectievelijk hotels-sql-idx, hotels-sql-indexer en hotels-sql-ds hebben.

2. Selecteer op het tabblad Indexen de index hotels-sql-idx . Search Explorer is het eerste tabblad op de pagina hotels.

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

   

4. Schakel over naar de JSON-weergave , zodat u queryparameters kunt invoeren.

   {
        "search": "river",
        "count": true
   }
   

   Met deze query wordt zoeken in volledige tekst op de term riveraangeroepen. Het resultaat bevat een telling van de overeenkomende documenten. Het retourneren van het aantal overeenkomende documenten is handig in testscenario's waarbij u een grote index hebt met duizenden of miljoenen documenten. In dit geval komt slechts één document overeen met de query.

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

Middelen opschonen

Wanneer u in uw eigen abonnement werkt, is het aan het einde van een project een goed idee om de resources die u niet meer nodig hebt te 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 de Azure-portal met behulp van de koppeling Alle resources of Resourcegroepen in het linkernavigatie-deelvenster.

Volgende stappen

Nu u bekend bent met de basisprincipes van het indexeren van SQL Database, gaat u dieper in op de configuratie van de indexeerfunctie: