Indizieren von Daten aus Azure Files

  • Artikel

Wichtig

Azure Files-Indexer befindet sich derzeit in der öffentlichen Vorschau und unterliegt zusätzlichen Nutzungsbedingungen. Verwenden Sie eine Vorschau-REST-API, um die Indexerdatenquelle zu erstellen.

In diesem Artikel erfahren Sie, wie Sie einen Indexer konfigurieren, der Inhalte aus Azure Files importiert und in Azure AI Search durchsuchbar macht. Eingaben für den Indexer sind Ihre Dateien in einer einzelnen Freigabe. 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 um spezifische Informationen zur Indizierung von Dateien in Azure 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 Files, transaktionsoptimierte Ebene.

  • Eine SMB-Dateifreigabe zur Bereitstellung des Quellinhalts. NFS-Freigaben werden nicht unterstützt.

  • Dateien, die Text enthalten. Wenn Sie binäre Daten haben, können Sie die KI-Anreicherung für die Bildanalyse einschließen.

  • Leseberechtigungen für Azure Storage. Eine Verbindungszeichenfolge „Vollzugriff“ enthält einen Schlüssel, der Zugriff auf den Inhalt gewährt.

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

Unterstützte Dokumentformate

Der Azure Files-Indexer kann Text aus den folgenden Dokumentformaten extrahieren:

Indizieren von Azure Files

Standardmäßig werden die meisten Dateien als einzelnes Suchdokument im Index indiziert, einschließlich Dateien mit strukturiertem Inhalt wie JSON oder CSV, die als einzelner Textabschnitt indiziert werden.

Ein Verbunddokument oder eingebettetes Dokument (z. B. ein ZIP-Archiv, ein Word-Dokument mit eingebetteter Outlook-E-Mail mit Anlagen oder eine MSG-Datei mit Anlagen) wird ebenfalls als einzelnes Dokument indiziert. So werden beispielsweise alle Bilder, die aus den Anlagen einer MSG-Datei extrahiert wurden, im Feld „normalized_images“ zurückgegeben. Wenn Sie über Bilder verfügen, sollten Sie eine KI-Anreicherung hinzufügen, um mehr Suchhilfe aus diesen Inhalten zu erhalten.

Der Textinhalt eines Dokuments wird in ein Zeichenfolgefeld mit dem Namen „content“ extrahiert. Sie können auch Standard- sowie benutzerdefinierte Metadaten extrahieren.

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.

Sie können 2020-06-30-preview oder höher für "type": "azurefile" verwenden. Wir empfehlen die neueste Vorschau-API.

  1. Erstellen Sie eine Datenquelle, um deren Definition mithilfe einer Vorschau-API für "type": "azurefile" festzulegen.

    POST /datasources?api-version=2024-05-01-preview
{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

  2. Legen Sie "type" auf "azurefile" 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 die Stammdateifreigabe 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 einer Dateifreigabe 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.

Hinzufügen von Suchfeldern zu einem Index

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

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

    POST /indexes?api-version=2024-07-01
{
  "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_path", "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": true, "filterable": true, "sortable": true }        
  ]
}

  2. Erstellen Sie ein Dokumentschlüsselfeld („key“: true). Metadateneigenschaften sind die besten Kandidaten für Blobinhalte. 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.

    • metadata_storage_path (Standard) vollständiger Pfad zum Objekt oder zur Datei

    • metadata_storage_name kann nur verwendet werden, wenn Namen eindeutig sind

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

  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. Bei der Dateiindizierung sind die Standardmetadateneigenschaften mit den Blobmetadateneigenschaften identisch. Der Azure Files-Indexer erstellt für diese Eigenschaften automatisch interne Feldzuordnungen, die Bindestriche in Eigenschaftennamen in Unterstriche konvertieren. Sie müssen die in der Indexdefinition gewünschten Felder nach wie vor hinzufügen, aber Sie können das Erstellen von Feldzuordnungen in der Datenquelle weglassen.

    • metadata_storage_name (Edm.String): der Dateiname. Für eine Datei mit dem Namen „/my-share/my-folder/subfolder/resume.pdf“ lautet der Wert dieses Felds beispielsweise resume.pdf.
    • metadata_storage_path (Edm.String): der vollständigen URI der Datei, einschließlich Speicherkonto. Beispiel: https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
    • metadata_storage_content_type (Edm.String): Inhaltstyp, der mit dem Code angegeben wird, den Sie zum Hochladen der Datei verwendet haben. Beispiel: application/octet-stream.
    • metadata_storage_last_modified (Edm.DateTimeOffset): Zeitstempel der letzten Änderung der Datei. In Azure AI Search wird dieser Zeitstempel zum Identifizieren geänderter Dateien verwendet, um die erneute Indizierung aller Elemente nach der ersten Indizierung zu vermeiden.
    • metadata_storage_size (Edm.Int64): Dateigröße in Bytes.
    • metadata_storage_content_md5 (Edm.String): MD5-Hash des Dateiinhalts, sofern vorhanden.
    • metadata_storage_sas_token (Edm.String): ein temporäres SAS-Token, das von benutzerdefinierten Skills verwendet werden kann, um Zugriff auf die Datei zu erhalten. Dieses Token sollte nicht zur späteren Verwendung gespeichert werden, da es ablaufen kann.

Konfigurieren und Ausführen des Azure Files-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.

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

    POST /indexers?api-version=2024-07-01
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

  2. Geben Sie im optionalen Abschnitt „configuration“ alle Einschluss- oder Ausschlusskriterien an. Wenn Sie nichts angeben, werden alle Dateien in der Dateifreigabe abgerufen.

    Wenn sowohl der indexedFileNameExtensions- als auch der excludedFileNameExtensions-Parameter vorhanden sind, untersucht Azure AI Search zunächst indexedFileNameExtensions und danach excludedFileNameExtensions. Wenn die gleiche Dateierweiterung in beiden Listen vorhanden ist, wird sie von der Indizierung ausgeschlossen.

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

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

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: