使用 Azure AI 搜尋服務索引器進行欄位對應和轉換

發行項
01/29/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 中，使用提供 SourceFieldName 和屬性和TargetFieldName選擇性MappingFunction參考的 FieldMapping 類別。

藉由直接設定 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編碼。

範例：以基底編碼檔索引鍵

只有 URL 安全字元可以出現在 Azure AI 搜尋檔案金鑰中（讓您可以使用查閱 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 }
    }
  }
]

如果您沒有包含 parameters 屬性，它會預設為值 {"useHttpServerUtilityUrlTokenEncode" : true}。

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 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 安全 base64	`MDA-MDA_MDA`	無	無

extractTokenAtPosition 函式

使用指定的分隔符分割字串字段，並在產生的分割中挑選位於指定位置的標記。

此函式會使用下列參數：

delimiter：分割輸入字串時要當做分隔符使用的字串。
position：在分割輸入字串之後要挑選之令牌的整數以零起始位置。

例如，如果輸入為，則為 Jane Doe" "（空格），而 position 為 0，則結果Jane為 ;如果 position 為 1，則結果為 Doe。delimiter 如果位置參考不存在的令牌，則會傳回錯誤。

範例 - 擷取名稱

您的數據源包含欄位 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 資料庫沒有內建數據類型，自然會對應至 Collection(Edm.String) Azure AI 搜尋中的欄位。若要填入字串集合欄位，您可以將源數據預先處理為 JSON 字串陣列，然後使用 jsonArrayToStringCollection 對應函式。

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

urlEncode 函式

此函式可用來編碼字串，使其「URL 安全」。與包含 URL 中不允許字元的字串搭配使用時，此函式會將這些「不安全」字元轉換成字元實體對等專案。此函式會使用UTF-8編碼格式。

範例 - 檔案索引鍵查閱

urlEncode 函式可作為函式的 base64Encode 替代方法，如果只轉換 URL 不安全字元，同時保留其他字元為非正則。

例如，輸入字串為 <hello> - 類型的目標欄位 (Edm.String) 將會填入值 %3chello%3e

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

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

urlDecode 函式

此函式會使用 UTF-8 編碼格式，將 URL 編碼的字串轉換成已譯碼的字串。

範例 - 譯碼 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"
    }
}

您可以在 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"
    }
  }
]