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

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

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

本文介绍如何设置显式字段映射，用于在支持的数据源中的源字段与搜索索引中的目标字段之间建立数据路径。

何时设置字段映射

当 Azure AI 搜索索引器加载搜索索引时，它将使用源到目标字段映射来确定数据路径。隐式字段映射是内部的，当字段名称和数据类型在源和目标之间兼容时发生。如果输入和输出不匹配，可以定义显式 字段映射 来设置数据路径，如本文所述。

字段映射还可用于轻量级数据转换，例如编码或解码，通过映射函数。如果需要更多处理，请考虑Azure 数据工厂来弥合差距。

字段映射适用于：

数据路径两侧的物理数据结构。技能创建的逻辑数据结构仅驻留在内存中。使用 outputFieldMappings 将内存中节点映射到搜索索引中的输出字段。
仅限父 AI 搜索索引。有关包含“子”文档或“区块”的“辅助”索引，请参阅高级字段映射方案。
仅顶级搜索字段，其中 targetFieldName 是简单字段或集合。目标字段不能是复杂类型。

支持的方案

请确保使用支持的数据源进行索引器驱动索引编制。

用例	描述
名称差异	设想你的数据源拥有一个名为 `_city` 的字段。鉴于 Azure AI 搜索不允许以下划线开头的字段名称，你可以使用字段映射将“_city”有效地映射到“city”。如果索引要求包括从多个数据源检索内容，其中字段名称因源而异，则可以使用字段映射来阐明路径。
类型差异	假设希望将源整数字段设置为类型`Edm.String`，以便可以在搜索索引中进行搜索。由于类型不同，因此需要定义字段映射，以便数据路径成功。请注意，Azure AI 搜索支持的数据类型比许多数据源要少。如果要导入 SQL 数据，字段映射允许映射搜索索引中所需的 SQL 数据类型。
一对多数据路径	可以使用来自同一源字段的内容填充索引中的多个字段。例如，你可能想要将不同的分析器应用于每个字段，以支持客户端应用中的不同用例。
编码和解码	可以在索引编制过程中应用映射函数以支持 Base64 编码或解码数据。
将字符串拆分或将数组重新结构化为集合	可以应用映射函数来拆分包含分隔符的字符串，或将 JSON 数组发送到类型的 `Collection(Edm.String)`搜索字段。

注意

如果没有字段映射，索引器假定数据源字段应映射到具有相同名称的索引字段。添加字段映射会覆盖源字段和目标字段的默认字段映射。某些索引器（如 Blob 存储索引器）会自动为索引键字段添加默认字段映射。

字段映射不支持复杂字段。源结构（嵌套或分层结构）必须与索引中的复杂类型完全匹配，以便默认映射有效。有关详细信息，请参阅教程：为嵌套 JSON Blob 编制索引，获取示例。如果收到类似 "Field mapping specifies target field 'Address/city' that doesn't exist in the index"错误，这是因为目标字段映射不能是复杂类型。

可以选择在复杂结构中选取几个节点。若要获取单个节点，可以将传入数据平展到字符串集合中（请参阅 outputFieldMappings 以获取此解决方法）。

定义字段映射

本部分介绍设置字段映射的步骤。

REST API
.NET SDK （C#）

在Azure SDK中使用 Create Indexer 或 Create 或 Update Indexer 或等效方法。下面是索引器定义的示例。

{
   "name": "myindexer",
   "description": null,
   "dataSourceName": "mydatasource",
   "targetIndexName": "myindex",
   "schedule": { },
   "parameters": { },
   "fieldMappings": [],
   "disabled": false,
   "encryptionKey": { }
 }

填写fieldMappings数组，以便完整地指定映射。字段映射由三个部分组成。

"fieldMappings": [
  {
    "sourceFieldName": "_city",
    "targetFieldName": "city",
    "mappingFunction": null
  }
]

财产	描述
sourceFieldName	必填。表示数据源中的字段。
目标字段名称	可选的表示搜索索引中的字段。如果省略，则假定目标的值为`sourceFieldName`。目标字段必须是顶级简单字段或集合。它不能是复杂类型或集合。如果要处理数据类型问题，则会在索引定义中指定字段的数据类型。字段映射只需要具有字段的名称。
mappingFunction	可选的由转换数据的预定义函数组成。

示例：名称或类型差异

显式字段映射为名称和类型不完全相同的情况建立数据路径。

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

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" : "_city", "targetFieldName" : "city" } ]
}

示例：一对多或分叉数据路径

本示例将单个源字段映射到多个目标字段（“一对多”映射）。可以“分叉”字段，将相同的源字段内容复制到两个不同的索引字段，这些字段将在索引中以不同的方式进行分析或属性化。


"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("_hotelId") {TargetFieldName = "HotelId", FieldMappingFunction.Base64Encode()},
        new FieldMapping("Amenities") {TargetFieldName = "Tags"}
    }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

映射函数和示例

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

base64Encode
base64Decode
extractTokenAtPosition
fixedLengthEncode
jsonArrayToStringCollection
toJson
urlEncode
urlDecode

请注意，目前父索引仅支持这些函数。它们与分块索引映射不兼容，因此，这些函数不能用于索引投影。

base64Encode 函数

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

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

只有 URL 安全字符可以出现在Azure AI 搜索文档密钥中（以便可以使用 Lookup API 对文档进行寻址）。如果密钥的源字段包含 URL 不安全的字符，如 - 和 \，请在索引时使用 base64Encode 函数对其进行转换。

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

PUT /indexers?api-version=2026-04-01
{
  "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 映射到两个字段；一个表示键（已编码），第二个表示可假定为在索引架构中 searchable 的路径字段。

PUT /indexers/blob-indexer?api-version=2026-04-01
{
    "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_pathblob 的 URI 添加到索引键字段。此值是 Base64 编码的，因此可以安全地用作Azure AI 搜索文档密钥。以下示例演示如何同时将 URL 安全的 Base64 编码版本 metadata_storage_path 映射到 index_key 字段，并在字段中保留原始值 metadata_storage_path ：

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

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

Azure AI 搜索支持两种不同的 Base64 编码。编码和解码同一字段时，应使用相同的参数。有关详细信息，请参阅 base64 编码选项，确定要使用的参数。

base64Decode 函数

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

示例 - 解码 Blob 元数据或 URL

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

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

如果未包含参数属性，则默认为值 {"useHttpServerUtilityUrlTokenEncode" : true}。

Azure AI 搜索支持两种不同的 Base64 编码。编码和解码同一字段时，应使用相同的参数。有关详细信息，请参阅 base64 编码选项，确定要使用的参数。

base64 编码选项

Azure AI 搜索支持 URL 安全的 base64 编码和普通 base64 编码。在索引编制过程中编码的字符串应稍后使用相同的编码选项解码，否则结果与原始字符串不匹配。

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

警告

如果 base64Encode 用于生成键值， useHttpServerUtilityUrlTokenEncode 则必须设置为 true。仅可使用 URL 安全的 base64 编码来处理键值。有关关键值中字符的完整限制集，请参阅命名规则。

Azure AI 搜索中的.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 AI 搜索中 Collection(Edm.String) 字段的内置数据类型。若要填充字符串集合字段，可以将源数据预处理为 JSON 字符串数组，然后使用 jsonArrayToStringCollection 映射函数。

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

urlEncode 函数

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

示例 - 文档键查找

urlEncode 函数可用作函数的 base64Encode 替代方法，前提是仅转换 URL 不安全字符，同时保留其他字符 as-is。

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

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

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

urlDecode 函数

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

示例 - 解码 Blob 元数据

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

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

fixedLengthEncode 函数

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

示例 - 映射过长的文档键

如果出现与文档密钥长度超过 1024 个字符相关的错误，则可以应用此函数来减少文档密钥的长度。


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

toJson 函数

此函数将字符串转换为格式化的 JSON 对象。这可用于数据源（如Azure SQL）本身不支持复合或分层数据类型的方案，然后将其映射到复杂字段。

示例 - 将文本内容映射到复杂字段

假设有一个包含 JSON 字符串的 SQL 行，该行需要映射到索引中的（相应定义的）复杂字段， toJson 该函数可用于实现此目的。例如，如果需要用以下数据填充索引中的复杂字段：

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

可以在 SQL 行中的 JSON 字符串列中使用 toJson 映射函数，如下所示：{"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}。

需要指定字段映射，如下所示。


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]

高级字段映射场景

在具有“一对多”文档关系（如数据分块或拆分）的情况下，请按照以下准则将字段从父文档映射到“子”文档（区块）：

1.跳过父文档索引编制

若要跳过父文档的索引（通过在技能组的 projectionMode 中将 skipIndexingParentDocuments 设置为 indexProjections），请使用索引投影将字段从父文档映射到“子”文档。

2. 为父文档和“子”文档编制索引

如果要为父文档和“子文档”编制索引：

使用字段映射将字段映射到父文档。
使用索引投影将字段映射到“子”文档。

3. 将经过函数转换的值映射到父文档和/或子文档

如果父文档中的字段需要转换（使用编码等映射函数），并且需要映射到父文档和/或“子”文档：

使用索引器中的字段映射函数应用转换。
使用索引投影在技能集中将转换后的字段映射到“子”文档。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-07-03