使用 Azure AI 搜尋服務索引器的欄位映射與轉換

註

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

本文說明如何設定明確的欄位映射，以建立支援資料來源欄位與搜尋索引目標欄位之間的資料路徑。

何時設定場映射

當 Azure AI 搜尋服務索引器載入搜尋索引時，會利用來源到目的地欄位映射來決定資料路徑。隱含欄位映射是內部的，當欄位名稱與資料型別在來源與目的地間相容時會發生。如果輸入和輸出不匹配，你可以定義明確的 欄位映射 來設定資料路徑，如本文所述。

場映射也可用於輕量級資料轉換，如編碼或解碼，透過映射函數進行。若需更多處理，可考慮Azure Data Factory來彌補空隙。

場映射適用於：

資料路徑兩端的實體資料結構。由技能建立的邏輯資料結構僅存在於記憶體中。使用 outputFieldMappings 將記憶體內節點映射到搜尋索引中的輸出欄位。
僅限父 AI Search 索引。對於帶有「子」文件或「區塊」的「次要」索引，請參閱進階欄位映射情境。
僅限頂層搜尋欄位，其中 targetFieldName 是簡單欄位或集合。目標場不能是複雜類型。

支援劇本

請確保你使用的是可以支援索引器驅動索引的資料來源。

使用情境	描述
名稱差異	假設你的資料來源有一個名為 `_city`的欄位。由於Azure AI 搜尋服務不允許以底線開頭的欄位名稱，欄位映射可以讓你有效地將「_city」對應到「城市」。如果你的索引需求包括從多個資料來源檢索內容，且欄位名稱在不同來源間有所不同，你可以使用欄位映射來釐清路徑。
類型差異	假設您希望一個來源整數欄位的型別為 `Edm.String`，以便於在搜尋索引中進行搜尋。因為類型不同，你需要定義欄位映射，才能讓資料路徑成功。請注意，Azure AI 搜尋服務的支援資料型別數量比許多資料來源少。如果你要匯入 SQL 資料，欄位映射可以讓你在搜尋索引中映射你想要的 SQL 資料型別。
一對多資料路徑	你可以在索引中用同一個來源欄位的內容來填入多個欄位。例如，你可能想對每個欄位套用不同的分析器，以支援客戶端應用程式中的不同使用情境。
編碼與解碼	你可以套用映射功能來支援索引時的資料 Base64 編碼或解碼。
將字串拆分或重構陣列為集合	你可以應用映射函式來拆分包含分隔符的字串，或將 JSON 陣列傳送到型別 `Collection(Edm.String)`為的搜尋欄位。

註

若不存在欄位映射，索引器會假設資料來源欄位應映射到同名的索引欄位。新增欄位映射會覆蓋來源欄位與目標欄位的預設欄位映射。有些索引器，例如 blob storage indexer，會自動為索引鍵欄位加入預設欄位映射。

複雜的欄位不支援欄位映射。你的來源結構（巢狀或階層結構）必須完全符合索引中的複數類型，這樣預設的映射才能正常運作。更多資訊請參見教學：索引巢狀 JSON blobs 範例。如果你遇到類似 "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 or 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` 值為。目標欄位必須是頂層的簡單欄位或集合。它不能是複雜的類型或集合。如果你處理的是資料型別問題，欄位的資料型別會在索引定義中指定。欄位映射只需要欄位名稱即可。
映射功能	可選的。由預先定義的函式組成，用以轉換資料。

範例：名稱或類型差異

明確欄位映射為名稱與類型不完全相同的情況建立資料路徑。

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
固定長度編碼
jsonArrayToStringCollection
toJson
urlEncode
urlDecode

請注意，這些函式目前僅支援父索引。它們不相容於分塊索引映射，因此這些函數無法用於索引投影。

base64Encode 函式

執行對輸入字串進行 URL 安全的 Base64 編碼。假設輸入為 UTF-8 編碼。

範例：文件鍵的基礎編碼

Azure AI 搜尋服務文件鍵中只能出現 URL 安全的字元（這樣你就能使用 Lookup API 來位址該文件）。如果你的金鑰來源欄位包含 URL 不安全字元，如 - 和 \，請在索引時使用該 base64Encode 函式將其轉換。

以下範例指定了 base64Encode 函式以 metadata_storage_name 處理不支援字元。

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 儲存索引器會自動將 blob 的 URI 從 metadata_storage_path 映射到索引鍵欄位。這個值是 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 元資料或網址

你的來源資料可能包含 Base64 編碼的字串，例如 blob 元資料字串或網頁網址，你希望這些字串能以純文字形式搜尋。你可以用這個 base64Decode 函式，將編碼的資料在搜尋索引填充時轉回一般字串。

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

如果你沒有包含參數屬性，它會預設為 {"useHttpServerUtilityUrlTokenEncode" : true}。

base64 編碼選項

Azure AI 搜尋服務支援 URL 安全的 base64 編碼及一般 base64 編碼。索引時以 base64 編碼的字串，之後應該用相同的編碼選項解碼，否則結果不會與原始相符。

若 useHttpServerUtilityUrlTokenEncode 編碼與解碼的 or 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-safe base64	`MDA-MDA_MDA`	沒有	沒有

extractTokenAtPosition 函式

使用指定的分隔符分割字串欄位，並在該分割中指定位置選取標記。

此函數使用以下參數：

delimiter：一個字串，用於分割輸入字串時作為分隔符。
position：輸入字串分割後要挑選的詞元之零起始整數位置。

例如，若輸入為 Jane Doe，則 delimiter 為 " "（空間）， position 為 0，結果為 Jane;若 position 為 1，則結果為 Doe。若該位置指向不存在的標記，則會回傳錯誤。

範例 - 擷取名稱

你的資料來源包含一個 PersonName 欄位，你想把它索引成兩個獨立 FirstName 的 and 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 Database 沒有自然對應到 Azure AI 搜尋服務中 Collection(Edm.String) 欄位的內建資料型態。要填充字串集合欄位，你可以先將來源資料預處理成 JSON 字串陣列，然後使用 jsonArrayToStringCollection 映射函式。

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

urlEncode 函式

此函式可用於編碼字串，使其「網址安全」。當字串包含不允許出現在 URL 中的字元時，這個函式會將那些「不安全」的字元轉換成字元與實體的等價物。此函式使用 UTF-8 編碼格式。

範例 - 文件金鑰查詢

urlEncode 函數可以作為 base64Encode 函數的替代，這在僅需轉換 URL 不安全字元，其他字元則保留原樣的情況下尤其適用。

假設輸入字串為 <hello> - ，那麼類型的目標欄位 (Edm.String) 會被填入 %3chello%3e

當你在搜尋時取得編碼的金鑰後，就可以用這個 urlDecode 函式取得原始金鑰值，並用它來取得原始文件。

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

urlDecode 函式

此函式會將 URL 編碼的字串轉換為 UTF-8 編碼格式的解碼字串。

範例 - 解碼 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）原生不支援複合或階層資料型態的情況，然後將其映射到複雜欄位。

範例 - 將文字內容映射到複雜欄位

假設有一列 SQL 列的 JSON 字串需要映射到索引中（相應定義的）複雜欄位， toJson 這個函式可以用來達成這個目標。例如，若索引中的複雜欄位需要填充以下資料：

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

可以透過使用 toJson 映射函式，對 SQL 列中的 JSON 字串欄位進行映射，該欄位看起來像是：{"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