Indizieren von Daten aus Azure Table Storage
In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus Azure Table Storage importiert und in Azure KI Search durchsuchbar macht. Eingaben für den Indexer sind Ihre Entitäten in einer einzelnen Tabelle. Die Ausgabe ist ein Suchindex mit durchsuchbaren Inhalten und Metadaten, die in einzelnen Feldern gespeichert sind.
Dieser Artikel ergänzt den Artikel Erstellen von Indexern in Azure Cognitive Search mit spezifischen Informationen zur Indizierung von Azure Table Storage. Er verwendet das Azure-Portal und die REST-APIs, um einen dreiteiligen Workflow zu veranschaulichen, der allen Indexern gemeinsam ist: Erstellen einer Datenquelle, Erstellen eines Indexes und Erstellen eines Indexers. Die Datenextraktion erfolgt, wenn Sie die Anforderung für die Indexererstellung übermitteln.
Voraussetzungen
Tabellen, die Text enthalten. Wenn Sie binäre Daten haben, sollten die KI-Anreicherung für die Bildanalyse in Erwägung ziehen.
Leseberechtigungen für Azure Storage. Eine „Vollzugriff“-Verbindungszeichenfolge enthält einen Schlüssel, der Zugriff auf den Inhalt gewährt. Wenn Sie jedoch Azure-Rollen verwenden, stellen Sie sicher, dass die verwaltete Identität des Suchdiensts über die Berechtigungen Leser und Datenzugriff verfügt.
Um die Beispiele in diesem Artikel durchzuarbeiten, benötigen Sie das Azure-Portal oder einen REST-Client. Wenn Sie das Azure-Portal verwenden, stellen Sie sicher, dass der Zugriff auf alle öffentlichen Netzwerke aktiviert ist. Andere Ansätze zum Erstellen eines Azure Table-Indexers beinhalten Azure SDKs.
Mit Beispieldaten testen
Verwenden Sie diese Anweisungen, um eine Tabelle in Azure Storage zu Testzwecken zu erstellen.
Melden Sie sich beim Azure-Portal an, navigieren Sie zu Ihrem Speicherkonto, und erstellen Sie eine Tabelle mit dem Namen Hotels.
Laden Sie HotelsData_toAzureSearch.csv von GitHub herunter. Diese Datei ist eine Teilmenge des integrierten Beispiel-Datasets für Hotels. Die Räumesammlung, übersetzte Beschreibungen und geografischen Koordinaten werden weggelassen.
Melden Sie sich im Azure Storage-Explorer bei Azure an, wählen Sie Ihr Abonnement und dann Ihr Speicherkonto aus.
Öffnen Sie Tabellen, und wählen Sie Hotels aus.
Wählen Sie Importieren auf der Befehlsleiste aus, und wählen Sie dann die Datei HotelsData_toAzureSearch.csv aus.
Übernehmen Sie die Standardeinstellungen. Wählen Sie Importieren aus, um die Daten zu laden.
Sie sollten über 50 Hoteldatensätze in der Tabelle mit einem automatisch generierten partitionKey, rowKey und Zeitstempel verfügen. Sie können diesen Inhalt jetzt für die Indizierung im Azure-Portal, REST-Client oder einem Azure SDK verwenden.
Das Feld „Beschreibung“ stellt den ausführlichsten Inhalt bereit. Sie sollten dieses Feld für die Volltextsuche und optionale Vektorabfragen verwenden.
Verwenden des Azure-Portals
Sie können entweder den Datenimport-Assistenten oder den Assistenten zum Importieren und Vektorisieren von Daten verwenden, um die Indizierung aus einer SQL-Datenbanktabelle oder -Ansicht zu automatisieren. Die Datenquellenkonfiguration ist für beide Assistenten ähnlich.
Aktivieren oder überprüfen Sie unter Verbindung mit Ihren Daten, ob der Datenquellentyp Azure Table Storage ist oder dass die Datenauswahlfelder zur Eingabe von Tabellen aufgefordert werden.
Der Name der Datenquelle bezieht sich auf das Datenquellenverbindungsobjekt in der Azure KI-Suche. Wenn Sie den Vektor-Assistenten verwenden, wird der Datenquellenname automatisch mit einem benutzerdefinierten Präfix generiert, das am Ende des Assistenten-Workflows angegeben wird.
Geben Sie das Speicherkonto und den Namen der Tabelle an. Die Abfrage ist optional. Sie ist nützlich, wenn Sie bestimmte Spalten haben, die Sie importieren möchten.
Geben Sie eine Authentifizierungsmethode an; entweder eine verwaltete Identität oder einen integrierten API-Schlüssel. Wenn Sie keine Verbindung mit verwalteter Identität angeben, verwendet das Azure-Portal den Schlüssel.
Wenn Sie Azure KI-Suche für die Verwendung einer verwalteten Identität konfigurieren und eine Rollenzuweisung in Azure Storage erstellen, die die Berechtigungen Leser und Datenzugriff für die Identität gewährt, kann Ihr Indexer mithilfe von Microsoft Entra ID und Rollen eine Verbindung mit dem Tabellenspeicher herstellen.
Für den Assistenten zum Importieren und Vektorisieren von Daten können Sie Optionen für die Löscherkennung angeben,
Für die Löscherkennung müssen Sie über ein bereits vorhandenes Feld in der Tabelle verfügen, das als Flag „Vorläufiges Löschen“ verwendet werden kann. Es sollte sich um ein boolesches Feld (Sie könnten es „IsDeleted“ nennen) handeln. Geben Sie als Wert für das vorläufige Löschen
truean. Fügen Sie im Suchindex ein entsprechendes Suchfeld namens IsDeleted hinzu, dass auf abrufbar und filterbar festgelegt ist.Fahren Sie mit den verbleibenden Schritten fort, um den Assistenten abzuschließen:
Verwenden der REST-APIs
In diesem Abschnitt werden die REST-API-Aufrufe veranschaulicht, die eine Datenquelle, einen Index und einen Indexer erstellen.
Definieren der Datenquelle
Die Datenquellendefinition gibt die zu indizierenden Quelldaten, die Anmeldeinformationen und die Richtlinien für die Änderungserkennung an. Eine Datenquelle ist eine unabhängige Ressource, welche von mehreren Indexern verwendet werden kann.
Erstellen oder aktualisieren Sie eine Datenquelle, um ihre Definition festzulegen:
POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 { "name": "my-table-storage-ds", "description": null, "type": "azuretable", "subtype": null, "credentials": { "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>" }, "container": { "name": "my-table-in-azure-storage", "query": "" }, "dataChangeDetectionPolicy": null, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }Legen Sie "type" auf
"azuretable"fest (erforderlich).Legen Sie "credentials" auf eine Azure Storage-Verbindungszeichenfolge fest. Im nächsten Abschnitt werden die unterstützten Formate beschrieben.
Legen Sie "container" auf den Namen der Tabelle fest.
Legen Sie "query" optional auf einen Filter für PartitionKey fest. Das Festlegen dieser Eigenschaft ist eine bewährte Methode, welche die Leistung verbessert. Wenn "query" null ist, führt der Indexer eine vollständige Tabellenüberprüfung durch, was zu einer schlechten Leistung führen kann, wenn die Tabellen groß sind.
Eine Datenquellendefinition kann auch Richtlinien für vorläufiges Löschen enthalten, wenn der Indexer ein Suchdokument löschen soll, wenn das Quelldokument für den Löschvorgang gekennzeichnet ist.
Unterstützte Anmeldeinformationen und Verbindungszeichenfolgen
Indexer können mithilfe der folgenden Verbindungen eine Verbindung mit einer Tabelle herstellen.
| Verbindungszeichenfolge für den Vollzugriff auf ein Speicherkonto |
|---|
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" } |
| Sie können die Verbindungszeichenfolge von der Speicherkontoseite im Azure-Portal abrufen, indem Sie im linken Navigationsbereich auf Zugriffsschlüssel klicken. Stellen Sie sicher, dass Sie eine vollständige Verbindungszeichenfolge und nicht nur einen Schlüssel auswählen. |
| Verbindungszeichenfolge für verwaltete Identitäten |
|---|
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" } |
| Diese Verbindungszeichenfolge erfordert keinen Kontoschlüssel, aber Sie müssen zuvor einen Suchdienst für das Herstellen einer Verbindung mithilfe einer verwalteten Identität konfiguriert haben. |
| SAS-Verbindungszeichenfolge (Shared Access Signature**) für ein Speicherkonto |
|---|
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" } |
| Die SAS muss über Listen- und Leseberechtigungen für die Tabellen und Entitäten verfügen. |
| Shared Access Signature des Containers |
|---|
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" } |
| Die SAS muss über Listen- und Leseberechtigungen für den Container verfügen. Weitere Informationen finden Sie unter Gewähren von eingeschränktem Zugriff auf Azure Storage-Ressourcen mithilfe von SAS (Shared Access Signature). |
Hinweis
Bei Verwendung von SAS-Anmeldeinformationen müssen Sie die Anmeldedaten für die Datenquellen in regelmäßigen Abständen mit erneuerten Signaturen aktualisieren, um den Ablauf zu verhindern. Wenn SAS-Anmeldeinformationen ablaufen, zeigt der Indexer eine Fehlermeldung wie „Die in der Verbindungszeichenfolge angegebenen Anmeldeinformationen sind ungültig oder abgelaufen“ an.
Partitionierung für verbesserte Leistung
Standardmäßig verwendet Azure KI Search den folgenden internen Abfragefilter, um nachzuverfolgen, welche Quell-Entitäten seit der letzten Ausführung aktualisiert wurden: Timestamp >= HighWaterMarkValue. Da Azure-Tabellen keinen sekundären Index im Timestamp-Feld besitzen, erfordert dieser Abfragetyp einen vollständigen Tabellenscan und ist daher bei großen Tabellen langsam.
Um eine vollständige Überprüfung zu vermeiden, können Sie Tabellenpartitionen verwenden, um den Bereich jedes Indexerauftrags zu beschränken.
Wenn Ihre Daten auf natürliche Weise in mehrere Bereiche partitioniert werden können, erstellen Sie eine Datenquelle und einen entsprechenden Indexer für jeden Partitionsbereich. Jeder Indexer muss jetzt nur einen bestimmten Partitionsbereich verarbeiten, was die Abfrageleistung verbessert. Wenn die zu indizierenden Daten auf eine kleine Anzahl fester Partitionen verteilt sind, ist dies noch besser – jeder Indexer führt dann nur einen Partitionsscan durch.
Um beispielsweise eine Datenquelle für die Verarbeitung eines Partitionsbereichs mit Schlüsseln von
000bis100zu erstellen, verwenden Sie etwa folgende Abfrage:"container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }.Wenn Ihre Daten nach der Zeit partitioniert sind (z. B. wenn Sie jeden Tag oder jede Woche eine neue Partition erstellen), ziehen Sie folgenden Ansatz in Betracht:
Geben Sie in der Datenquellendefinition eine Abfrage an, die dem folgenden Beispiel ähnelt:
(PartitionKey ge <TimeStamp>) and (other filters).Überwachen Sie den Indexerverlauf mit der API zum Abrufen des Indexerstatus, und aktualisieren Sie regelmäßig die
<TimeStamp>-Bedingung der Abfrage basierend auf dem aktuellen Markierungswert für die Obergrenze.Wenn Sie mit diesem Ansatz eine vollständige Neuindizierung auslösen müssen, setzen Sie die zusätzlich zu dem Zurücksetzen des Indexers die Datenquellenabfrage zurück.
Hinzufügen von Suchfeldern zu einem Index
Fügen Sie in einem Suchindex Felder hinzu, um den Inhalt und die Metadaten Ihrer Tabellenentitäten zu akzeptieren.
Erstellen oder aktualisieren Sie einen Index, um Suchfelder zu definieren, in denen Inhalte aus Entitäten gespeichert werden:
POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 { "name" : "my-search-index", "fields": [ { "name": "Key", "type": "Edm.String", "key": true, "searchable": false }, { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true } ] }Erstellen Sie ein Dokumentschlüsselfeld ("key": true), lassen Sie es jedoch vom Indexer automatisch auffüllen. Ein Tabellenindexer füllt das Schlüsselfeld mit verketteten Partitions- und Zeilenschlüsseln aus der Tabelle auf. Wenn der Partitionsschlüssel einer Zeile beispielsweise
1lautet und der Zeilenschlüssel den Wert1_123hat, lautet der Schlüsselwert11_123. Wenn der Partitionsschlüssel NULL ist, wird nur der Zeilenschlüssel verwendet.Wenn Sie den Index mithilfe des Datenimport-Assistenten erstellen, leitet das Azure-Portal ein Feld „Schlüssel“ für den Suchindex ab und verwendet eine implizite Feldzuordnung, um die Quell- und Zielfelder zu verbinden. Sie müssen das Feld nicht selbst hinzufügen, und Sie müssen keine Feldzuordnung einrichten.
Wenn Sie die REST-APIs verwenden und implizite Feldzuordnungen benötigen, erstellen Sie das Dokumentschlüsselfeld "Schlüssel" in der Suchindexdefinition, wie im vorherigen Schritt gezeigt (
{ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). Der Indexer füllt das Schlüsselfeld automatisch auf, ohne dass Feldzuordnungen erforderlich sind.Wenn Sie kein Feld mit dem Namen "Key" in Ihrem Suchindex verwenden möchten, fügen Sie in der Indexerdefinition eine explizite Feldzuordnung mit dem gewünschten Feldnamen hinzu, und legen Sie das Quellfeld als "Schlüssel" fest:
"fieldMappings" : [ { "sourceFieldName" : "Key", "targetFieldName" : "MyDocumentKeyFieldName" } ]Fügen Sie nun alle anderen Entitätsfelder hinzu, die Sie in Ihrem Index verwenden möchten. Wenn eine Entität beispielsweise wie im folgenden Beispiel aussieht, sollte Ihr Suchindex Felder für „HotelName“, „Description“ und „Category“ enthalten, um diese Werte zu erhalten.
Die Verwendung der gleichen Namen und kompatiblen Datentypen minimiert die Notwendigkeit von Feldzuordnungen. Wenn Namen und Typen identisch sind, kann der Indexer den Datenpfad automatisch bestimmen.
Konfigurieren und Ausführen des Tabellenindexers
Sobald Sie über einen Index und eine Datenquelle verfügen, können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern.
Erstellen oder aktualisieren Sie den Indexer, indem Sie ihm einen Namen geben und einen Verweis auf die Datenquelle und den Zielindex hinzufügen:
POST https://[service name].search.windows.net/indexers?api-version=2024-07-01 { "name" : "my-table-indexer", "dataSourceName" : "my-table-storage-ds", "targetIndexName" : "my-search-index", "disabled": null, "schedule": null, "parameters" : { "batchSize" : null, "maxFailedItems" : null, "maxFailedItemsPerBatch" : null, "configuration" : { } }, "fieldMappings" : [ ], "cache": null, "encryptionKey": null }Geben Sie Feldzuordnungen an, wenn es Unterschiede beim Feldnamen oder -typ gibt, oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen. Das Zielfeld ist der Name des Feldes im Suchindex.
"fieldMappings" : [ { "sourceFieldName" : "Description", "targetFieldName" : "HotelDescription" } ]Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen von Indexern in Azure Cognitive Search.
Ein Indexer wird automatisch ausgeführt, wenn er erstellt wird. Sie können dies verhindern, indem Sie „disabled“ (Deaktiviert) auf „true“ festlegen. Um die Ausführung des Indexers zu steuern, führen Sie einen Indexer nach Bedarf aus, oder legen Sie für ihn einen Zeitplan fest.
Überprüfen des Indexerstatus
Um den Indexerstatus und den Ausführungsverlauf zu überwachen, überprüfen Sie den Indexerausführungsverlauf im Azure-Portal, oder senden Sie die REST-API-Anforderung Get Indexer Status.
Öffnen Sie auf der Suchdienstseite Suchverwaltung>Indexer.
Wählen Sie einen Indexer aus, um auf den Konfigurations- und Ausführungsverlauf zuzugreifen.
Wählen Sie einen bestimmten Indexerauftrag aus, um Details, Warnungen und Fehler anzuzeigen.
Der Ausführungsverlauf enthält bis zu 50 der zuletzt abgeschlossenen Ausführungen. Diese sind in umgekehrter chronologischer Reihenfolge sortiert, sodass die neueste Ausführung als Erstes aufgelistet wird.
Nächste Schritte
Erfahren Sie mehr darüber, wie Sie den Indexer ausführen, den Status überwachen oder die Ausführung des Indexers planen. Die folgenden Artikel gelten für Indexer, die Inhalte mithilfe von Pull Requests aus Azure Storage übertragen: