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

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

何時設定場映射

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

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

場映射適用於：

• 資料路徑兩端的實體資料結構。 由技能建立的邏輯資料結構僅存在於記憶體中。 使用 outputFieldMappings 將記憶體內節點映射到搜尋索引中的輸出欄位。

• 僅限父 AI Search 索引。 對於帶有「子」文件或「區塊」的「次要」索引，請參閱 進階欄位映射情境。

• 僅限頂層搜尋欄位，其中 targetFieldName 是簡單欄位或集合。 目標場不能是複雜類型。

支援劇本

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

複雜的欄位不支援欄位映射。 你的來源結構（巢狀或階層結構）必須完全符合索引中的複數類型，這樣預設的映射才能正常運作。 更多資訊請參見 教學：索引巢狀 JSON blobs 範例。 如果你遇到類似 "Field mapping specifies target field 'Address/city' that doesn't exist in the index"的錯誤，是因為目標場映射不可能是複雜型態。

你也可以選擇在複雜結構中只設幾個節點。 要取得個別節點，你可以將輸入資料扁平化成字串集合（請參考 outputFieldMappings 作為這個變通方法）。

定義場映射

本節說明設置場域映射的步驟。

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

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

Azure AI 搜尋服務 支援兩種不同的 Base64 編碼。 編碼和解碼同一個欄位時，應該使用相同的參數。 欲了解更多資訊，請參閱 base64 編碼選項 以決定使用哪些參數。

base64 編碼選項

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

若 useHttpServerUtilityUrlTokenEncode 編碼與解碼的 or useHttpServerUtilityUrlTokenDecode 參數分別設為 true，則 base64Encode 的行為類似 HttpServerUtility.UrlTokenEncode ，且 base64Decode 行為類似 HttpServerUtility.UrlTokenDecode。

Azure AI 搜尋服務 中的 .NET 函式庫採用完整的 .NET 框架，提供內建編碼功能。 useHttpServerUtilityUrlTokenEncode 和 useHttpServerUtilityUrlTokenDecode 選項會應用此內建功能。 如果你使用 .NET Core 或其他框架，建議將這些選項設為 false，並直接呼叫框架的編碼與解碼函式。

下表比較了字串 00>00?00的不同 base64 編碼方式。 要判斷 base64 函式所需的處理量（如果有的話），請對字串 00>00?00 套用函式庫的編碼函式，並將輸出與預期輸出 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. 將函式轉換後的值映射到父文件和/或「子文件」

如果父文件中的欄位需要轉換（使用映射 函式 如編碼），且需要映射到父文件和/或「子文件」：

• 利用索引器中的欄位映射 函式 來套用轉換。
• 在技能組中使用 索引投影 ，將轉換後的欄位映射到「子」文件。

參見

• Azure AI 搜尋服務 中支援的資料型別
• SQL 資料型態映射