Feldzuordnungen und Transformationen mithilfe von Indexern der kognitiven Azure-Suche

Indexer Stages

Wenn Sie zum Pushen von Inhalten in einen Suchindex einen Azure Cognitive Search-Indexer verwenden, weist dieser die Zuordnungen zwischen Quell- und Zielfeldern automatisch zu. Implizite Feldzuordnungen erfolgen dann, wenn Feldnamen und Datentypen kompatibel sind. Wenn die Ein- und Ausgaben nicht übereinstimmen, können Sie explizite Feldzuordnungen definieren, um den Datenpfad einzurichten, wie in diesem Artikel beschrieben.

Feldzuordnungen bieten auch eine einfache Datenkonvertierung über Zuordnungsfunktionen. Wenn weitere Verarbeitungsvorgänge erforderlich sind, ziehen Sie die Verwendung von Azure Data Factory in Betracht, um die Lücke zu überbrücken.

Szenarien und Einschränkungen

Feldzuordnungen ermöglichen die folgenden Szenarien:

  • Umbenennen von Feldern oder Behandeln von Diskrepanzen bei Namen: Angenommen, Ihre Datenquelle verfügt über ein Feld mit dem Namen _id. Da Azure Cognitive Search keine Feldnamen zulässt, die mit einem Unterstrich beginnen, können Sie mit einer Feldzuordnung ein Feld effektiv umbenennen.

  • Diskrepanzen bei Datentypen: Die unterstützten Datentypen von Cognitive Search sind weniger umfangreich als bei vielen Datenquellen. Wenn Sie SQL-Daten importieren, ermöglicht ihnen eine Feldzuordnung die Zuordnung des gewünschten SQL-Datentyps in einem Suchindex.

  • 1:n-Datenpfade: Sie können mehrere Felder im Index mit Inhalten aus ein und demselben Feld auffüllen. Beispielsweise möchten Sie verschiedene Analyser auf jedes Feld anwenden.

  • Mehrere Datenquellen mit unterschiedlichen Feldnamen, und Sie möchten ein Suchfeld mit Dokumenten aus mehr als einer Datenquelle auffüllen: Wenn die Feldnamen zwischen den Datenquellen variieren, können Sie eine Feldzuordnung verwenden, um den Pfad zu klären.

  • Base64-Codierung oder -Decodierung von Daten. Feldzuordnungen unterstützen mehrere Zuordnungsfunktionen, einschließlich Funktionen für die Base64-Codierung und -Decodierung.

  • Aufteilen von Zeichenfolgen oder Umwandeln eines JSON-Arrays in eine Zeichenfolgensammlung. Feldzuordnungsfunktionen stellen diese Funktionalität bereit.

Einschränkungen

Bevor Sie mit dem Zuordnen von Feldern beginnen, stellen Sie sicher, dass die folgenden Einschränkungen kein Problem darstellen:

  • Der „targetFieldName“ muss auf einen einzelnen Feldnamen festgelegt werden: entweder ein einfaches Feld oder eine Auflistung. Sie können derzeit keinen Feldpfad zu einem Teilfeld in einem komplexen Feld (z. B. address/city) definieren. Eine Möglichkeit, dieses Problem zu umgehen, ist das Hinzufügen eines Skillsets und das Verwenden eines Shaper-Skills.

  • Feldzuordnungen funktionieren nur für Suchindizes. Bei Indexern, die auch Wissensspeicher erstellen, werden Feldzuordnungen durch Datenformen und Projektionen bestimmt, und alle Feldzuordnungen und Ausgabefeldzuordnungen im Indexer werden ignoriert.

Einrichten von Feldzuordnungen

Feldzuordnungen werden dem fieldMappings-Array der Indexerdefinition hinzugefügt. Eine Feldzuordnung besteht aus drei Teilen.

Eigenschaft BESCHREIBUNG
sourceFieldName Erforderlich. Repräsentiert ein Feld in Ihrer Datenquelle.
targetFieldName Optional. Repräsentiert ein Feld in Ihrem Suchindex. Wird kein Wert angegeben, wird der Wert von „sourceFieldName“ für das Ziel angenommen.
mappingFunction Optional. Besteht aus vordefinierten Funktionen, die Daten transformieren. Sie können Funktionen sowohl auf Quell- als auch auf Zielfeldzuordnungen anwenden.

Bei der kognitiven Azure-Suche wird ein von Groß- und Kleinschreibung unabhängiger Vergleich zum Auflösen von Feld- und Funktionsnamen in Feldzuordnungen verwendet. Dies ist zwar praktisch, weil Sie die Groß- und Kleinschreibung nicht berücksichtigen müssen, bedeutet aber, dass weder Datenquelle noch Index Felder enthalten dürfen, die sich nur in der Groß- und Kleinschreibung unterscheiden.

Hinweis

Wenn keine Feldzuordnungen vorhanden sind, nehmen Indexer an, dass die Datenquellenfelder den Indexfeldern mit demselben Namen zugeordnet werden sollen. Das Hinzufügen einer Feldzuordnung setzt diese Standardfeldzuordnungen für das Quell- und Zielfeld außer Kraft. Manche Indexer wie etwa der Blobspeicherindexer fügen Standardfeldzuordnungen für das Indexschlüsselfeld hinzu.

Zum Definieren von Feldzuordnungen können Sie das Portal, die REST-API oder ein Azure SDK verwenden.

Wenn Sie den Assistenten zum Importieren von Daten verwenden, werden Feldzuordnungen nicht unterstützt, da der Assistent Zielsuchfelder erstellt, die die Quellfelder spiegeln.

Im Portal können Sie Feldzuordnungen in einem Indexer festlegen, nachdem der Indexer bereits vorhanden ist:

  1. Öffnen Sie die JSON-Definition eines vorhandenen Indexers.

  2. Fügen Sie im Abschnitt „fieldMappings“ die Quell- und Zielfelder hinzu. Zielfelder müssen im Suchindex vorhanden sein und den Feldnamenskonventionen entsprechen. Weitere Details zur JSON-Syntax finden Sie auf der Registerkarte „REST-API“.

  3. Speichern Sie die Änderungen.

  4. Wenn das Suchfeld leer ist, führen Sie den Indexer aus, um Daten aus dem Quellfeld in das neu zugeordnete Suchfeld zu importieren. Wenn das Suchfeld zuvor aufgefüllt wurde, setzen Sie den Indexer vor der Ausführung zurück, um den Inhalt zu verwerfen und neuen hinzuzufügen.

Funktionen und Beispiele für Feldzuordnungen

Eine Feldzuordnungsfunktion transformiert den Inhalt eines Felds, bevor es im Index gespeichert wird. Die folgenden Zuordnungsfunktionen werden derzeit unterstützt:

Funktion „base64Encode“

Führt eine URL-sichere Base64-Codierung der Eingabezeichenfolge durch. Geht davon aus, dass die Eingabe mit UTF-8 codiert ist.

Beispiel: Basiscodierung eines Dokumentschlüssels

Nur URL-sichere Zeichen können in einem Azure Cognitive Search-Dokumentschlüssel enthalten sein (sodass Sie das Dokument über die Lookup-API aufrufen können). Wenn das Quellfeld für den Schlüssel URL-unsichere Zeichen wie - und \ enthält, können Sie die Funktion base64Encode verwenden, um die Zeichenfolge bei der Indizierung zu konvertieren.

Im folgenden Beispiel wird die base64Encode-Funktion für "metadata_storage_name" angegeben, um nicht unterstützte Zeichen zu verarbeiten.

PUT /indexers?api-version=2020-06-30
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Ein Dokumentschlüssel darf (vor und nach der Konvertierung) nicht länger als 1.024 Zeichen sein. Wenn Sie den codierten Schlüssel während der Suche abrufen, können Sie die Funktion base64Decode verwenden, um den ursprünglichen Schlüsselwert abzurufen, und mit diesem das Quelldokument abrufen.

Beispiel: Konfigurieren, dass ein basiscodiertes Feld durchsuchbar ist

Manchmal müssen Sie eine codierte Version eines Felds wie "metadata_storage_path" als Schlüssel verwenden, aber Sie benötigen auch eine nicht codierte Version für die Volltextsuche. Um beide Szenarios zu unterstützen, können Sie "metadata_storage_path" zwei Feldern zuordnen: einem für den Schlüssel (verschlüsselt) und einem zweiten für ein Pfadfeld, von dem wir annehmen können, dass es im Indexschema als „durchsuchbar“ gekennzeichnet ist.

PUT /indexers/blob-indexer?api-version=2020-06-30
{
    "dataSourceName" : " blob-datasource ",
    "targetIndexName" : "my-target-index",
    "schedule" : { "interval" : "PT2H" },
    "fieldMappings" : [
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "key", "mappingFunction" : { "name" : "base64Encode" } },
        { "sourceFieldName" : "metadata_storage_path", "targetFieldName" : "path" }
      ]
}

Beispiel: Beibehalten von Ursprungswerten

Der Blobspeicherindexer fügt dem Indexschlüsselfeld automatisch eine Feldzuordnung aus metadata_storage_path hinzu, den URI des Blobs, wenn keine Feldzuordnung angegeben ist. Dieser Wert ist Base64-codiert. Er kann also sicher als Dokumentschlüssel für Azure Cognitive Search verwendet werden. Im folgenden Beispiel sehen Sie, wie Sie gleichzeitig eine Base64-codierte Version mit sicherer URL von metadata_storage_path einem index_key-Feld zuordnen und den Ursprungswert in einem metadata_storage_path-Feld beibehalten:

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Wenn Sie keine parameters-Eigenschaft für Ihre Zuordnungsfunktion angeben, wird standardmäßig der Wert {"useHttpServerUtilityUrlTokenEncode" : true} verwendet.

Die kognitive Azure-Suche unterstützt zwei verschiedene Base64-Codierungen. Verwenden Sie beim Codieren und Decodieren eines bestimmten Felds dieselben Parameter. Weitere Informationen, anhand der Sie entscheiden können, welche Parameter verwendet werden sollen, finden Sie unter Base64-Codierungsoptionen.

Funktion „base64Decode“

Führt die Base64-Decodierung der Eingabezeichenfolge durch. Es wird davon ausgegangen, dass es sich bei der Eingabe um eine URL-sichere Base64-codierte Zeichenfolge handelt.

Beispiel: Decodieren von Blobmetadaten oder URLs

Ihre Quelldaten enthalten möglicherweise Base64-codierte Zeichenfolgen wie Blobmetadaten-Zeichenfolgen oder Web-URLs, die Sie konvertieren möchten, damit sie als Nur-Text durchsuchbar sind. Mit der Funktion base64Decode können Sie die codierten Daten beim Auffüllen des Suchindex wieder in „normale“ Zeichenfolgen umwandeln.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }]

Wenn Sie keine parameters-Eigenschaft angeben, wird standardmäßig der Wert {"useHttpServerUtilityUrlTokenEncode" : true} verwendet.

Die kognitive Azure-Suche unterstützt zwei verschiedene Base64-Codierungen. Verwenden Sie beim Codieren und Decodieren eines bestimmten Felds dieselben Parameter. Ausführlichere Informationen, anhand der Sie entscheiden können, welche Parameter verwendet werden sollen, finden Sie unter Base64-Codierungsoptionen.

Base64-Codierungsoptionen

Azure Cognitive Search unterstützt die URL-sichere Base64-Codierung sowie normale Base64-Codierung. Eine während der Indizierung base64-codierte Zeichenfolge muss später mit denselben Codierungsoptionen decodiert werden. Andernfalls stimmt das Ergebnis nicht mit dem ursprünglichen Wert überein.

Wenn der Parameter useHttpServerUtilityUrlTokenEncode zum Codieren bzw. useHttpServerUtilityUrlTokenDecode zum Decodieren auf true festgelegt ist, verhält sich base64Encode wie HttpServerUtility.UrlTokenEncode und base64Decode wie HttpServerUtility.UrlTokenDecode.

Warnung

Wenn base64Encode verwendet wird, um Schlüsselwerte zu erzeugen, muss useHttpServerUtilityUrlTokenEncode auf „true“ festgelegt werden. Für Schlüsselwerte kann nur die URL-sichere Base64-Codierung verwendet werden. Weitere Informationen zum vollständigen Satz der Einschränkungen für Zeichen in Schlüsselwerten finden Sie unter Benennungsregeln.

Die .NET-Bibliotheken in Azure Cognitive Search setzen das vollständige .NET Framework voraus, das integrierte Codierung bereitstellt. Die Optionen useHttpServerUtilityUrlTokenEncode und useHttpServerUtilityUrlTokenDecode nutzen diese integrierte Funktion. Wenn Sie .NET Core oder ein anderes Framework verwenden, empfiehlt es sich, diese Optionen auf false festzulegen und die Codierungs- und Decodierungsfunktionen Ihres Frameworks direkt aufzurufen.

In der folgenden Tabelle werden verschiedene Base64-Codierungen der Zeichenfolge 00>00?00 verglichen. Um die erforderliche Verarbeitung (sofern zutreffend) für die Base64-Funktionen zu ermitteln, wenden Sie die Codierungsfunktion der Bibliothek auf die Zeichenfolge 00>00?00 an und vergleichen die Ausgabe mit der erwarteten Ausgabe MDA-MDA_MDA.

Codieren Base64-codierte Ausgabe Weitere Verarbeitung nach Codierung der Bibliothek Weitere Verarbeitung vor Decodierung der Bibliothek
Base64 mit Auffüllung MDA+MDA/MDA= Verwenden URL-sicherer Zeichen und Entfernen der Auffüllung Verwenden von Base64-Standardzeichen und Hinzufügen der Auffüllung
Base64-Codierung ohne Auffüllung MDA+MDA/MDA Verwenden URL-sicherer Zeichen Verwenden von Base64-Standardzeichen
URL-sichere Base64-Codierung mit Auffüllung MDA-MDA_MDA= Entfernen der Auffüllung Hinzufügen der Auffüllung
URL-sichere Base64-Codierung ohne Auffüllung MDA-MDA_MDA Keine Keine

Funktion „extractTokenAtPosition“

Teilt ein Zeichenfolgenfeld mithilfe des angegebenen Trennzeichens und wählt das Token an der angegebenen Position in der resultierenden Teilung aus.

Diese Funktion verwendet die folgenden Parameter:

  • delimiter: eine Zeichenfolge, die beim Teilen der Eingabezeichenfolge als Trennzeichen verwendet werden soll.
  • position: eine ganzzahlige nullbasierte Position des Tokens, das nach der Teilung der Eingabezeichenfolge ausgewählt werden soll.

Wenn die Eingabe beispielsweise Jane Doe lautet, " " (Leerzeichen) als Trennzeichen (delimiter) dient und die position 0 ist, ist das Ergebnis Jane. Ist die position 1, ist das Ergebnis Doe. Wenn die Position auf ein Token verweist, das nicht vorhanden ist, wird ein Fehler zurückgegeben.

Beispiel: Extrahieren eines Namens

Die Datenquelle enthält ein Feld PersonName, und Sie möchten es als zwei separate Felder FirstName und LastName indizieren. Mit dieser Funktion können Sie die Eingabe mit dem Leerzeichen als Trennzeichen unterteilen.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

Funktion „jsonArrayToStringCollection“

Wandelt eine Zeichenfolge, die als JSON-Zeichenfolgenarray formatiert ist, in ein Zeichenfolgenarray um, das zum Auffüllen eines Felds Collection(Edm.String) im Index verwendet werden kann.

Wenn die Eingabezeichenfolge beispielsweise ["red", "white", "blue"] lautet, wird das Zielfeld vom Typ Collection(Edm.String) mit drei Werten gefüllt: red, white und blue. Bei Eingabewerten, die nicht als JSON-Zeichenfolgenarrays analysiert werden können, wird ein Fehler zurückgegeben.

Beispiel: Auffüllen der Sammlung aus relationalen Daten

Azure SQL-Datenbank verfügt nicht über einen integrierten Datentyp, der Collection(Edm.String)-Feldern in der kognitiven Azure-Suche natürlich zugeordnet werden kann. Um Zeichenfolgen-Sammlungsfelder aufzufüllen, können Sie Ihre Quelldaten als JSON-Zeichenfolgenarray vorverarbeiten und dann die Zuordnungsfunktion jsonArrayToStringCollection verwenden.

"fieldMappings" : [
  {
    "sourceFieldName" : "tags", 
    "mappingFunction" : { "name" : "jsonArrayToStringCollection" }
  }]

urlEncode-Funktion

Diese Funktion kann verwendet werden, um eine Zeichenfolge zu codieren, sodass Sie „URL-sicher“ ist. Bei Verwendung mit einer Zeichenfolge, die in einer URL nicht zulässige Zeichen enthält, konvertiert diese Funktion diese „unsicheren“ Zeichen in Entsprechungen von Zeichenentitäten. Diese Funktion verwendet das UTF-8-Codierungsformat.

Beispiel: Dokumentschlüsselsuche

Die urlEncode-Funktion kann als Alternative zur base64Encode-Funktion verwendet werden, wenn nur URL-unsichere Zeichen konvertiert werden sollen, während andere Zeichen unverändert bleiben sollen.

Wenn die Eingabezeichenfolge beispielsweise <hello> lautet, wird das Zielfeld des Typs (Edm.String) mit dem Wert %3chello%3e aufgefüllt.

Wenn Sie den codierten Schlüssel während der Suche abrufen, können Sie die Funktion urlDecode verwenden, um den ursprünglichen Schlüsselwert abzurufen, mit dem Sie dann das Quelldokument abrufen können.

"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : {
      "name" : "urlEncode"
    }
  }]

urlDecode-Funktion

Diese Funktion konvertiert eine URL-codierte Zeichenfolge unter Verwendung des UTF-8-Codierungsformats in eine decodierte Zeichenfolge.

Beispiel: Decodieren von Blobmetadaten

Einige Azure Storage-Clients codieren Blobmetadaten automatisch als URL, wenn Sie Nicht-ASCII-Zeichen enthalten. Wenn Sie jedoch das Durchsuchen solcher Metadaten (als unformatierter Text) ermöglichen möchten, können Sie die urlDecode-Funktion verwenden, um die codierten Daten beim Auffüllen Ihres Suchindexes wieder in „normale“ Zeichenfolgen umzuwandeln.

"fieldMappings" : [
 {
   "sourceFieldName" : "UrlEncodedMetadata",
   "targetFieldName" : "SearchableMetadata",
   "mappingFunction" : {
     "name" : "urlDecode"
   }
 }]

Funktion „fixedLengthEncode“

Diese Funktion konvertiert eine Zeichenfolge mit beliebiger Länge in eine Zeichenfolge mit fester Länge.

Beispiel: Zuordnen von zu langen Dokumentschlüsseln

Wenn die Dokumentschlüssellänge 1024 Zeichen überschreitet und dadurch Fehler auftreten, kann diese Funktion angewendet werden, um den Dokumentschlüssel zu kürzen.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }]

Weitere Informationen