Сопоставления полей и преобразования с помощью индексаторов поиска ИИ Azure

В этой статье объясняется, как задать явные сопоставления полей, которые устанавливают путь к данным между исходными полями в поддерживаемом источнике данных и целевых полях в индексе поиска.

Когда необходимо установить сопоставление полей

Когда индексатор поиска Azure AI загружает индекс поиска, он определяет путь к данным с помощью сопоставлений полей источника и назначения. Неявные сопоставления полей являются внутренними и происходят, когда имена полей и типы данных совместимы между источником и назначением. Если входные и выходные данные не совпадают, можно определить явные сопоставления полей для настройки пути к данным, как описано в этой статье.

Сопоставления полей также можно использовать для упрощённого преобразования данных, таких как кодирование или декодирование, с помощью функций отображения. Если требуется больше обработки, рассмотрите Azure Data Factory для преодоления разрыва.

Применяются следующие сопоставления полей:

• Физические структуры данных на обеих сторонах пути к данным. Логические структуры данных, созданные навыками, находятся только в памяти. Используйте outputFieldMappings для сопоставления узлов в памяти с полями вывода в индексе поиска.

• Только индексы родительского поиска с ИИ. Для вспомогательных индексов с дочерними документами или блоками обратитесь к сценариям расширенного сопоставления полей.

• Только поля поиска верхнего уровня, где targetFieldName это простое поле или коллекция. Целевое поле не может быть сложным типом.

Поддерживаемые сценарии

Убедитесь, что используете поддерживаемый источник данных для индексирования, управляемого индексатором.

Сложные поля не поддерживаются в процессе сопоставления полей. Исходная структура (вложенные или иерархические структуры) должна точно соответствовать сложному типу в индексе, чтобы сопоставления по умолчанию работали. Для получения дополнительной информации см. руководство «Индексирование вложенных JSON BLOB-объектов». Если вы получите ошибку, аналогичную "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
• fixedLengthEncode
• jsonArrayToStringCollection
• toJson
• urlEncode
• urlDecode

Обратите внимание, что эти функции поддерживаются исключительно для родительских индексов в настоящее время. Они несовместимы с сопоставлением фрагментированных индексов, поэтому эти функции нельзя использовать для проекций индексов.

Функция base64Encode

Выполняет безопасное для URL Base64-кодирование входной строки. Входные данные должны быть в кодировке UTF-8.

Пример: базовая кодировка ключа документа

Только символы, безопасные для URL, могут появляться в ключе документа Azure AI Search, чтобы вы могли обратиться к документу с помощью API Lookup. Если исходное поле для ключа содержит небезопасные символы URL-адреса, например - и \используйте base64Encode функцию для преобразования его во время индексирования.

В следующем примере указывается функция base64Encode для metadata_storage_name обработки неподдерживаемых символов.

PUT /indexers?api-version=2025-09-01
{
  "dataSourceName" : "my-blob-datasource ",
  "targetIndexName" : "my-search-index",
  "fieldMappings" : [
    { 
        "sourceFieldName" : "metadata_storage_name", 
        "targetFieldName" : "key", 
        "mappingFunction" : { 
            "name" : "base64Encode",
            "parameters" : { "useHttpServerUtilityUrlTokenEncode" : false }
        } 
    }
  ]
}

Ключ документа (как до, так и после преобразования) не может превышать 1024 символов. При получении закодированного ключа во время поиска используйте base64Decode функцию, чтобы получить исходное значение ключа и использовать ее для извлечения исходного документа.

Пример: Сделать поле с кодировкой по основанию "поисковым"

Иногда требуется использовать закодированную версию поля, например metadata_storage_path ключа, но также требуется незакодированная версия для полнотекстового поиска. Для поддержки обоих сценариев можно сопоставить metadata_storage_path с двумя полями: одно для ключа (закодированного), а второе для поля пути, которое можно предположить, является атрибутом searchable в схеме индекса.

PUT /indexers/blob-indexer?api-version=2025-09-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, URI blob, в поле ключа индекса, если сопоставление полей не указано. Это значение закодировано в кодировке Base64, поэтому оно безопасно использовать в качестве ключа документа поиска ИИ Azure. В следующем примере показано, как одновременно сопоставлять безопасную для URL-адреса версию metadata_storage_path, закодированную с помощью Base64, с полем index_key и сохранить исходное значение в поле metadata_storage_path.

"fieldMappings": [
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "metadata_storage_path"
  },
  {
    "sourceFieldName": "metadata_storage_path",
    "targetFieldName": "index_key",
    "mappingFunction": {
       "name": "base64Encode"
    }
  }
]

Если свойство parameters для функции сопоставления не указано, по умолчанию используется значение {"useHttpServerUtilityUrlTokenEncode" : true}.

Служба "Поиск ИИ Azure" поддерживает два разных кодировки Base64. При кодировании и декодировании одного и того же поля следует использовать одни и те же параметры. Чтобы решить, какие параметры использовать, см. дополнительные сведения в разделе о вариантах кодировки Base64.

Функция base64Decode

Выполняет декодирование входной строки в Base64. Предполагается, что входные данные представляют собой безопасную для URL-адреса строку в кодировке Base64.

Пример. декодирование метаданных BLOB-объектов или URL-адресов

Исходные данные могут содержать строки в кодировке Base64, например строки метаданных BLOB-объектов или URL-адреса веб-узлов, которые требуется включить в поиск в виде обычного текста. Можно использовать функцию base64Decode, чтобы при заполнении индекса поиска снова превратить закодированные данные в обычные строки.

"fieldMappings" : [
  {
    "sourceFieldName" : "Base64EncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : { 
      "name" : "base64Decode", 
      "parameters" : { "useHttpServerUtilityUrlTokenDecode" : false }
    }
  }
]

Если свойство parameters не указано, по умолчанию используется значение {"useHttpServerUtilityUrlTokenEncode" : true}.

Служба "Поиск ИИ Azure" поддерживает два разных кодировки Base64. При кодировании и декодировании одного и того же поля следует использовать одни и те же параметры. Чтобы решить, какие параметры использовать, см. дополнительные сведения в разделе о вариантах кодировки Base64.

Варианты кодировки Base64

Поиск ИИ Azure поддерживает URL-безопасную и обычную кодировку base64. Строку, кодируемую с помощью Base64 во время индексирования, позже нужно декодировать, используя те же параметры кодировки, иначе результат не будет совпадать с оригиналом.

Если параметрам useHttpServerUtilityUrlTokenEncode или useHttpServerUtilityUrlTokenDecode для кодирования и декодирования соответственно присвоено значение true, то base64Encode ведет себя как HttpServerUtility.UrlTokenEncode, а base64Decode — как HttpServerUtility.UrlTokenDecode.

Предполагается, что библиотеки .NET в Azure AI Search используют полную версию .NET Framework, которая обеспечивает встроенную кодировку. useHttpServerUtilityUrlTokenEncode и useHttpServerUtilityUrlTokenDecode параметры применяют эту встроенную функцию. Если вы используете .NET Core или другую платформу, рекомендуется задать эти параметры на false и напрямую вызывать функции кодирования и декодирования вашего фреймворка.

В следующей таблице сравниваются различные кодировки Base64 строки 00>00?00. Чтобы определить необходимую обработку (если есть) для функций base64, примените функцию кодирования библиотеки к строке 00>00?00 и сравните выходные данные с ожидаемыми выходными данными 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, возвращается ошибка.

Пример: заполнение коллекции реляционными данными

База данных SQL Azure не имеет встроенный тип данных, который естественно сопоставляется с полями Collection(Edm.String) в поиске ИИ Azure. Чтобы заполнить поля сбора строк, можно предварительно обработать исходные данные в виде массива строк 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

Эта функция преобразует строку в кодировке URL в декодированную строку, используя формат кодирования UTF-8.

Пример. декодирование метаданных BLOB-объекта

Некоторые клиенты хранилищ Azure автоматически кодируют метаданные BLOB-объектов в формате URL, если они содержат символы, не являющиеся частью набора ASCII. Однако если вы хотите сделать такие метаданные доступными для поиска (в виде обычного текста), можно использовать функцию 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. Это можно использовать для сценариев, когда источник данных, например SQL Azure, не поддерживает составные или иерархические типы данных, а затем сопоставляет его со сложными полями.

Пример. Сопоставление текстового содержимого со сложным полем

Предположим, что в индексе есть строка SQL со строкой JSON, которую необходимо сопоставить со сложным полем (соответствующим образом определенным) в индексе, toJson эту функцию можно использовать для этого. Например, если сложное поле в индексе должно быть заполнено следующими данными:

{
    "id": "5",
    "info": {
        "name": "Jane",
        "surname": "Smith",
        "skills": [
            "SQL",
            "C#",
            "Azure"
        ],
        "dob": "2005-11-04T12:00:00"
    }
}

Его можно достичь с помощью toJson функции сопоставления в столбце строки JSON в строке SQL, которая выглядит следующим образом: {"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
• Карта типов данных SQL