Feldzuordnungen und Transformationen mithilfe von Azure KI Search-Indexern

  • Artikel

Indexer Stages

Wenn ein Azure KI-Suche-Indexer einen Suchindex lädt, bestimmt er den Datenpfad durch die Zuordnung von Quell-zu-Zielfeldern. Implizite Feldzuordnungen sind intern und erfolgen, wenn Feldnamen und Datentypen zwischen Quelle und Ziel 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 können auch für einfache Datenkonvertierungen, wie z. B. Codierung oder Dekodierung, durch Zuordnungsfunktionen verwendet werden. Wenn weitere Verarbeitungsvorgänge erforderlich sind, ziehen Sie die Verwendung von Azure Data Factory in Betracht, um die Lücke zu überbrücken.

Feldzuordnungen gelten für:

  • Physische Datenstrukturen auf beiden Seiten des Datenstroms (zwischen Feldern in einer unterstützten Datenquelle und Feldern in einem Suchindex). Wenn Sie mit Fähigkeiten angereicherte Inhalte importieren, die sich im Speicher befinden, verwenden Sie outputFieldMappings, um speicherinterne Knoten den Ausgabefeldern in einem Suchindex zuzuordnen.

  • Nur Suchindizes. Wenn Sie einen Wissensspeicher auffüllen, verwenden Sie Projektionen für die Datenpfadkonfiguration.

  • Nur Suchfelder der obersten Ebene, wobei targetFieldName entweder ein einfaches Feld oder eine Sammlung ist. Ein Zielfeld kann kein komplexer Typ sein.

Hinweis

Wenn Sie mit komplexen Daten (geschachtelten oder hierarchischen Strukturen) arbeiten und diese Datenstruktur in Ihrem Suchindex spiegeln möchten, muss ihr Suchindex genau mit der Quellstruktur übereinstimmen (gleiche Feldnamen, Ebenen und Typen), damit die Standardzuordnungen funktionieren. Optional benötigen Sie möglicherweise nur wenige Knoten in der komplexen Struktur. Um einzelne Knoten abzurufen, können Sie eingehende Daten zu einer Zeichenfolgensammlung vereinfachen (siehe outputFieldMappings für diese Problemumgehung).

Unterstützte Szenarios

Anwendungsfall Beschreibung
Namensabweichung Angenommen, Ihre Datenquelle verfügt über ein Feld mit dem Namen _city. Da Azure KI Search keine Feldnamen zulässt, die mit einem Unterstrich beginnen, können Sie mit einer Feldzuordnung die Felder „_Ort“ und „Ort“ effektiv einander zuordnen.

Wenn Ihre Indizierungsanforderungen das Abrufen von Inhalten aus mehreren Datenquellen umfassen, wobei Feldnamen zwischen den Quellen variieren, können Sie eine Feldzuordnung verwenden, um den Pfad zu klären.
Typabweichung Angenommen, Sie möchten, dass ein ganzzahliges Quellfeld den Typ Edm.String aufweist, damit es im Suchindex durchsuchbar ist. Da sich die Typen unterscheiden, müssen Sie eine Feldzuordnung definieren, damit der Datenpfad erfolgreich verläuft. Beachten Sie, dass die unterstützten Datentypen von Azure KI Search weniger umfangreich als bei vielen Datenquellen sind. 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 Quellfeld auffüllen. Sie möchten beispielsweise auf die verschiedenen Felder unterschiedliche Analysemodule anwenden, um unterschiedliche Anwendungsfälle in Ihrer Client-App zu unterstützen.
Codierung und Decodierung Sie können Zuordnungsfunktionen anwenden, um die Base64-Codierung oder -Decodierung von Daten während der Indizierung zu unterstützen.
Teilen von Zeichenfolgen oder Umwandeln von Arrays in Sammlungen Sie können Zuordnungsfunktionen anwenden, um eine Zeichenfolge, die ein Trennzeichen enthält, zu teilen oder um ein JSON-Array an ein Suchfeld vom Typ Collection(Edm.String) zu senden.

Definieren einer Feldzuordnung

Feldzuordnungen werden dem fieldMappings-Array einer Indexer-Definition hinzugefügt. Eine Feldzuordnung besteht aus drei Teilen.

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]
Eigenschaft Beschreibung
sourceFieldName Erforderlich. Repräsentiert ein Feld in Ihrer Datenquelle.
targetFieldName Optional. Repräsentiert ein Feld in Ihrem Suchindex. Wenn dieser Wert weggelassen wird, wird der Wert von sourceFieldName für das Ziel angenommen. Zielfelder müssen einfache Felder oder Sammlungen auf oberster Ebene sein. Es darf sich nicht um einen komplexen Typ oder eine komplexe Sammlung handeln. Beim Behandeln von Problemen mit dem Datentyp wird der Datentyp eines Felds in der Indexdefinition angegeben. Die Feldzuordnung muss nur den Namen des Felds aufweisen.
mappingFunction Optional. Besteht aus vordefinierten Funktionen, die Daten transformieren.

Wenn Sie eine Fehlermeldung ähnlich wie "Field mapping specifies target field 'Address/city' that doesn't exist in the index" erhalten, liegt das daran, dass Zielfeld-Zuordnungen kein komplexer Typ sein können. Die Zwischenlösung besteht darin, ein Indexschema zu erstellen, das in Bezug auf Feldnamen und Datentypen mit dem Rohinhalt identisch ist. Ein Beispiel finden Sie unter im Tutorial: Indizierte geschachtelte JSON-Blobs.

Azure KI Search verwendet einen von Groß- und Kleinschreibung unabhängigen Vergleich zum Auflösen von Feld- und Funktionsnamen in Feldzuordnungen. 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 die 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 die REST-API oder ein Azure SDK verwenden.

Verwenden Sie Create Indexer (REST) oder Update Indexer (REST), eine beliebige API-Version.

In diesem Beispiel wird eine Feldnamenabweichung behandelt.

PUT https://[service name].search.windows.net/indexers/myindexer?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
{
    "dataSourceName" : "mydatasource",
    "targetIndexName" : "myindex",
    "fieldMappings" : [ { "sourceFieldName" : "_city", "targetFieldName" : "city" } ]
}

In diesem Beispiel wird ein einzelnes Quellfeld mehreren Zielfeldern zugeordnet (1:n-Zuordnungen). Sie können ein Feld „gabeln“, d. h. denselben Inhalt eines Quellfelds in zwei verschiedene Indexfelder kopieren, die im Index unterschiedlich analysiert oder zugeordnet werden.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

Zuordnungsfunktionen und Beispiele

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 KI 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 Anwendungsfälle 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 searchable 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 KI 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.

Azure KI Search 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.

Azure KI Search 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.

Base64-Codierungsoptionen

Azure KI 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 KI Search setzen das vollständige .NET Framework voraus, das integrierte Codierung bereitstellt. Die Optionen useHttpServerUtilityUrlTokenEncode und useHttpServerUtilityUrlTokenDecode wenden diese integrierte Funktion an. 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 Zusätzliche Verarbeitung nach Codierung der Bibliothek Zusätzliche 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 über keinen integrierten Datentyp, der Collection(Edm.String)-Feldern in Azure KI Search 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"
   }
 }
]

Funktion toJson

Diese Funktion konvertiert eine Zeichenfolge in ein formatiertes JSON-Objekt. Sie kann für Szenarien verwendet werden, in denen die Datenquelle, z. B. Azure SQL, keine zusammengesetzten oder hierarchischen Datentypen unterstützt, und diese dann komplexen Feldern zuordnen.

Beispiel: Zuordnen von Textinhalten zu einem komplexen Feld

Angenommen, es gibt eine SQL-Zeile mit einem JSON-String, der auf ein (entsprechend definiertes) komplexes Feld im Index abgebildet werden muss, so kann dies mit der Funktion toJson erreicht werden. Wenn zum Beispiel ein komplexes Feld im Index mit den folgenden Daten gefüllt werden muss:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Sie können dies erreichen, indem Sie die Zuordnungsfunktion toJson auf eine Spalte mit einer JSON-Zeichenfolge in einer SQL-Zeile anwenden, die wie folgt aussieht: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

Die Feldzuordnung muss wie unten gezeigt angegeben werden.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

Weitere Informationen