你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
使用 Azure 认知搜索索引器进行字段映射和转换
使用 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 选项卡。
保存所做更改。
如果搜索字段为空,请运行索引器,将数据从源字段导入到新映射的搜索字段。 如果之前填充了搜索字段,请在运行索引器之前对其进行重置,以便删除和添加内容。
字段映射函数和示例
字段映射函数在将字段存储到索引中之前转换该字段的内容。 目前支持以下映射函数:
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"
}
}]