Indizieren von Daten aus Azure Table Storage

Artikel
02/22/2024

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

Azure Table Storage
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 Daten und Leser-Berechtigungen verfügt.
Verwenden Sie einen REST-Client, wenn Sie REST-Aufrufe formulieren wollen, die den in diesem Artikel gezeigten ähnlich sind.

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=2023-11-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 000 bis 100 zu 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=2023-11-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 1 lautet und der Zeilenschlüssel den Wert 1_123 hat, lautet der Schlüsselwert 11_123. Wenn der Partitionsschlüssel NULL ist, wird nur der Zeilenschlüssel verwendet.

Wenn Sie den Index mithilfe des Assistenten zum Importieren von Daten erstellen, leitet das 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=2023-11-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,
        "base64EncodeKeys" : 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, senden Sie eine Anforderung zum Abrufen des Indexerstatus:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

Die Antwort enthält den Status und die Anzahl der verarbeiteten Elemente. Sie sollte in etwa wie das folgende Beispiel aussehen:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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: