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

發行項
06/14/2024

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

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

欄位對應適用於：

資料流兩端的實體資料結構 (在支援資料來源和搜尋索引的欄位之間)。如果您要匯入位於記憶體中的技能擴充內容，請使用 outputFieldMappings 將記憶體內部節點對應至搜尋索引中的輸出欄位。
限搜尋索引。如果您要填入知識存放區，請使用資料路徑組態的投影。
限最上層的搜尋欄位，其中 targetFieldName 為簡單欄位或集合。目標欄位不得為複雜類型。

注意

如果您要處理複雜的資料 (巢狀或階層式結構)，而且想要在您的搜尋索引中鏡像該資料結構，則您的搜尋索引必須完全符合來源結構 (欄位名稱、層級和類型皆相同)，以便預設對應正常運作。您也可能只需要複雜結構中的少數幾個節點。若要取得個別節點，您可以將傳入的資料壓平合併為字串集合 (請參閱 outputFieldMappings 以了解此因應措施)。

支援的案例

使用案例	描述
名稱不一致	假設您的資料來源有一個名為 `_city` 的欄位。由於 Azure AI 搜尋服務不允許以底線開頭的欄位名稱，欄位對應可讓您有效地將「_city」對應至「city」。如果您的索引需求包括從多個資料來源擷取內容 (其中欄位名稱因來源而異)，您可以使用欄位對應來釐清路徑。
類型不一致	假設您希望來源的整數欄位類型為 `Edm.String`，以便在搜尋索引中搜尋。由於類型不同，您必須定義欄位對應，才能讓資料路徑成功。請注意，Azure AI 搜尋服務支援的資料類型比許多資料來源都來得少。如果您要匯入 SQL 資料，欄位對應可讓您在搜尋索引中對應您所需的 SQL 資料類型。
一對多資料路徑	您可以用相同來源欄位的內容填入索引中的多個欄位。例如，您可能想要為各個欄位套用不同的分析器，以支援用戶端應用程式中不同的使用案例。
編碼及解碼	在編制索引期間，您可以套用對應函式來支援資料的 Base64 編碼或解碼。
將字串分割或將陣列重新轉換成集合	您可以套用對應函式來分割包含分隔符號的字串，或將 JSON 陣列傳送至類型 `Collection(Edm.String)` 的搜尋欄位。

定義欄位對應

欄位對應會新增至索引子定義的 fieldMappings 陣列。欄位對應包含三個部分。

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

屬性	說明
sourceFieldName	必要。代表資料來源中的欄位。
targetFieldName	選擇性。代表搜尋索引中的欄位。如果省略，則會假定目標的值為 `sourceFieldName`。目標欄位必須是最上層的簡單欄位或集合。它不能是複雜類型或集合。如果您正在處理資料類型問題，則索引定義中會指定欄位的資料類型。欄位對應只需要有欄位名稱即可。
mappingFunction	選擇性。包含負責轉換資料的預定義函式。

如果您收到類似 "Field mapping specifies target field 'Address/city' that doesn't exist in the index"的錯誤，這是因為目標字段對應不能是複雜類型。因應措施是建立索引架構，其與功能變數名稱和數據類型的原始內容相同。如需範例，請參閱教學課程：編製巢狀 JSON Blob 的索引。

Azure AI 搜尋服務會使用不區分大小寫的比較，解析欄位對應的欄位和函式名稱。這很方便 (大小寫不需要完全正確)，但這表示資料來源或索引不能有只以大小寫區分的欄位。

注意

如果沒有欄位對應，索引子會假定資料來源欄位對應至具有相同名稱的索引欄位。新增欄位對應可以覆寫來源和目標欄位的預設欄位對應。某些索引子 (如 Blob 儲存體索引子) 會為索引鍵欄位新增預設欄位對應。

您可以使用 REST API 或 Azure SDK 來定義欄位對應。

REST API
.NET SDK (C#)

使用建立索引子 (REST) 或更新索引子 (REST)、任何 API 版本。

此範例會處理欄位名稱不一致的情況。

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=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 對應至兩個欄位：一個用於索引鍵 (編碼)，另一個用於我們能假設在索引架構描述中屬性為 searchable 的路徑欄位。

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 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)，並將其對應至複雜欄位。

範例 - 將文字內容對應至複雜欄位

假設有一個 SQL 數據列，其 JSON 字串必須對應至索引中的（對應定義）複雜欄位， 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"
    }
  }
]

共用方式為