Indizieren von Daten aus Azure Data Lake Storage Gen2

In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus Azure Data Lake Storage (ADLS) Gen2 importiert und sie in Azure AI Search durchsuchbar macht. Eingaben für den Indexer sind Ihre Blobs, in einem einzelnen Container. Die Ausgabe ist ein Suchindex mit durchsuchbaren Inhalten und Metadaten, die in einzelnen Feldern gespeichert sind.

Dieser Artikel ergänzt Erstellen von Indexern in Azure Cognitive Search mit spezifischen Informationen zur Indizierung von ADLS Gen2 aus. 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.

Ein Codebeispiel in C# finden Sie unter Index Data Lake Gen2 mit Microsoft Entra ID auf GitHub.

Voraussetzungen

• ADLS Gen2 mit aktiviertem hierarchischen Namespace. ADLS Gen2 ist über Azure Storage verfügbar. Beim Einrichten eines Speicherkontos haben Sie die Möglichkeit, den hierarchischen Namespace zu aktivieren und Dateien in einer Hierarchie von Verzeichnissen und geschachtelten Unterverzeichnissen zu organisieren. Wenn Sie einen hierarchischen Namespace aktivieren, aktivieren Sie ADLS Gen2.

• Zugriffsebenen für ADLS Gen2 lauten „Heiß“, „Kalt“ und „Archiv“. Suchindexer können nur auf die heiße und kalte Ebene zugreifen.

• Blobs, die Text enthalten. Wenn Sie binäre Daten haben, können Sie die KI-Anreicherung für die Bildanalyse einschließen. Blob-Inhalte dürfen die Indexer-Limits für Ihre Suchdienstebene nicht überschreiten.

• Leseberechtigungen für Azure Storage. Eine „Vollzugriff“-Verbindungszeichenfolge enthält einen Schlüssel, der Zugriff auf den Inhalt gewährt. Wenn Sie jedoch stattdessen Azure-Rollen verwenden, stellen Sie sicher, dass die verwaltete Identität des Suchdiensts über die Storage-Blobdatenleser-Berechtigungen verfügt.

• Verwenden Sie einen REST-Client, wenn Sie REST-Aufrufe formulieren wollen, die den in diesem Artikel gezeigten ähnlich sind.

Unterstützte Dokumentformate

Der ADLS Gen2-Indexer kann Text aus den folgenden Dokumentformaten extrahieren:

• CSV (siehe Indizierung von CSV-Blobs)
• EML
• EPUB
• GZ
• HTML
• JSON (Siehe Indizierung von JSON-Blobs)
• KML (XML für geografische Darstellungen)
• Microsoft Office-Formate: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook-E-Mails), XML (WORD XML 2003 und 2006)
• Öffnen von Dokumentformaten: ODT, ODS, ODP
• PDF
• Textdateien (Siehe auch Indizierung von Nur-Text)
• RTF
• XML
• ZIP

Bestimmen der zu indizierenden Blobs

Überprüfen Sie vor dem Einrichten der Indizierung die Quelldaten, um zu ermitteln, ob Änderungen im Voraus vorgenommen werden sollten. Ein Indexer kann immer nur Inhalte aus einem Container gleichzeitig indizieren. Standardmäßig werden alle Blobs im Container verarbeitet. Sie haben mehrere Optionen für eine stärker selektive Verarbeitung:

• Platzieren von Blobs in einem virtuellen Ordner. Eine Indexer-Datenquellendefinition enthält einen „query“-Parameter, der einen virtuellen Ordner akzeptiert. Wenn Sie einen virtuellen Ordner angeben, werden nur die Blobs im Ordner indiziert.

• Ein- oder Ausschließen von Blobs nach Dateityp. Mithilfe der Liste der unterstützten Dokumentformate können Sie bestimmen, welche Blobs ausgeschlossen werden sollen. Beispielsweise können Sie Bild- oder Audiodateien ausschließen, die keinen durchsuchbaren Text bereitstellen. Diese Funktion wird über Konfigurationseinstellungen im Indexer gesteuert.

• Ein- oder Ausschließen beliebiger Blobs. Wenn Sie ein bestimmtes Blob aus irgendeinem Grund überspringen möchten, können Sie Blobs in Blob Storage die folgenden Metadateneigenschaften und -werte hinzufügen. Wenn der Indexer auf diese Eigenschaft stößt, überspringt er den Blob oder dessen Inhalt im Indizierungslauf.

  Name der Eigenschaft	Eigenschaftswert	Erklärung
  „AzureSearch_Skip“	"true"	Weist den Blobindexer an, das Blob vollständig zu überspringen. Weder die Metadaten- noch die Inhaltsextraktion werden versucht. Dies ist nützlich, wenn ein bestimmtes Blob wiederholt fehlschlägt und den Indizierungsprozess unterbricht.
  „AzureSearch_SkipContent“	"true"	Überspringt Inhalte und extrahiert nur die Metadaten. Dies entspricht der Einstellung "dataToExtract" : "allMetadata", die in den Konfigurationseinstellungen beschrieben sind, lediglich eingegrenzt auf ein bestimmtes Blob.

Wenn Sie keine Ein- oder Ausschlusskriterien einrichten, meldet der Indexer ein nicht berechtigtes Blob als Fehler und fährt fort. Wenn genügend Fehler auftreten, wird die Verarbeitung möglicherweise beendet. Sie können die Fehlertoleranz in den Konfigurationseinstellungen des Indexers angeben.

Ein Indexer erstellt in der Regel ein Suchdokument pro Blob, wobei der Textinhalt und die Metadaten als durchsuchbare Felder in einem Index erfasst werden. Wenn Blobs ganze Dateien sind, können Sie sie möglicherweise in mehrere Suchdokumente analysieren. Beispielsweise können Sie Zeilen in einer CSV-Datei analysieren, um ein Suchdokument pro Zeile zu erstellen.

Indizieren der Metadaten von Blobs

Blobmetadaten können auch indiziert werden. Dies ist hilfreich, wenn Sie der Meinung sind, dass eine der Standard- oder benutzerdefinierten Metadateneigenschaften für Filter und Abfragen nützlich ist.

Vom Benutzer angegebene Metadateneigenschaften werden wortgetreu extrahiert. Um die Werte zu erhalten, müssen Sie im Suchindex ein Feld des Typs Edm.String definieren, das den gleichen Namen hat wie der Metadatenschlüssel des Blobs. Wenn ein Blob beispielsweise über den Metadatenschlüssel Sensitivity mit dem Wert High verfügt, müssen Sie ein Feld mit dem Namen Sensitivity in Ihrem Suchindex definieren, das dann mit dem Wert High aufgefüllt wird.

Standard-Blobmetadateneigenschaften können in ähnlich benannte und typisierte Felder extrahiert werden, wie unten aufgeführt. Der Blobindexer erstellt automatisch interne Feldzuordnungen für diese Blobmetadateneigenschaften und konvertiert den ursprünglichen Bindestrichnamen („metadata-storage-name“) in einen entsprechenden Unterstrichnamen („metadata_storage_name“).

Sie müssen der Indexdefinition weiterhin die unterstrichenen Felder hinzufügen, aber Sie können Feldzuordnungen weglassen, da der Indexer die Zuordnung automatisch erstellt.

• metadata_storage_name (Edm.String): der Dateiname des Blobs. Für ein Blob mit dem Namen „/my-container/my-folder/subfolder/resume.pdf“ lautet der Wert dieses Felds beispielsweise resume.pdf.

• metadata_storage_path (Edm.String): der vollständigen URI des Blobs, einschließlich Speicherkonto. Beispiel: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

• metadata_storage_content_type (Edm.String): Inhaltstyp, der mit dem Code angegeben wird, den Sie zum Hochladen des Blobs verwendet haben. Beispiel: application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset): Zeitstempel der letzten Änderung des Blobs. In Azure KI Search wird dieser Zeitstempel zum Identifizieren geänderter Blobs verwendet, um die erneute Indizierung aller Elemente nach der ersten Indizierung zu vermeiden.

• metadata_storage_size (Edm.Int64): Blobgröße in Bytes.

• metadata_storage_content_md5 (Edm.String): MD5-Hash des Blobinhalts, sofern vorhanden.

• metadata_storage_sas_token (Edm.String): ein temporäres SAS Token, das von benutzerdefinierten Qualifikationen verwendet werden kann, um Zugriff auf den Blob zu erhalten. Dieses Token sollte nicht zur späteren Verwendung gespeichert werden, da es ablaufen kann.

Schließlich können auch alle Metadateneigenschaften, die für das Dokumentformat der zu indizierenden Blobs spezifisch sind, im Indexschema dargestellt werden. Weitere Informationen zu inhaltsspezifischen Metadaten finden Sie unter Eigenschaften von Inhaltsmetadaten.

Wichtig ist der Hinweis, dass Sie nicht für alle der oben genannten Eigenschaften Felder in Ihrem Suchindex definieren müssen. Erfassen Sie lediglich die Eigenschaften, die Sie für Ihre Anwendung benötigen.

Definieren der Datenquelle

Die Datenquellendefinition gibt die zu indizierenden Daten, die Anmeldeinformationen und die Richtlinien für die Identifizierung von Datenänderungen an. Eine Datenquelle wird als unabhängige Ressource definiert, sodass sie von mehreren Indexern verwendet werden kann.

1. Erstellen oder aktualisieren Sie eine Datenquelle, um ihre Definition festzulegen:

   {
       "name" : "my-adlsgen2-datasource",
       "type" : "adlsgen2",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
   }
   

2. Legen Sie "type" auf "adlsgen2" fest (erforderlich).

3. Legen Sie "credentials" auf eine Azure Storage-Verbindungszeichenfolge fest. Im nächsten Abschnitt werden die unterstützten Formate beschrieben.

4. Legen Sie "container" auf den Blobcontainer fest, und verwenden Sie „query“, um Unterordner anzugeben.

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 einem Blobcontainer herstellen.

Hinzufügen von Suchfeldern zu einem Index

Fügen Sie in einem Suchindex Felder hinzu, um den Inhalt und die Metadaten Ihrer Azure-Blobs zu akzeptieren.

1. Erstellen oder aktualisieren Sie einen Index, um Suchfelder zu definieren, in denen Blobinhalte und Metadaten gespeichert werden:

   {
       "name" : "my-search-index",
       "fields": [
           { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
           { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
           { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }     
       ]
   }
   

2. Erstellen Sie ein Dokumentschlüsselfeld („key“: true). Metadateneigenschaften sind die besten Kandidaten für Blobinhalte.

   • metadata_storage_path (Standard) vollständiger Pfad zum Objekt oder zur Datei. Das Schlüsselfeld („ID“ in diesem Beispiel) wird mit Werten aus „metadata_storage_path“ aufgefüllt, da es sich um die Standardeinstellung handelt.

   • metadata_storage_name kann nur verwendet werden, wenn Namen eindeutig sind. Wenn Sie dieses Feld als Schlüssel benötigen, verschieben Sie "key": true in diese Felddefinition.

   • Eine benutzerdefinierte Metadateneigenschaft, die Sie Blobs hinzufügen. Für diese Option ist es erforderlich, dass diese Metadateneigenschaft im Prozess des Hochladens von Blobs allen Blobs hinzugefügt wird. Da der Schlüssel eine erforderliche Eigenschaft ist, schlägt die Indizierung aller Blobs fehl, denen ein Wert fehlt. Wenn Sie eine benutzerdefinierte Metadateneigenschaft als Schlüssel verwenden, vermeiden Sie es, Änderungen an dieser Eigenschaft vorzunehmen. Indexer fügen doppelte Dokumente für denselben Blob hinzu, wenn sich die Schlüsseleigenschaft ändert.

   Metadateneigenschaften enthalten häufig Zeichen wie / und -, die für Dokumentschlüssel ungültig sind. Der Indexer codiert automatisch die Schlüsselmetadaten-Eigenschaft, ohne dass eine Konfiguration oder Feldzuordnung erforderlich ist.

3. Fügen Sie ein Feld „content“ hinzu, um extrahierten Text aus jeder Datei über die Eigenschaft „content“ des Blobs zu speichern. Sie sind nicht verpflichtet, diesen Namen zu verwenden, aber Sie können so die Vorteile impliziter Zuordnungen von Feldern nutzen.

4. Fügen Sie Felder für Standardmetadateneigenschaften hinzu. Der Indexer kann Eigenschaften von benutzerdefinierten Metadaten, Standardmetadaten und inhaltsspezifischen Metadaten lesen.

Konfigurieren und Ausführen des ADLS Gen2-Indexers

Nach der Erstellung von Index und Datenquelle können Sie den Indexer erstellen. Die Indexerkonfiguration gibt die Eingaben, Parameter und Eigenschaften an, die das Laufzeitverhalten steuern. Sie können auch angeben, welche Teile eines Blobs indiziert werden sollen.

1. Erstellen oder aktualisieren Sie den Indexer, indem Sie ihm einen Namen geben und einen Verweis auf die Datenquelle und den Zielindex hinzufügen:

   {
     "name" : "my-adlsgen2-indexer",
     "dataSourceName" : "my-adlsgen2-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Legen Sie „batchSize“ fest, wenn der Standardwert (10 Dokumente) die verfügbaren Ressourcen entweder nicht auslastet oder überlastet. Die Standardbatchgrößen sind datenquellenspezifisch. Bei der Blobindizierung wird eine Batchgröße von 10 Dokumenten unter Berücksichtigung der größeren durchschnittlichen Dokumentgröße festgelegt.

3. Steuern Sie unter „configuration“, welche Blobs basierend auf dem Dateityp indiziert werden, oder geben Sie dies nicht an, um alle Blobs abzurufen.

   Geben Sie für "indexedFileNameExtensions" eine durch Trennzeichen getrennte Liste der Dateierweiterungen an (mit vorangestelltem Punkt). Machen Sie dasselbe für "excludedFileNameExtensions", um anzugeben, welche Erweiterungen übersprungen werden sollen. Wenn dieselbe Erweiterung in beiden Listen vorhanden ist, wird sie von der Indizierung ausgeschlossen.

4. Legen Sie unter „configuration“ „dataToExtract“ fest, um zu steuern, welche Teile der Blobs indiziert werden:

   • „contentAndMetadata“ gibt an, dass alle aus dem Blob extrahierten Metadaten und Textinhalte indiziert werden. Dies ist der Standardwert.

   • „storageMetadata“ gibt an, dass nur die standardmäßigen Blobeigenschaften und benutzerspezifischen Metadaten indiziert werden.

   • „allMetadata“ gibt an, dass standardmäßige Blobeigenschaften und alle Metadaten für gefundene Inhaltstypen aus dem Blobinhalt extrahiert und indiziert werden.

5. Legen Sie unter „configuration“ „parsingMode“ fest, wenn Blobs mehreren Suchdokumenten zugeordnet werden sollen, oder wenn sie aus Nur-Text, JSON-Dokumenten oder CSV-Dateien bestehen.

6. Geben Sie Feldzuordnungen an, wenn es Unterschiede beim Feldnamen oder -typ gibt, oder wenn Sie mehrere Versionen eines Quellfelds im Suchindex benötigen.

   Bei der Blobindizierung können Sie häufig Feldzuordnungen weglassen, da der Indexer über integrierte Unterstützung für die Zuordnung der „content“- und Metadateneigenschaften zu ähnlich benannten und typisierten Feldern in einem Index verfügt. Bei Metadateneigenschaften ersetzt der Indexer im Suchindex automatisch Bindestriche - durch Unterstriche.

7. Weitere Informationen zu anderen Eigenschaften finden Sie unter Erstellen von Indexern in Azure Cognitive Search. Die vollständige Liste der Parameterbeschreibungen finden Sie in der REST-API unter Erstellen eines Indexers (REST).

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=2024-07-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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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.

Umgang mit Fehlern

Zu häufigen Fehlern bei der Indizierung gehören nicht unterstützte Inhaltstypen, fehlende Inhalte oder übergroße Blobs.

Der Blobindexer wird standardmäßig beendet, sobald ein Blob mit einem nicht unterstützten Inhaltstyp (z. B. einer Audiodatei) gefunden wird. Sie können mit dem Parameter „excludedFileNameExtensions“ bestimmte Inhaltstypen überspringen. Möglicherweise möchten Sie jedoch, dass die Indizierung auch dann fortgesetzt wird, wenn Fehler auftreten, und dann später einzelne Dokumente debuggen. Weitere Informationen zu Indexerfehlern finden Sie unter Beheben von häufigen Problemen bei Suchindexern in Azure Cognitive Search und Beheben von häufigen Fehlern und Warnungen bei Suchindexern in Azure Cognitive Search.

Es gibt fünf Indexereigenschaften, die die Reaktion des Indexers beim Auftreten von Fehlern steuern.

PUT /indexers/[indexer name]?api-version=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Begrenzungen

1. Im Gegensatz zu BLOB-Indexern können ADLS Gen2-Indexer keine SAS-Token auf Containerebene zum Aufzählen und Indizieren von Inhalten aus einem Speicherkonto verwenden. Dies liegt daran, dass der Indexer eine Überprüfung vorgibt, um zu ermitteln, ob das Speicherkonto hierarchische Namespaces aktiviert hat, indem die Filesystem - Get properties API aufgerufen wird. Für Speicherkonten, bei denen hierarchische Namespaces nicht aktiviert sind, empfiehlt es sich stattdessen, BLOB-Indexer zu verwenden, um eine leistungsfähige Enumeration von Blobs sicherzustellen.

2. Wenn die Eigenschaft metadata_storage_path dem Indexschlüsselfeld zugeordnet ist, werden Blobs nicht garantiert, wenn sie bei einer Verzeichnisumbenennung neu indiziert werden. Wenn Sie die Blobs neu indizieren möchten, die Teil der umbenannten Verzeichnisse sind, aktualisieren Sie die LastModified-Zeitstempel für alle.

Nächste Schritte

Sie können nun 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:

• Erkennung von Änderungen und Löschungen bei der Blobindizierung (Azure Cognitive Search)
• Indexierung großer Datensätze
• C# Beispiel: Index Data Lake Gen2 mit Microsoft Entra ID