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

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

Indexer Stages

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

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

场景和限制

字段映射支持以下场景:

  • 重命名字段或处理名称差异。 假设数据源包含名为 _id 的字段。 鉴于 Azure 认知搜索不允许以下划线开头的字段名称,字段映射让你可以有效地重命名字段。

  • 数据类型差异。 与许多数据源相比,认知搜索具有的支持的数据类型更少。 如果要导入 SQL 数据,可使用字段映射来映射搜索索引中所需的 SQL 数据类型

  • 一对多数据路径。 可以使用同一字段中的内容填充索引中的多个字段。 例如,你可能希望对每个字段应用不同的分析器。

  • 具有不同字段名称的多个数据源,你希望在其中使用多个数据源中的文档填充某个搜索字段。 如果数据源之间的字段名称不同,你可以使用字段映射来明确路径。

  • 数据的 Base64 编码或解码。 字段映射支持多个映射函数,包括用于 Base64 编码和解码的函数。

  • 拆分字符串或将 JSON 数组重新强制转换为字符串集合。 字段映射函数提供这种功能。

限制

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

  • 必须将“targetFieldName”设置为单个字段名称,要么为单个字段,要么为集合。 你目前无法定义复杂字段(例如 address/city)中的子字段的字段路径。 一种解决方法是添加技能组并使用整形程序技能

  • 字段映射仅适用于搜索索引。 对于还会创建知识存储的索引器,数据形状投影确定了字段关联,并将忽略索引器中的任何字段映射和输出字段映射。

设置字段映射

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

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

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

注意

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

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

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

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

  1. 打开现有索引器的 JSON 定义。

  2. 在“fieldMappings”部分下,添加源和目标字段。 目标字段必须存在于搜索索引中,并且符合字段命名约定。 有关更多 JSON 语法的详细信息,请查看 REST API 选项卡。

  3. 保存所做更改。

  4. 如果搜索字段为空,请运行索引器,将数据从源字段导入到新映射的搜索字段。 如果之前填充了搜索字段,请在运行索引器之前对其进行重置,以便删除和添加内容。

字段映射函数和示例

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

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 编码的字符串在以后应使用相同的编码选项进行解码,否则结果将与原始字符串不匹配。

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

警告

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

Azure 认知搜索中的 .NET 库采用完整的 .NET 框架来提供内置编码。 useHttpServerUtilityUrlTokenEncodeuseHttpServerUtilityUrlTokenDecode 选项利用了此内置功能。 如果使用 .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 Doedelimiter" "(空格)并且 position 是 0,则结果为 Jane;如果 position 是 1,则结果是 Doe。 如果位置引用的令牌不存在,则会返回错误。

示例 - 提取名称

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

"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) 的目标字段由 redwhiteblue 这三个值填充。 对于无法分析为 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"
   }
 }]

另请参阅