Azure コグニティブ検索インデクサーを使用したフィールドのマッピングと変換Field mappings and transformations using Azure Cognitive Search indexers

Azure コグニティブ検索インデクサーを使用すると、入力データがターゲット インデックスのスキーマと完全に一致しないことがあります。When using Azure Cognitive Search indexers, you sometimes find that the input data doesn't quite match the schema of your target index. そのような場合は、インデックス作成処理中にフィールド マッピングを使用してデータを変形できます。In those cases, you can use field mappings to reshape your data during the indexing process.

フィールド マッピングが役立つシナリオは次のとおりです。Some situations where field mappings are useful:

  • データ ソースに _id というフィールドがあるが、Azure コグニティブ検索でアンダースコアで始まるフィールド名が許可されていない場合。Your data source has a field named _id, but Azure Cognitive Search doesn't allow field names that start with an underscore. フィールド マッピングを使用すると、フィールドの名前を効果的に変更できます。A field mapping lets you effectively rename a field.
  • 同じデータ ソース データからインデックス内のいくつかのフィールドにデータを入力します。You want to populate several fields in the index from the same data source data. たとえば、このようなフィールドにさまざまなアナライザーを適用することができます。For example, you might want to apply different analyzers to those fields.
  • インデックス フィールドに複数のデータ ソースのデータを入力し、データ ソースはそれぞれ異なるフィールド名が使用されています。You want to populate an index field with data from more than one data source, and the data sources each use different field names.
  • Base64 エンコードまたはデータのデコードが必要な場合。You need to Base64 encode or decode your data. フィールド マッピングは、Base64 エンコードおよびデコードの関数など、マッピング関数をいくつかサポートしています。Field mappings support several mapping functions, including functions for Base64 encoding and decoding.

注意

Azure コグニティブ検索インデクサーのフィールド マッピング機能には、データ変換のためのいくつかのオプションを使用して、データ フィールドをインデックス フィールドにマップする簡単な方法が用意されています。The field mapping feature of Azure Cognitive Search indexers provides a simple way to map data fields to index fields, with a few options for data conversion. より複雑なデータでは、インデックス付けが簡単な形式に変形する前処理が必要な場合があります。More complex data might require pre-processing to reshape it into a form that's easy to index.

Microsoft Azure Data Factory は、データをインポートおよび変換するための強力なクラウドベースのソリューションです。Microsoft Azure Data Factory is a powerful cloud-based solution for importing and transforming data. インデックスを付ける前にソース データを変換するコードを書くこともできます。You can also write code to transform source data before indexing. コード例については、「リレーショナル データをモデル化する」と「多層構造ファセットをモデル化する」を参照してください。For code examples, see Model relational data and Model multilevel facets.

フィールド マッピングの設定Set up field mappings

フィールド マッピングは、3 つの部分で構成されます。A field mapping consists of three parts:

  1. sourceFieldName。データ ソース内のフィールドを表します。A sourceFieldName, which represents a field in your data source. このプロパティは必須です。This property is required.
  2. targetFieldName (省略可能)。Search インデックス内のフィールドを表します。An optional targetFieldName, which represents a field in your search index. 省略すると、データ ソースと同じ名前が使用されます。If omitted, the same name as in the data source is used.
  3. mappingFunction (省略可能)。定義済みのいずれかの関数を使用してデータを変換できます。An optional mappingFunction, which can transform your data using one of several predefined functions. 関数の完全な一覧については、以下をご覧ください。The full list of functions is below.

フィールド マッピングは、インデクサー定義の fieldMappings 配列に追加されます。Field mappings are added to the fieldMappings array of the indexer definition.

REST API を使用してフィールドをマップするMap fields using the REST API

フィールド マッピングは、インデクサーの作成 API 要求を使用して新しいインデクサーを作成するときに追加できます。You can add field mappings when creating a new indexer using the Create Indexer API request. インデクサーの更新 API 要求を使用して、既存のインデクサーのフィールド マッピングを管理できます。You can manage the field mappings of an existing indexer using the Update Indexer API request.

たとえば、ソース フィールドを別の名前のターゲット フィールドにマップする方法は次のとおりです。For example, here's how to map a source field to a target field with a different name:


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" } ]
}

ソース フィールドは複数のフィールド マッピングで参照できます。A source field can be referenced in multiple field mappings. 次の例は、同じソース フィールドを 2 つの異なるインデックス フィールドにコピーしてフィールドを "分岐させる" 方法を示しています。The following example shows how to "fork" a field, copying the same source field to two different index fields:


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

注意

Azure コグニティブ検索では、大文字と小文字が区別されない比較を使用して、フィールド マッピングのフィールドと関数名を解決します。Azure Cognitive Search uses case-insensitive comparison to resolve the field and function names in field mappings. これは便利ですが (大文字と小文字を区別する必要がないため)、同時に、データ ソースまたはインデックスが、大文字と小文字のみが異なるフィールドを持つことができないことを意味します。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.

.NET SDK を使用してフィールドをマップするMap fields using the .NET SDK

プロパティ SourceFieldNameTargetFieldName を持つ FieldMapping クラスと、オプションの MappingFunction 参照を使用して、.NET SDK でフィールド マッピングを定義します。You define field mappings in the .NET SDK using the FieldMapping class, which has the properties SourceFieldName and TargetFieldName, and an optional MappingFunction reference.

インデクサーを作成するとき、または後で Indexer.FieldMappings プロパティを直接設定することによって、フィールド マッピングを指定できます。You can specify field mappings when constructing the indexer, or later by directly setting the Indexer.FieldMappings property.

次の C# の例では、インデクサーを作成するときにフィールド マッピングを設定します。The following C# example sets the field mappings when constructing an indexer.

  List<FieldMapping> map = new List<FieldMapping> {
    // removes a leading underscore from a field name
    new FieldMapping("_custId", "custId"),
    // URL-encodes a field for use as the index key
    new FieldMapping("docPath", "docId", FieldMappingFunction.Base64Encode() )
  };

  Indexer sqlIndexer = new Indexer(
    name: "azure-sql-indexer",
    dataSourceName: sqlDataSource.Name,
    targetIndexName: index.Name,
    fieldMappings: map,
    schedule: new IndexingSchedule(TimeSpan.FromDays(1)));

  await searchService.Indexers.CreateOrUpdateAsync(indexer);

フィールド マッピング関数Field mapping functions

フィールド マッピング関数によって、インデックスに格納される前にフィールドのコンテンツが変換されます。A field mapping function transforms the contents of a field before it's stored in the index. 現在、以下のマッピング関数がサポートされています。The following mapping functions are currently supported:

base64Encode 関数base64Encode function

入力文字列の URL の安全な Base64 エンコードを実行します。Performs URL-safe Base64 encoding of the input string. 入力は UTF-8 でエンコードされていることを前提としています。Assumes that the input is UTF-8 encoded.

例 - ドキュメント キーの検索Example - document key lookup

Azure コグニティブ検索ドキュメント キーには、URL で使用できる文字のみを使用できます (Lookup API を使用してドキュメントのアドレスを指定できるようにする必要があるため)。Only URL-safe characters can appear in an Azure Cognitive Search document key (because customers must be able to address the document using the Lookup API ). URL の安全ではない文字がキーのソース フィールドに含まれている場合は、インデックス作成時に base64Encode 関数を使用して変換できます。If the source field for your key contains URL-unsafe characters, you can use the base64Encode function to convert it at indexing time.

検索時にエンコードされたキーを取得すると、base64Decode 関数を使用して元のキー値を取得し、それを使用してソース ドキュメントを取得できます。When you retrieve the encoded key at search time, you can then use the base64Decode function to get the original key value, and use that to retrieve the source document.


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

マッピング関数に parameters プロパティを含めない場合、既定で値 {"useHttpServerUtilityUrlTokenEncode" : true} になります。If you don't include a parameters property for your mapping function, it defaults to the value {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure コグニティブ検索では、2 つの異なる Base64 エンコードがサポートされています。Azure Cognitive Search supports two different Base64 encodings. 同じフィールドをエンコードおよびデコードするときは、同じパラメーターを使用する必要があります。You should use the same parameters when encoding and decoding the same field. 詳細については、base64 エンコード オプションに関するページを参照して使用するパラメーターを決定します。For more information, see base64 encoding options to decide which parameters to use.

base64Decode 関数base64Decode function

入力文字列の Base64 デコードを実行します。Performs Base64 decoding of the input string. 入力値は URL 対応の Base64 でエンコードされた文字列と想定されます。The input is assumed to be a URL-safe Base64-encoded string.

例 - BLOB メタデータまたは URL をデコードするExample - decode blob metadata or URLs

ソース データには、BLOB メタデータ文字列や Web URL など、プレーン テキストとして検索できるようにする Base64 エンコード文字列が含まれている場合があります。Your source data might contain Base64-encoded strings, such as blob metadata strings or web URLs, that you want to make searchable as plain text. 検索インデックスを設定するときに、base64Decode 関数を使用して、エンコードされたデータを通常の文字列に戻すことができます。You can use the base64Decode function to turn the encoded data back into regular strings when populating your search index.


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

parameters プロパティを含めない場合、既定で値 {"useHttpServerUtilityUrlTokenEncode" : true} になります。If you don't include a parameters property, it defaults to the value {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure コグニティブ検索では、2 つの異なる Base64 エンコードがサポートされています。Azure Cognitive Search supports two different Base64 encodings. 同じフィールドをエンコードおよびデコードするときは、同じパラメーターを使用する必要があります。You should use the same parameters when encoding and decoding the same field. 詳細については、「base64 エンコード オプション」を参照して使用するパラメーターを決定します。For more details, see base64 encoding options to decide which parameters to use.

base64 エンコード オプションbase64 encoding options

Azure コグニティブ検索では、2 つの異なる Base64 エンコードがサポートされています。HttpServerUtility URL トークンと、パディングなしの URL 対応 Base64 エンコードです。Azure Cognitive Search supports two different Base64 encodings: HttpServerUtility URL token, and URL-safe Base64 encoding without padding. インデックス作成中に base64 でエンコードされた文字列は、後で同じエンコード オプションでデコードする必要があります。そうしないと、結果が元の文字列と一致しません。A string that is base64-encoded during indexing should later be decoded with the same encoding options, or else the result won't match the original.

それぞれがエンコードとデコードに対応する useHttpServerUtilityUrlTokenEncode パラメーターまたは useHttpServerUtilityUrlTokenDecode パラメーターが true に設定されると、base64EncodeHttpServerUtility.UrlTokenEncode のように、base64DecodeHttpServerUtility.UrlTokenDecode のように動作します。If the 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.

Azure コグニティブ検索の動作をエミュレートするキー値を生成するために、全面的に .NET Framework を使用していない (つまり、.NET Core またはその他のフレームワークを使用している) 場合は、useHttpServerUtilityUrlTokenEncodeuseHttpServerUtilityUrlTokenDecodefalse に設定する必要があります。If you are not using the full .NET Framework (that is, you are using .NET Core or another framework) to produce the key values to emulate Azure Cognitive Search behavior, then you should set useHttpServerUtilityUrlTokenEncode and useHttpServerUtilityUrlTokenDecode to false. 使用するライブラリによっては、base64 のエンコードおよびデコード関数が Azure コグニティブ検索で使用されるものと異なる場合があります。Depending on the library you use, the base64 encoding and decoding functions might differ from the ones used by Azure Cognitive Search.

次の表では、文字列 00>00?00 の異なる base64 エンコードを比較しています。The following table compares different base64 encodings of the string 00>00?00. base64 関数に必要な追加処理 (ある場合) を判断するには、ライブラリ エンコード関数を文字列 00>00?00 に適用し、出力を想定出力 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.

エンコードEncoding base64 エンコード出力Base64 encode output ライブラリ エンコード後の追加処理Additional processing after library encoding ライブラリ デコード前の追加処理Additional processing before library decoding
パディング付きの base64Base64 with padding MDA+MDA/MDA= URL で使用できる文字を使用し、パディングを削除するUse URL-safe characters and remove padding 標準 base64 文字を使用し、パディングを追加するUse standard base64 characters and add padding
パディングなしの base64Base64 without padding MDA+MDA/MDA URL で使用できる文字を使用するUse URL-safe characters 標準 base64 文字を使用するUse standard base64 characters
パディング付きの URL 対応 base64URL-safe base64 with padding MDA-MDA_MDA= パディングを削除するRemove padding パディングを追加するAdd padding
パディングなしの URL 対応 base64URL-safe base64 without padding MDA-MDA_MDA なしNone なしNone

extractTokenAtPosition 関数extractTokenAtPosition function

指定された区切り記号を使用して文字列フィールドを分割し、結果として得られる分割の指定位置でトークンを取得します。Splits a string field using the specified delimiter, and picks the token at the specified position in the resulting split.

この関数は以下のパラメーターを使用します。This function uses the following parameters:

  • delimiter: 入力文字列を分割するときに区切り記号として使用する文字列。delimiter: a string to use as the separator when splitting the input string.
  • position: 入力文字列の分割後に取得するトークンの整数の 0 から始まる位置。position: an integer zero-based position of the token to pick after the input string is split.

たとえば、入力が Jane Doedelimiter" " (空白)、position が 0 の場合、結果は Jane になり、position が 1 の場合、結果は 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. 位置が、存在しないトークンを参照する場合、エラーが返されます。If the position refers to a token that doesn't exist, an error is returned.

例 - 名前を抽出するExample - extract a name

データ ソースに PersonName フィールドが含まれ、それを 2 つの別々の FirstName および LastName フィールドとしてインデックスする必要がある場合、Your data source contains a PersonName field, and you want to index it as two separate FirstName and LastName fields. この関数を使用して、空白文字を区切り記号として使って入力を分割できます。You can use this function to split the input using the space character as the delimiter.


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

jsonArrayToStringCollection 関数jsonArrayToStringCollection function

文字列の JSON 配列として書式設定された文字列を、インデックス内の Collection(Edm.String) フィールドの入力に使用できる文字列配列に変換します。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.

たとえば、入力文字列が ["red", "white", "blue"] の場合、Collection(Edm.String) 型のターゲット フィールドに redwhiteblue の 3 つの値が設定されます。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. JSON 文字列配列として解析できない入力値では、エラーが返されます。For input values that cannot be parsed as JSON string arrays, an error is returned.

例 - リレーショナル データからコレクションを設定するExample - populate collection from relational data

Azure SQL Database には、Azure コグニティブ検索の Collection(Edm.String) のフィールドに自然にマップされる組み込みのデータ型がありません。Azure SQL Database doesn't have a built-in data type that naturally maps to Collection(Edm.String) fields in Azure Cognitive Search. 文字列収集フィールドを設定するには、ソース データを JSON 文字列配列として前処理してから、jsonArrayToStringCollection マッピング関数を使用することができます。To populate string collection fields, you can pre-process your source data as a JSON string array and then use the jsonArrayToStringCollection mapping function.


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

リレーショナル データをインデックス コレクション フィールドに変換する詳細な例については、「リレーショナル データをモデル化する」を参照してください。For a detailed example that transforms relational data into index collection fields, see Model relational data.

urlEncode 関数urlEncode function

この関数を使用すると、"URL セーフ" になるように文字列をエンコードできます。This function can be used to encode a string so that it is "URL safe". URL 内で許可されていない文字を含む文字列と共に使用する場合、この関数では、これらの "安全でない" 文字が等価の文字エンティティに変換されます。When used with a string that contains characters that are not allowed in a URL, this function will convert those "unsafe" characters into character-entity equivalents. この関数では、UTF-8 エンコード形式が使用されます。This function uses the UTF-8 encoding format.

例 - ドキュメント キーの検索Example - document key lookup

urlEncode 関数は、他の文字をそのままにして、URL の安全でない文字だけを変換する場合に、base64Encode 関数の代わりに使用できます。urlEncode function can be used as an alternative to the base64Encode function, if only URL unsafe characters are to be converted, while keeping other characters as-is.

たとえば、入力文字列が <hello> の場合、(Edm.String) 型のターゲット フィールドに値 %3chello%3eが設定されますSay, the input string is <hello> - then the target field of type (Edm.String) will be populated with the value %3chello%3e

検索時にエンコードされたキーを取得すると、urlDecode 関数を使用して元のキー値を取得し、それを使用してソース ドキュメントを取得できます。When you retrieve the encoded key at search time, you can then use the urlDecode function to get the original key value, and use that to retrieve the source document.


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

urlDecode 関数urlDecode function

この関数では、UTF-8 エンコード形式を使用して、URL エンコードされた文字列がデコードされた文字列に変換されます。This function converts a URL-encoded string into a decoded string using UTF-8 encoding format.

例 - BLOB メタデータをデコードするExample - decode blob metadata

一部の Azure ストレージ クライアントでは、ASCII 以外の文字が含まれている場合に、BLOB メタデータが自動的に URL エンコードされます。Some Azure storage clients automatically url encode blob metadata if it contains non-ASCII characters. ただし、このようなメタデータを (プレーンテキストとして) 検索可能にする場合は、urlDecode 関数を使用して、検索インデックスを設定する際に、エンコードされたデータを通常の文字列に戻すことがきます。However, if you want to make such metadata searchable (as plain text), you can use the urlDecode function to turn the encoded data back into regular strings when populating your search index.


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