Tutorial: Indizieren von Azure SQL-Daten mithilfe des .NET SDK

Artikel
09/25/2024

Konfigurieren Sie einen Indexer, um durchsuchbare Daten aus Azure SQL-Datenbank zu extrahieren und an einen Suchindex in Azure KI Search zu senden.

In diesem Tutorial werden C# und das Azure SDK für .NET verwendet, um die folgenden Aufgaben auszuführen:

Erstellen einer mit Azure SQL-Datenbank verbundenen Datenquelle
Erstellen eines Indexers
Ausführen eines Indexers, um Daten in einen Index zu laden
Abfragen eines Index als Überprüfungsschritt

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Voraussetzungen

Azure SQL-Datenbank unter Verwendung der SQL Server-Authentifizierung
Visual Studio
Azure KI Search. Neuer oder bereits vorhandener Suchdienst

Hinweis

Sie können einen kostenlosen Suchdienst für dieses Tutorial verwenden. Der Free-Tarif ist auf drei Indizes, drei Indexer und drei Datenquellen beschränkt. In diesem Tutorial wird davon jeweils eine Instanz erstellt. Vergewissern Sie sich zunächst, dass Ihr Dienst über genügend freie Kapazität für die neuen Ressourcen verfügt.

Herunterladen von Dateien

Der Quellcode für dieses Tutorial befindet sich im Ordner DotNetHowToIndexer des GitHub-Repositorys Azure-Samples/search-dotnet-getting-started.

1\. Erstellen der Dienste

In diesem Tutorial wird Azure KI Cognitive Search für die Indizierung und für Abfragen und Azure SQL-Datenbank als externe Datenquelle verwendet. Erstellen Sie beide Dienste nach Möglichkeit in derselben Region und Ressourcengruppe, um eine möglichst große Nähe zu erreichen und die Verwaltung zu vereinfachen. In der Praxis kann sich Azure SQL-Datenbank in einer beliebigen Region befinden.

Beginnen mit Azure SQL-Datenbank

Dieses Tutorial enthält hotels.sql -Datei im Beispieldownload, um die Datenbank aufzufüllen. Azure KI Search nutzt vereinfachte Rowsets, wie sie beispielsweise auf der Grundlage einer Sicht oder Abfrage generiert werden. Die SQL-Datei in der Beispielprojektmappe erstellt eine einzelne Tabelle und füllt sie auf.

Falls Sie bereits über eine Azure SQL-Datenbank-Ressource verfügen, können Sie ihr ab dem Schritt zum Öffnen der Abfrage die Hoteltabelle hinzufügen.

Erstellen Sie eine Azure SQL-Datenbank mithilfe der Anweisungen in Schnellstart: Erstellen einer einzelnen Datenbank.

Die Serverkonfiguration für die Datenbank ist wichtig.
- Wählen Sie die SQL Server-Authentifizierungsoption aus, mit der Sie aufgefordert werden, einen Benutzernamen und ein Kennwort anzugeben. Sie benötigen dies für die vom Indexer verwendete ADO.NET-Verbindungszeichenfolge.
- Wählen Sie eine öffentliche Verbindung aus. Es erleichtert das Abschließen dieses Tutorials. Die Einstellung „Öffentlich“ wird nicht für die Produktion empfohlen, und wir empfehlen am Ende des Tutorials, diese Ressource zu löschen.
Wechseln Sie im Azure-Portal zur neuen Ressource.
Fügen Sie eine Firewallregel hinzu, um den Zugriff von Ihrem Client zuzulassen, indem Sie die Anweisungen in Schnellstart: Erstellen einer Firewallregel auf Serverebene im Azure-Portal verwenden. Sie können ipconfig über eine Eingabeaufforderung ausführen, um Ihre IP-Adresse abzurufen.
Verwenden Sie den Abfrage-Editor, um die Beispieldaten zu laden. Wählen Sie im Navigationsbereich den Abfrage-Editor (Vorschau) aus und geben Sie den Benutzernamen und das Kennwort des Serveradministrators ein.

Wenn ein Fehler mit der Nachricht „Zugriff verweigert“ angegeben wird, kopieren Sie die Client-IP-Adresse aus der Fehlermeldung, öffnen Sie die Netzwerksicherheitsseite für den Server, und fügen Sie eine eingehende Regel hinzu, die den Zugriff von Ihrem Client zulässt.
Wählen Sie im Abfrage-Editor Abfrage öffnen aus und navigieren Sie zum Speicherort der Datei hotels.sql auf Ihrem lokalen Computer.
Wählen Sie die Datei und dann Öffnen aus. Das Skript sollte in etwa wie im folgenden Screenshot aussehen:
Klicken Sie auf Ausführen, um die Abfrage auszuführen. Im Ergebnisbereich sollte eine Erfolgsmeldung für drei Zeilen angezeigt werden.
Wenn Sie ein Rowset aus dieser Tabelle zurückgeben möchten, können Sie als Überprüfungsschritt die folgende Abfrage ausführen:
```
SELECT * FROM Hotels
```

Kopieren Sie die ADO.NET-Verbindungszeichenfolge für die Datenbank. Kopieren Sie unter Einstellungen>Verbindungszeichenfolgen die ADO.NET-Verbindungszeichenfolge (ähnlich wie im folgenden Beispiel).

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;

Sie benötigen diese Verbindungszeichenfolge in der nächsten Übung, wenn Sie Ihre Umgebung einrichten.

Azure KI Search

Die nächste Komponente ist Azure KI-Suche, die Sie im Azure-Portal erstellen können. Im Rahmen dieser exemplarischen Vorgehensweise können Sie den Free-Tarif verwenden.

Abrufen eines Administrator-API-Schlüssels und einer URL für Azure KI Search

Für API-Aufrufe benötigen Sie die Dienst-URL und einen Zugriffsschlüssel. Hierfür wird jeweils ein Suchdienst erstellt. Wenn Sie Azure AI Search also Ihrem Abonnement hinzugefügt haben, können Sie diese Schritte ausführen, um die erforderlichen Informationen zu erhalten:

Melden Sie sich beim Azure-Portal an, und rufen Sie auf der Seite Übersicht Ihres Suchdiensts die URL ab. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.
Rufen Sie unter Einstellungen>Schlüssel einen Administratorschlüssel ab, um Vollzugriff auf den Dienst zu erhalten. Es gibt zwei austauschbare Administratorschlüssel – diese wurden zum Zweck der Geschäftskontinuität bereitgestellt, falls Sie einen Rollover für einen Schlüssel durchführen müssen. Für Anforderungen zum Hinzufügen, Ändern und Löschen von Objekten können Sie den primären oder den sekundären Schlüssel verwenden.

2\. Einrichten Ihrer Umgebung

Starten Sie Visual Studio, und öffnen Sie DotNetHowToIndexers.sln.
Öffnen Sie im Projektmappen-Explorer die Datei appsettings.json, um Verbindungsinformationen anzugeben.
Wenn die vollständige URL auf der Dienstübersichtsseite „https://my-demo-service.search.windows.net"“ lautet, muss als Wert für SearchServiceEndPoint die gesamte URL angegeben werden.
Für AzureSqlConnectionString lautet das Zeichenfolgenformat in etwa wie folgt: "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",
}
```
Ersetzen Sie das Benutzerkennwort in der SQL-Verbindungszeichenfolge durch ein gültiges Kennwort. Die Datenbank und die Benutzernamen werden kopiert, aber das Kennwort muss manuell eingegeben werden.

3\. Erstellen der Pipeline

Für Indexer werden ein Datenquellenobjekt und ein Index benötigt. Der relevante Code befindet sich in zwei Dateien:

hotel.cs enthält ein Schema zum Definieren des Index.
Program.cs enthält Funktionen zum Erstellen und Verwalten von Strukturen in Ihrem Dienst.

hotel.cs

Das Indexschema definiert die Sammlung „fields“ einschließlich Attributen zur Angabe zulässiger Vorgänge (beispielsweise, ob in einem Feld eine Volltextsuche möglich ist oder ob es gefiltert oder sortiert werden kann), wie in der folgenden Felddefinition für „HotelName“ zu sehen. Ein durchsuchbares Feld (SearchableField) kann definitionsgemäß für die Volltextsuche verwendet werden. Andere Attribute werden explizit zugewiesen.

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

Ein Schema kann auch andere Elemente enthalten. Hierzu zählen beispielsweise Bewertungsprofile zur Erhöhung einer Suchbewertung, benutzerdefinierte Analysen und andere Konstrukte. Für unsere Zwecke reicht jedoch eine einfache Schemadefinition, die lediglich Felder aus den Beispieldatasets enthält.

Program.cs

Das Hauptprogramm enthält Logik zum Erstellen eines Indexerclients, eines Index, einer Datenquelle und eines Indexers. Der Code sucht und löscht vorhandene Ressourcen mit dem gleichen Namen (unter der Annahme, dass Sie dieses Programm ggf. mehrmals ausführen).

Das Datenquellenobjekt wird mit Einstellungen konfiguriert, die speziell für Ressourcen von Azure SQL-Datenbank gelten, z. B. partielle oder inkrementelle Indizierung zur Nutzung der integrierten Features für die Erkennung von Änderungen von Azure SQL. Die Demoquelldatenbank „hotels“ in Azure SQL enthält eine Spalte für vorläufiges Löschen mit dem Namen IsDeleted. Wenn diese Spalte in der Datenbank auf „true“ festgelegt ist, entfernt der Indexer das entsprechende Dokument aus dem Azure KI Search-Index.

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

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

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Ein Indexerobjekt ist plattformagnostisch. Dies bedeutet, dass die Konfiguration, die Zeitplanung und das Aufrufen unabhängig von der Quelle gleich sind. Dieses Indexerbeispiel enthält einen Zeitplan und eine Zurücksetzungsoption, mit der der Verlauf des Indexers gelöscht wird. Außerdem wird eine Methode zum sofortigen Erstellen und Ausführen des Indexers aufgerufen. Verwenden Sie CreateOrUpdateIndexerAsync, um einen Indexer zu erstellen oder zu aktualisieren.

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);

Indexerausführungen sind in der Regel geplant. Im Rahmen der Entwicklung kann der Indexer mithilfe von RunIndexerAsync aber auch sofort ausgeführt werden.

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\. Erstellen der Projektmappe

Drücken Sie F5, um die Lösung zu erstellen und auszuführen. Das Programm wird im Debugmodus ausgeführt. Ein Konsolenfenster gibt Aufschluss über den Status der einzelnen Vorgänge.

Der Code wird lokal in Visual Studio ausgeführt und stellt eine Verbindung mit Ihrem Suchdienst in Azure her, der wiederum eine Verbindung mit Azure SQL-Datenbank herstellt und das Dataset abruft. Die hohe Anzahl von Vorgängen hat mehrere potenzielle Fehlerquellen zur Folge. Überprüfen Sie im Falle eines Fehlers zunächst Folgendes:

Bei den von Ihnen angegebenen Verbindungsinformationen für den Suchdienst handelt es sich um die vollständige URL. Falls Sie lediglich den Dienstnamen eingegeben haben, werden die Vorgänge bei der Indexerstellung mit einem Verbindungsfehler beendet.
Datenbank-Verbindungsinformationen in appsettings.json: Hierbei muss es sich um die ADO.NET-Verbindungszeichenfolge aus dem Azure-Portal handeln, die mit einem gültigen Benutzernamen und einem Kennwort für die Datenbank versehen wurde. Das Benutzerkonto muss über Datenabrufberechtigungen verfügen. Ihrer lokalen Client-IP-Adresse muss über die Firewall eingehender Zugriff gewährt worden sein.
Ressourceneinschränkungen: Bedenken Sie, dass für den Free-Tarif eine Obergrenze von drei Indizes, Indexern und Datenquellen gilt. Ist die Obergrenze für einen Dienst erreicht, können keine neuen Objekte mehr erstellt werden.

5\. Suchen

Vergewissern Sie sich im Azure-Portal, dass die Objekterstellung erfolgreich war, und verwenden Sie anschließend den Suchexplorer, um den Index abzufragen.

Melden Sie sich beim Azure-Portal an, und öffnen Sie auf Ihrem Suchdienst im linken Navigationsbereich jede Seite, um sich zu vergewissern, dass das Objekt erstellt wurde. Indexe, Indexer und Datenquellen enthalten „hotels-sql-idx“, „hotels-sql-indexer“, und „hotels-sql-ds“.
Wählen Sie auf der Registerkarte „Indizes“ den hotels-sql-idx-Index aus. Auf der Seite „hotels“ ist Suchexplorer die erste Registerkarte.
Wählen Sie Suchen aus, um eine leere Abfrage auszugeben.

Die drei Einträge in Ihrem Index werden als JSON-Dokumente zurückgegeben. Der Suchexplorer gibt Dokumente im JSON-Format zurück, sodass Sie sich die gesamte Struktur ansehen können.
Wechseln Sie als Nächstes zu JSON-Ansicht, damit Sie Abfrageparameter eingeben können:
```
{
     "search": "river",
     "count": true
}
```
Diese Abfrage führt eine Volltextsuche nach dem Begriff river durch, und das Ergebnis enthält die Anzahl passender Dokumente. Die Rückgabe der Anzahl passender Dokumente ist hilfreich in Testszenarien mit einem umfangreichen Index mit tausenden oder Millionen von Dokumenten. In diesem Fall entspricht der Abfrage lediglich ein einzelnes Dokument.
Geben Sie schließlich Parameter ein, die Suchergebnisse auf Interessenfelder beschränken:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
Die Abfrageantwort wird auf die ausgewählten Felder beschränkt, um eine präzisere Ausgabe zu erhalten.

Zurücksetzen und erneut ausführen

In den frühen experimentellen Phasen der Entwicklung ist es am praktischsten, die Objekt aus Azure KI-Suche zu löschen und sie durch Ihren Code neu zu erstellen. Ressourcennamen sind eindeutig. Wenn Sie ein Objekt löschen, können Sie es unter dem gleichen Namen neu erstellen.

Im Beispielcode dieses Tutorials wird eine Überprüfung auf vorhandene Objekte durchgeführt. Diese werden dann gelöscht, damit Sie Ihren Code erneut ausführen können.

Sie können das Azure-Portal auch verwenden, um Indizes, Indexer und Datenquellen zu löschen.

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, ist es ratsam, nach Abschluss eines Projekts die nicht mehr benötigten Ressourcen zu entfernen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können einzelne Ressourcen oder die gesamte Ressourcengruppe mit allen darin enthaltenen Ressourcen löschen.

Sie können Ressourcen im Azure-Portal über den Link „Alle Ressourcen“ oder „Ressourcengruppen“ im linken Navigationsbereich suchen und verwalten.

Nächste Schritte

Nachdem Sie sich nun mit den Grundlagen der SQL-Datenbankindizierung vertraut gemacht haben, können Sie sich die Indexerkonfiguration genauer ansehen.

Konfigurieren eines SQL-Datenbank-Indexers

Freigeben über