Feldzuordnungen in Azure Search-IndexernField mappings in Azure Search indexers

Bei Verwendung des Azure Search-Indexers gibt es gelegentlich Situationen, in denen die Eingabedaten nicht ganz dem Schema des Zielindexes entsprechen.When using Azure Search indexers, you can occasionally find yourself in situations where your input data doesn't quite match the schema of your target index. In diesen Fällen können Sie Ihre Daten mithilfe von Feldzuordnungen in das gewünschte Format umwandeln.In those cases, you can use field mappings to transform your data into the desired shape.

Feldzuordnungen sind beispielsweise in folgenden Situationen hilfreich:Some situations where field mappings are useful:

  • Ihre Datenquelle verfügt über ein Feld _id, aber Azure Search lässt keine Feldnamen zu, die mit einem Unterstrich beginnen.Your data source has a field _id, but Azure Search doesn't allow field names starting with an underscore. Mit einer Feldzuordnung können Sie das Feld „umbenennen“.A field mapping allows you to "rename" a field.
  • Sie möchten mehrere Felder im Index mit denselben Datenquellendaten auffüllen, da Sie z.B. verschiedene Analysen auf diese Felder anwenden möchten.You want to populate several fields in the index with the same data source data, for example because you want to apply different analyzers to those fields. Mit Feldzuordnungen können Sie ein Datenquellenfeld „verzweigen“.Field mappings let you "fork" a data source field.
  • Sie müssen Ihre Daten mit Base64 codieren oder decodieren.You need to Base64 encode or decode your data. Feldzuordnungen unterstützen mehrere Zuordnungsfunktionen, einschließlich Funktionen für die Base64-Codierung und -Decodierung.Field mappings support several mapping functions, including functions for Base64 encoding and decoding.

Einrichten von FeldzuordnungenSetting up field mappings

Sie können Feldzuordnungen beim Erstellen eines neuen Indexers über die API Indexer erstellen hinzufügen.You can add field mappings when creating a new indexer using the Create Indexer API. Sie können Feldzuordnungen für einen Indexer mithilfe der API Indexer aktualisieren verwalten.You can manage field mappings on an indexing indexer using the Update Indexer API.

Eine Feldzuordnung besteht aus drei Teilen:A field mapping consists of three parts:

  1. Einem sourceFieldName, der ein Feld in der Datenquelle darstellt.A sourceFieldName, which represents a field in your data source. Diese Eigenschaft ist obligatorisch.This property is required.
  2. Einem optionalen targetFieldName, der ein Feld im Suchindex darstellt.An optional targetFieldName, which represents a field in your search index. Wenn dieser nicht angegeben wird, wird derselbe Name wie in der Datenquelle verwendet.If omitted, the same name as in the data source is used.
  3. Einer optionalen mappingFunction, die die Daten mit einer von mehreren vordefinierten Funktionen transformieren kann.An optional mappingFunction, which can transform your data using one of several predefined functions. Die vollständige Liste der Funktionen finden Sie unten.The full list of functions is below.

Feldzuordnungen werden dem fieldMappings -Array in der Indexerdefinition hinzugefügt.Fields mappings are added to the fieldMappings array on the indexer definition.

Beispielsweise können Sie Unterschiede in Feldnamen folgendermaßen ausgleichen:For example, here's how you can accommodate differences in field names:


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" : "_id", "targetFieldName" : "id" } ]
}

Ein Indexer kann mehrere Feldzuordnungen aufweisen.An indexer can have multiple field mappings. Hier sehen Sie beispielsweise, wie Sie ein Feld „verzweigen“ können:For example, here's how you can "fork" a field:


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

Hinweis

Azure Search verwendet einen von Groß- und Kleinschreibung unabhängigen Vergleich zum Auflösen von Feld- und Funktionsnamen in Feldzuordnungen.Azure Search uses case-insensitive comparison to resolve the field and function names in field mappings. Dies ist zwar praktisch, weil Sie die Groß- und Kleinschreibung nicht berücksichtigen müssen, bedeutet aber, dass die Datenquelle oder der Index keine Felder aufweisen dürfen, die sich nur in der Groß- und Kleinschreibung unterscheiden.This is convenient (you don't have to get all the casing right), but it means that your data source or index cannot have fields that differ only by case.

FeldzuordnungsfunktionenField mapping functions

Diese Funktionen werden derzeit unterstützt:These functions are currently supported:

base64Encodebase64Encode

Führt eine URL-sichere Base64-Codierung der Eingabezeichenfolge durch.Performs URL-safe Base64 encoding of the input string. Geht davon aus, dass die Eingabe mit UTF-8 codiert ist.Assumes that the input is UTF-8 encoded.

Beispielanwendungsfall – Suche des DokumentschlüsselsSample use case - document key lookup

Nur URL-sichere Zeichen können in einem Azure Search-Dokumentschlüssel enthalten sein (da Kunden das Dokument z.B. über die Lookup-API aufrufen können müssen).Only URL-safe characters can appear in an Azure Search document key (because customers must be able to address the document using the Lookup API, for example). Wenn Ihre Daten URL-unsichere Zeichen enthalten und Sie damit ein Schlüsselfeld in Ihrem Suchindex auffüllen möchten, verwenden Sie diese Funktion.If your data contains URL-unsafe characters and you want to use it to populate a key field in your search index, use this function. Nach der Codierung des Schlüssels können Sie mit einer Base64-Codierung den ursprünglichen Wert abrufen.Once the key is encoded, you can use base64 decode to retrieve the original value. Einzelheiten finden Sie im Abschnitt Base64-Codierung und -Decodierung.For details, see the base64 encoding and decoding section.

BeispielExample


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

Beispielanwendungsfall – Abrufen des OriginalschlüsselsSample use case - retrieve original key

Sie verfügen über einen Blobindexer, der Blobs mit den Metadaten des Blobpfads als Dokumentschlüssel indiziert.You have a blob indexer that indexes blobs with the blob path metadata as the document key. Nach dem Abrufen des codierten Dokumentschlüssels möchten Sie den Pfad decodieren und das Blob herunterladen.After retrieving the encoded document key, you want to decode the path and download the blob.

BeispielExample


"fieldMappings" : [
  {
    "sourceFieldName" : "SourceKey",
    "targetFieldName" : "IndexKey",
    "mappingFunction" : { "name" : "base64Encode", "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false } }
  }]

Wenn Sie Dokumente nicht mit Schlüsseln suchen müssen und auch den codierten Inhalt nicht decodieren müssen, können Sie einfach parameters für die Zuordnungsfunktion auslassen, mit der useHttpServerUtilityUrlTokenEncode standardmäßig auf true festgelegt wird.If you don't need to look up documents by keys and also don't need to decode the encoded content, you can just leave out parameters for the mapping function, which defaults useHttpServerUtilityUrlTokenEncode to true. Andernfalls finden Sie im Abschnitt mit den Details zu Base64 Informationen zum Festlegen der zu verwendenden Einstellungen.Otherwise, see base64 details section to decide which settings to use.

base64Decodebase64Decode

Führt die Base64-Decodierung der Eingabezeichenfolge durch.Performs Base64 decoding of the input string. Es wird davon ausgegangen, dass es sich bei der Eingabe um eine URL-sichere Base64-codierte Zeichenfolge handelt.The input is assumed to a URL-safe Base64-encoded string.

Beispiel für einen AnwendungsfallSample use case

Benutzerdefinierte Blob-Metadatenwerte müssen ASCII-codiert sein.Blob custom metadata values must be ASCII-encoded. Sie können die Base64-Codierung verwenden, um beliebige UTF-8-Zeichenfolgen in benutzerdefinierten Blobmetadaten darzustellen.You can use Base64 encoding to represent arbitrary UTF-8 strings in blob custom metadata. Um die Suche aussagekräftig zu gestalten, können Sie mit dieser Funktion die codierten Daten beim Auffüllen des Suchindexes wieder in „normale“ Zeichenfolgen umwandeln.However, to make search meaningful, you can use this function to turn the encoded data back into "regular" strings when populating your search index.

BeispielExample


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

Wenn Sie keine parameters angeben, ist true der Standardwert von useHttpServerUtilityUrlTokenDecode.If you don't specify any parameters, then the default value of useHttpServerUtilityUrlTokenDecode is true. Informationen zum Festlegen der zu verwendenden Einstellungen finden Sie im Abschnitt mit den Details zu Base64.See base64 details section to decide which settings to use.

Details zur Base64-Codierung und -DecodierungDetails of base64 encoding and decoding

Azure Search unterstützt zwei base64-Codierungen: das HttpServerUtility-URL-Token und die URL-sichere Base64-Codierung ohne Auffüllung.Azure Search supports two base64 encodings: HttpServerUtility URL token and URL-safe base64 encoding without padding. Sie müssen die gleiche Codierung wie die Zuordnungsfunktionen verwenden, wenn Sie einen Dokumentschlüssel für die Suche codieren, einen Wert für die Decodierung durch den Indexer codieren oder ein durch den Indexer codiertes Feld decodieren möchten.You need to use the same encoding as the mapping functions if you want to encode a document key for look up, encode a value to be decoded by the indexer, or decode a field encoded by the indexer.

Wenn der Parameter useHttpServerUtilityUrlTokenEncode zum Codieren bzw. useHttpServerUtilityUrlTokenDecode zum Decodieren auf true eingestellt ist, verhält sich base64Encode wie HttpServerUtility.UrlTokenEncode und base64Decode wie HttpServerUtility.UrlTokenDecode.If useHttpServerUtilityUrlTokenEncode or useHttpServerUtilityUrlTokenDecode parameters for encoding and decoding respectively are set to true, then base64Encode behaves like HttpServerUtility.UrlTokenEncode and base64Decode behaves like HttpServerUtility.UrlTokenDecode.

Wenn Sie nicht das vollständige .NET Framework verwenden (d. h., Sie verwenden .NET Core oder eine andere Programmierumgebung), um die Schlüsselwerte zum Emulieren des Azure Search-Verhaltens zu erzeugen, sollten Sie useHttpServerUtilityUrlTokenEncode und useHttpServerUtilityUrlTokenDecode auf false festlegen.If you are not using the full .NET Framework (i.e., you are using .NET Core or other programming environment) to produce the key values to emulate Azure Search behavior, then you should set useHttpServerUtilityUrlTokenEncode and useHttpServerUtilityUrlTokenDecode to false. Je nach verwendeter Bibliothek können sich die Hilfsfunktionen der Base64-Codierung und -Decodierung von Azure Search unterscheiden.Depending on the library you use, the base64 encode and decode utility functions may be different from Azure Search.

In der folgenden Tabelle werden verschiedene Base64-Codierungen der Zeichenfolge 00>00?00 verglichen.The following table compares different base64 encodings of the string 00>00?00. Um die erforderliche weitere Verarbeitung (sofern vorhanden) für die Base64-Funktionen zu ermitteln, wenden Sie die Codierfunktion der Bibliothek auf die Zeichenfolge 00>00?00 an und vergleichen die Ausgabe mit der erwarteten Ausgabe MDA-MDA_MDA.To determine the required additional processing (if any) for your base64 functions, apply your library encode function on the string 00>00?00 and compare the output with the expected output MDA-MDA_MDA.

CodierenEncoding Base64-codierte AusgabeBase64 encode output Weitere Verarbeitung nach Codierung der BibliothekAdditional processing after library encoding Weitere Verarbeitung vor Decodierung der BibliothekAdditional processing before library decoding
Base64 mit AuffüllungBase64 with padding MDA+MDA/MDA= Verwenden URL-sicherer Zeichen und Entfernen der AuffüllungUse URL-safe characters and remove padding Verwenden von Base64-Standardzeichen und Hinzufügen der AuffüllungUse standard base64 characters and add padding
Base64-Codierung ohne AuffüllungBase64 without padding MDA+MDA/MDA Verwenden URL-sicherer ZeichenUse URL-safe characters Verwenden von Base64-StandardzeichenUse standard base64 characters
URL-sichere Base64-Codierung mit AuffüllungURL-safe base64 with padding MDA-MDA_MDA= Entfernen der AuffüllungRemove padding Hinzufügen der AuffüllungAdd padding
URL-sichere Base64-Codierung ohne AuffüllungURL-safe base64 without padding MDA-MDA_MDA KeineNone KeineNone

extractTokenAtPositionextractTokenAtPosition

Teilt ein Zeichenfolgenfeld mithilfe des angegebenen Trennzeichens und wählt das Token an der angegebenen Position in der resultierenden Teilung aus.Splits a string field using the specified delimiter, and picks the token at the specified position in the resulting split.

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.For example, if the input is Jane Doe, the delimiter is " "(space) and the position is 0, the result is Jane; if the position is 1, the result is Doe. Wenn die Position auf ein Token verweist, das nicht vorhanden ist, wird ein Fehler zurückgegeben.If the position refers to a token that doesn't exist, an error is returned.

Beispiel für einen AnwendungsfallSample use case

Die Datenquelle enthält ein Feld PersonName, und Sie möchten es als zwei separate Felder FirstName und LastName indizieren.Your data source contains a PersonName field, and you want to index it as two separate FirstName and LastName fields. Mit dieser Funktion können Sie die Eingabe mit dem Leerzeichen als Trennzeichen unterteilen.You can use this function to split the input using the space character as the delimiter.

ParameterParameters

  • delimiter: eine Zeichenfolge, die beim Teilen der Eingabezeichenfolge als Trennzeichen verwendet werden soll.delimiter: a string to use as the separator when splitting the input string.
  • position: eine ganzzahlige nullbasierte Position des Tokens, das nach der Teilung der Eingabezeichenfolge ausgewählt werden soll.position: an integer zero-based position of the token to pick after the input string is split.

BeispielExample


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

jsonArrayToStringCollectionjsonArrayToStringCollection

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.Transforms a string formatted as a JSON array of strings into a string array that can be used to populate a Collection(Edm.String) field in the index.

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.For example, if the input string is ["red", "white", "blue"], then the target field of type Collection(Edm.String) will be populated with the three values red, white, and blue. Für Eingabewerte, die nicht als JSON-Zeichenfolgenarrays analysiert werden können, wird ein Fehler zurückgegeben.For input values that cannot be parsed as JSON string arrays, an error is returned.

Beispiel für einen AnwendungsfallSample use case

Die Azure SQL-Datenbank verfügt über keinen integrierten Datentyp, der Collection(Edm.String) -Feldern in Azure Search natürlich zugeordnet werden kann.Azure SQL database doesn't have a built-in data type that naturally maps to Collection(Edm.String) fields in Azure Search. Um Zeichenfolgen-Sammlungsfelder aufzufüllen, formatieren Sie Ihre Quelldaten als JSON-Zeichenfolgenarray, und verwenden Sie diese Funktion.To populate string collection fields, format your source data as a JSON string array and use this function.

BeispielExample


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

Helfen Sie uns bei der Verbesserung von Azure SearchHelp us make Azure Search better

Teilen Sie uns auf unserer UserVoice-Websitemit, wenn Sie sich Features wünschen oder Verbesserungsvorschläge haben.If you have feature requests or ideas for improvements, please reach out to us on our UserVoice site.