使用 Azure AI 搜尋服務索引子的欄位對應和轉換

發行項
10/16/2024

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

設定欄位對應的時機

當 Azure AI 搜尋服務索引子載入搜尋索引時，將會使用來源到目的地欄位對應來判斷資料路徑。隱含欄位對應是內部的，而且來源和目的地的欄位名稱和資料類型要相容才會發生。如果輸入和輸出不相符，您可以定義明確的「欄位對應」來設定資料路徑，如本文所述。

欄位對應也可透過對應函式用於輕量的資料轉換，如編碼或解碼。如果需要進一步處理，請考慮使用 Azure Data Factory 來彌補。

欄位對應適用於：

資料路徑兩端的實體資料結構。技能所建立的邏輯資料結構只位於記憶體中。使用 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 中使用建立索引子或建立或更新索引子或對等的方法。以下是索引子定義的範例。

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

填寫 fieldMappings 陣列以指定對應。欄位對應包含三個部分。

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

屬性	說明
sourceFieldName	必要。代表資料來源中的欄位。
targetFieldName	選擇性。代表搜尋索引中的欄位。如果省略，則會假定目標的值為 `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
jsonArrayToStringCollection
urlEncode
urlDecode

請注意，目前僅父索引支援這些函式。它們與區塊索引對應不相容，因此這些函式無法用於索引投影。

base64Encode 函式

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

範例：對文件索引鍵進行基底編碼

Azure AI 搜尋服務服務文件索引鍵只會顯示安全的 URL 字元 (以便您使用查閱 API 來處理文件)。如果索引鍵的來源欄位包含不安全的 URL 字元，例如 - 和 \，請使用 base64Encode 函式在編制索引時轉換。

下列範例會在 metadata_storage_name 上指定 base64Encode 函式來處理不支援的字元。

PUT /indexers?api-version=2024-07-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=2024-07-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_path (Blob 的 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 編碼。在編制索引期間經過 base64 編碼的字串，後續應使用相同的編碼選項來進行解碼，否則結果不會與原先相同。

如果用於編碼和解碼的 useHttpServerUtilityUrlTokenEncode 或 useHttpServerUtilityUrlTokenDecode 參數分別設定為 true，則 base64Encode 的行為會像 HttpServerUtility.UrlTokenEncode 且 base64Decode 的行為會像 HttpServerUtility.UrlTokenDecode。

警告

如果使用 base64Encode 來產生索引鍵值，則 useHttpServerUtilityUrlTokenEncode 必須設定為 true。只有安全的 URL base64 編碼可用做索引鍵值。如需索引鍵值中字元的完整限制條件，請參閱命名規則。

Azure AI 搜尋服務中的 .NET 程式庫會假設提供內建編碼的完整 .NET Framework。選項 useHttpServerUtilityUrlTokenEncode 和 useHttpServerUtilityUrlTokenDecode 會套用此內建功能。如果您使用的是 .NET 核心或其他架構，建議您將這些選項設為 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 編碼格式。

範例 - 文件索引鍵查閱

如果只轉換不安全的 URL 字元，而其他字元保持原狀，則 urlEncode 函式可作為 base64Encode 函式的替代方案。

若輸入字串是 <hello>，則 (Edm.String) 類型的目標欄位會填入 %3chello%3e 這個值

當您在搜尋期間擷取編碼的索引鍵時，您可以使用 urlDecode 函式來取得原索引鍵值，並使用該值來擷取來源檔案。

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

urlDecode 函式

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

範例 - 解碼 Blob 中繼資料

如果 Blob 中繼資料中包含非 ASCII 字元，某些 Azure 儲存體用戶端會自動對該 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.略過父系文件編製索引

如果您要略過父系文件編製索引 (透過在技能集 indexProjections 中的 projectionMode 設定為 skipIndexingParentDocuments)，請使用索引投影將父文件的欄位對應至「子系」文件。

2.為父系和「子系」文件編製索引

如果您要為父系文件和「子系」文件編製索引：

使用欄位對應將欄位對應至父系文件。
使用索引投影將欄位對應至「子系」文件。

3.將函式轉換的值對應至父系和/或「子系」文件

如果父系文件中的欄位需要轉換 (使用對應函式，例如編碼)，而且必須對應至父系和/或「子系」文件：

使用索引子中的欄位對應函式來套用轉換。
使用技能中的索引投影，將轉換的欄位對應至「子系」文件。

共用方式為