使用 Azure AI 搜尋服務索引子的欄位對應和轉換
當 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) 或 更新索引子 (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" }
]
對應函式和範例
欄位對應函式會先轉換欄位中的內容,再將其儲存在索引中。 目前支援以下對應函式:
請注意,目前僅父索引支援這些函式。 它們與區塊索引對應不相容,因此這些函式無法用於索引投影。
base64Encode 函式
執行輸入字串的安全 URL Base64 編碼。 假設輸入以 UTF-8 編碼。
範例:對文件索引鍵進行基底編碼
Azure AI 搜尋服務服務文件索引鍵只會顯示安全的 URL 字元 (以便您使用查閱 API 來處理文件)。 如果索引鍵的來源欄位包含不安全的 URL 字元,例如 -
和 \
,請使用 base64Encode
函式在編制索引時轉換。
下列範例會在 metadata_storage_name
上指定 base64Encode 函式來處理不支援的字元。
PUT /indexers?api-version=2023-11-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=2023-11-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"
}
}
]
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應