你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure 认知搜索索引器进行字段映射和转换

项目
06/24/2022

使用 Azure 认知搜索索引器将内容推送到搜索索引时，索引器会自动分配源到目标字段映射。当字段名称和数据类型兼容时，会出现隐式字段映射。如果输入和输出不一致，你可以定义显式字段映射来设置数据路径，如本文所述。

字段映射还通过映射函数提供轻量级数据转换。如果需要进行更多处理，请考虑使用 Azure 数据工厂来弥补差距。

场景和限制

字段映射支持以下场景：

重命名字段或处理名称差异。假设数据源包含名为 _id 的字段。鉴于 Azure 认知搜索不允许以下划线开头的字段名称，字段映射让你可以有效地重命名字段。
数据类型差异。与许多数据源相比，认知搜索具有的支持的数据类型更少。如果要导入 SQL 数据，可使用字段映射来映射搜索索引中所需的 SQL 数据类型。
一对多数据路径。可以使用同一字段中的内容填充索引中的多个字段。例如，你可能希望对每个字段应用不同的分析器。
具有不同字段名称的多个数据源，你希望在其中使用多个数据源中的文档填充某个搜索字段。如果数据源之间的字段名称不同，你可以使用字段映射来明确路径。
数据的 Base64 编码或解码。字段映射支持多个映射函数，包括用于 Base64 编码和解码的函数。
拆分字符串或将 JSON 数组重新强制转换为字符串集合。字段映射函数提供这种功能。

限制

在开始映射字段之前，请确保以下限制不会对你造成阻碍：

必须将“targetFieldName”设置为单个字段名称，要么为单个字段，要么为集合。你目前无法定义复杂字段（例如 address/city）中的子字段的字段路径。一种解决方法是添加技能组并使用整形程序技能。
字段映射仅适用于搜索索引。对于还会创建知识存储的索引器，数据形状和投影确定了字段关联，并将忽略索引器中的任何字段映射和输出字段映射。

设置字段映射

字段映射将添加到索引器定义的“fieldMappings”数组。字段映射由 3 部分组成。

属性	说明
"sourceFieldName"	必需。表示数据源中的字段。
"targetFieldName"	可选。表示搜索索引中的字段。如果省略，则“sourceFieldName”的值用于目标。
"mappingFunction"	可选。由用于转换数据的预定义函数组成。可以将函数应用于源和目标字段映射。

Azure 认知搜索使用不区分大小写的比较，来解析字段映射中的字段和函数名称。此操作很方便（大小写无需全都正确），但这表示数据源或索引无法具有仅大小写不同的字段。

注意

如果不存在字段映射，则索引器假设应将数据源字段映射到同名的索引字段。添加字段映射会替代源和目标字段的这些默认字段映射。有些索引器（如 Blob 存储索引器）为索引键字段添加默认字段映射。

可以使用门户、REST API 或 Azure SDK 来定义字段映射。

如果使用的是导入数据向导，则不支持字段映射，因为此向导会创建目标搜索字段，这些字段是原始源字段的镜像。

在门户中，如果索引器已存在，则可在索引器中设置字段映射：

打开现有索引器的 JSON 定义。
在“fieldMappings”部分下，添加源和目标字段。目标字段必须存在于搜索索引中，并且符合字段命名约定。有关更多 JSON 语法的详细信息，请查看 REST API 选项卡。
保存所做更改。
如果搜索字段为空，请运行索引器，将数据从源字段导入到新映射的搜索字段。如果之前填充了搜索字段，请在运行索引器之前对其进行重置，以便删除和添加内容。

使用创建索引器 API 请求创建新的索引器时，可添加字段映射。可使用更新索引器 API 请求来管理现有索引器的字段映射。

在此示例中，将一个源字段映射到了具有不同名称的目标字段：

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

可以在多个字段映射中引用一个源字段。以下示例演示如何“分叉”字段 - 将同一个源字段复制到两个不同的索引字段：


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

在用于 .NET 的 Azure SDK 中，可使用 FieldMapping 类，该类提供“SourceFieldName”和“TargetFieldName”属性以及可选的“MappingFunction”引用。

可以在构造索引器时指定字段映射，也可以在以后通过直接设置 SearchIndexer.FieldMappings 来指定字段映射。以下 C# 示例在构造索引器时设置字段映射。

var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
    Description = "SQL data indexer",
    Schedule = schedule,
    Parameters = parameters,
    FieldMappings =
    {
        new FieldMapping("_id") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

字段映射函数和示例

字段映射函数在将字段存储到索引中之前转换该字段的内容。目前支持以下映射函数：

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

base64Encode 函数

执行输入字符串的 URL 安全 Base64 编码。假定输入采用 UTF-8 进行编码。

示例：对文档键进行基本编码

Azure 认知搜索文档键中只能出现 URL 安全字符（以便可以使用查找 API 找到该文档）。如果键的源字段包含 URL 不安全字符（例如 - 和 \），在编制索引时，你可以使用 base64Encode 函数来转换该字段。

以下示例指定“metadata_storage_name”中的 base64Encode 函数以处理不受支持的字符。

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

文档键（转换前后）的长度不能超过 1,024 个字符。在搜索时检索编码的键时，请使用 base64Decode 函数获取原始键值，并使用它来检索源文档。

示例：使采用基本编码的字段“可搜索”

有时，需要使用一个字段的编码版本（如“metadata_storage_path”）作为键，但也需要未编码版本以进行全文搜索。若要支持这两种方案，你可以将“metadata_storage_path”映射到两个字段；一个用于键（编码版本），另一个用于在索引架构中可视为“可搜索”的路径字段。

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

示例 - 保留原始值

如果未指定字段映射，blob 存储索引器会自动将字段映射从 metadata_storage_path（blob 的 URI）添加到索引键字段。此值是 Base64 编码的，因此可以安全地作为 Azure 认知搜索文档键使用。下面的示例演示如何同时将 metadata_storage_path 的 URL 安全 Base64 编码版本映射到 index_key 字段和将原始值保留在 metadata_storage_path 字段中：

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

如果未包含映射函数的 parameters 属性，该属性的默认值为 {"useHttpServerUtilityUrlTokenEncode" : true}。

Azure 认知搜索支持两种不同的 Base64 编码：在编码和解码同一字段时，应使用相同的参数。在决定要使用哪些参数时，请参阅 base64 编码选项了解详细信息。

base64Decode 函数

执行输入字符串的 Base64 解码。假设输入是 URL 安全的 Base64 编码字符串。

示例 - 解码 Blob 元数据或 URL

源数据可能包含 Base64 编码的字符串（例如 Blob 元数据字符串或 Web URL），你希望这些字符串可作为纯文本进行搜索。可以在填充搜索索引时，使用 base64Decode 函数将编码的数据转换回到常规字符串。

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

如果未包含 parameters 属性，该属性的默认值为 {"useHttpServerUtilityUrlTokenEncode" : true}。

Azure 认知搜索支持两种不同的 Base64 编码。在编码和解码同一字段时，应使用相同的参数。在决定要使用哪些参数时，请参阅 base64 编码选项了解更多详细信息。

base64 编码选项

Azure 认知搜索支持 URL 安全的 base64 编码和正常的 base64 编码。在索引编制期间经过 base64 编码的字符串在以后应使用相同的编码选项进行解码，否则结果将与原始字符串不匹配。

如果将用于编码或解码的 useHttpServerUtilityUrlTokenEncode 或 useHttpServerUtilityUrlTokenDecode 参数分别设置为 true，则 base64Encode 的行为与 HttpServerUtility.UrlTokenEncode 类似，base64Decode 的行为与 HttpServerUtility.UrlTokenDecode 类似。

警告

如果使用 base64Encode 来生成密钥值，则必须将 useHttpServerUtilityUrlTokenEncode 设置为 true。只能将 URL 安全的 base64 编码用于密钥值。请参阅命名规则了解键值中字符的整套限制。

Azure 认知搜索中的 .NET 库采用完整的 .NET 框架来提供内置编码。 useHttpServerUtilityUrlTokenEncode 和 useHttpServerUtilityUrlTokenDecode 选项利用了此内置功能。如果使用 .NET Core 或其他框架，建议将这些选项设置为 false 并直接调用框架的编码和解码函数。

下表比较了对字符串 00>00?00 进行不同的 base64 编码的结果。若要确定 base64 函数所需的处理（如有），请对字符串 00>00?00 应用库编码函数，然后比较输出和预期的输出 MDA-MDA_MDA。

编码	Base64 编码输出	库编码后的其他处理	库解码前的其他处理
带填充的 Base64	`MDA+MDA/MDA=`	使用 URL 安全字符并删除填充	使用标准 base64 字符并添加填充
不带填充的 Base64	`MDA+MDA/MDA`	使用 URL 安全字符	使用标准 base64 字符
带填充的 URL 安全 Base64	`MDA-MDA_MDA=`	删除填充	添加填充
不带填充的 URL 安全 Base64	`MDA-MDA_MDA`	无	无

extractTokenAtPosition 函数

使用指定的分隔符拆分字符串字段，并在所生成拆分的指定位置处选取令牌。

此函数使用以下参数：

delimiter：在拆分输入字符串时，用作分隔符的字符串。
position：在拆分输入字段串后要选取的位置，以零为底的整数。

例如，如果输入是 Jane Doe，delimiter 是 " "（空格）并且 position 是 0，则结果为 Jane；如果 position 是 1，则结果是 Doe。如果位置引用的令牌不存在，则会返回错误。

示例 - 提取名称

数据源包含 PersonName 字段，并且想要为其编制索引作为两个单独的 FirstName 和 LastName 字段。可以使用此函数来拆分将空格字符用作分隔符的输入。

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

jsonArrayToStringCollection 函数

将已格式化为 JSON 字符串数组的字符串转换为可用于填充索引中 Collection(Edm.String) 字段的字符串数组。

例如，如果输入字符串是 ["red", "white", "blue"]，类型 Collection(Edm.String) 的目标字段由 red、white 和 blue 这三个值填充。对于无法分析为 JSON 字符串数组的输入值，则会返回错误。

示例 - 使用关系数据填充集合

Azure SQL 数据库不具有能自然映射到 Azure 认知搜索中 Collection(Edm.String) 字段的内置数据类型。若要填充字符串集合字段，可将源数据预处理成 JSON 字符串数组，然后使用 jsonArrayToStringCollection 映射函数。

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

urlEncode 函数

此函数可用于对字符串进行编码，使其是“URL 安全的”。与包含 URL 中不允许的字符的字符串结合使用时，此函数会将这些“不安全”字符转换为字符实体等效项。此函数使用 UTF-8 编码格式。

示例 - 文档键查找

如果只转换 URL 不安全字符，而将其他字符保留原样，则可以使用 urlEncode 函数来代替 base64Encode 函数。

例如，如果输入字符串是 <hello> - 则 (Edm.String) 类型的目标字段中将填充值 %3chello%3e

在搜索时检索编码的键时，可以使用 urlDecode 函数获取原始键值，然后使用该值来检索源文档。

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

urlDecode 函数

此函数使用 UTF-8 编码格式将 URL 编码的字符串转换为解码的字符串。

示例 - 解码 Blob 元数据

如果 blob 元数据包含非 ASCII 字符，某些 Azure 存储客户端会自动对这些元数据进行 URL 编码。但是，若要使此类元数据可搜索（作为纯文本），可以在填充搜索索引时，使用 urlDecode 函数将编码的数据转换回到常规字符串。

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

fixedLengthEncode 函数

此函数将任意长度的字符串转换为固定长度的字符串。

示例 - 映射过长的文档键

当出现与文档键长度超过 1024 个字符相关的错误时，可以应用此函数来减少文档键的长度。


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