Mapeamentos e transformações de campo usando indexadores do Azure AI Search

Artigo
03/15/2024

Quando um indexador do Azure AI Search carrega um índice de pesquisa, ele determina o caminho de dados usando mapeamentos de campo de origem para destino. Os mapeamentos de campo implícitos são internos e ocorrem quando os nomes de campo e os tipos de dados são compatíveis entre a origem e o destino. Se as entradas e saídas não corresponderem, você poderá definir mapeamentos de campo explícitos para configurar o caminho de dados, conforme descrito neste artigo.

Os mapeamentos de campo também podem ser usados para conversões de dados leves, como codificação ou decodificação, por meio de funções de mapeamento. Se for necessário mais processamento, considere o Azure Data Factory para preencher a lacuna.

Os mapeamentos de campo aplicam-se a:

Estruturas de dados físicas em ambos os lados do fluxo de dados (entre campos em uma fonte de dados suportada e campos em um índice de pesquisa). Se você estiver importando conteúdo enriquecido com habilidades que reside na memória, use outputFieldMappings para mapear nós na memória para campos de saída em um índice de pesquisa.
Apenas índices de pesquisa. Se você estiver preenchendo um repositório de conhecimento, use projeções para a configuração do caminho de dados.
Apenas campos de pesquisa de nível superior, onde o targetFieldName é um campo simples ou uma coleção. Um campo de destino não pode ser um tipo complexo.

Nota

Se você estiver trabalhando com dados complexos (estruturas aninhadas ou hierárquicas) e quiser espelhar essa estrutura de dados em seu índice de pesquisa, seu índice de pesquisa deverá corresponder exatamente à estrutura de origem (mesmos nomes de campo, níveis e tipos) para que os mapeamentos padrão funcionem. Opcionalmente, você pode querer apenas alguns nós na estrutura complexa. Para obter nós individuais, você pode nivelar os dados de entrada em uma coleção de cadeia de caracteres (consulte outputFieldMappings para esta solução alternativa).

Cenários suportados

Caso de utilização	Description
Discrepância de nome	Suponha que sua fonte de dados tenha um campo chamado `_city`. Dado que o Azure AI Search não permite nomes de campo que comecem com um sublinhado, um mapeamento de campo permite mapear efetivamente "_city" para "cidade". Se seus requisitos de indexação incluírem a recuperação de conteúdo de várias fontes de dados, onde os nomes de campo variam entre as fontes, você poderá usar um mapeamento de campo para esclarecer o caminho.
Discrepância de tipo	Suponha que você queira que um campo inteiro de origem seja do tipo `Edm.String` para que possa ser pesquisado no índice de pesquisa. Como os tipos são diferentes, você precisará definir um mapeamento de campo para que o caminho de dados seja bem-sucedido. Observe que o Azure AI Search tem um conjunto menor de tipos de dados com suporte do que muitas fontes de dados. Se você estiver importando dados SQL, um mapeamento de campo permitirá mapear o tipo de dados SQL desejado em um índice de pesquisa.
Caminhos de dados um-para-muitos	Você pode preencher vários campos no índice com conteúdo do mesmo campo de origem. Por exemplo, talvez você queira aplicar analisadores diferentes a cada campo para dar suporte a diferentes casos de uso em seu aplicativo cliente.
Codificação e descodificação	Você pode aplicar funções de mapeamento para dar suporte à codificação Base64 ou decodificação de dados durante a indexação.
Dividir cadeias de caracteres ou reformular matrizes em coleções	Você pode aplicar funções de mapeamento para dividir uma cadeia de caracteres que inclui um delimitador ou para enviar uma matriz JSON para um campo de pesquisa do tipo `Collection(Edm.String)`.

Definir um mapeamento de campo

Mapeamentos de campo são adicionados à fieldMappings matriz de uma definição de indexador. Um mapeamento de campo consiste em três partes.

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

Property	Description
sourceFieldName	Obrigatório. Representa um campo em sua fonte de dados.
targetFieldName	Opcional. Representa um campo no índice de pesquisa. Se omitido, o valor de é assumido `sourceFieldName` para o destino. Os campos de destino devem ser campos simples de nível superior ou coleções. Não pode ser um tipo ou coleção complexa. Se você estiver lidando com um problema de tipo de dados, o tipo de dados de um campo será especificado na definição de índice. O mapeamento de campo só precisa ter o nome do campo.
Função mappingFunction	Opcional. Consiste em funções predefinidas que transformam dados.

Se você receber um erro semelhante ao "Field mapping specifies target field 'Address/city' that doesn't exist in the index", é porque os mapeamentos de campo de destino não podem ser um tipo complexo. A solução alternativa é criar um esquema de índice idêntico ao conteúdo bruto para nomes de campos e tipos de dados. Consulte Tutorial: Indexar blobs JSON aninhados para obter um exemplo.

O Azure AI Search usa a comparação sem diferenciação de maiúsculas e minúsculas para resolver os nomes de campo e função em mapeamentos de campo. Isso é conveniente (você não precisa acertar todo o invólucro), mas significa que sua fonte de dados ou índice não pode ter campos que diferem apenas por maiúsculas e minúsculas.

Nota

Se nenhum mapeamento de campo estiver presente, os indexadores assumirão que os campos da fonte de dados devem ser mapeados para campos de índice com o mesmo nome. Adicionar um mapeamento de campo substitui os mapeamentos de campo padrão para o campo de origem e de destino. Alguns indexadores, como o indexador de armazenamento de blob, adicionam mapeamentos de campo padrão para o campo de chave de índice.

Você pode usar a API REST ou um SDK do Azure para definir mapeamentos de campo.

APIs REST
SDK .NET (C#)

Use Create Indexer (REST) ou Update Indexer (REST), qualquer versão da API.

Este exemplo lida com uma discrepância de nome de campo.

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" } ]
}

Este exemplo mapeia um único campo de origem para vários campos de destino (mapeamentos "um-para-muitos"). Você pode "bifurcar" um campo, copiando o mesmo conteúdo do campo de origem para dois campos de índice diferentes que serão analisados ou atribuídos de forma diferente no índice.


"fieldMappings" : [
    { "sourceFieldName" : "text", "targetFieldName" : "textStandardEnglishAnalyzer" },
    { "sourceFieldName" : "text", "targetFieldName" : "textSoundexAnalyzer" }
]

No SDK do Azure para .NET, use a classe FieldMapping que fornece SourceFieldName propriedades e TargetFieldName uma referência opcional MappingFunction .

Especifique mapeamentos de campo ao construir o indexador ou posterior definindo diretamente SearchIndexer.FieldMappings. O exemplo C# a seguir define os mapeamentos de campo ao construir um indexador.

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);

Mapeando funções e exemplos

Uma função de mapeamento de campo transforma o conteúdo de um campo antes de ser armazenado no índice. As seguintes funções de mapeamento são suportadas atualmente:

base64Encode
base64Decodificar
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecodificação

função base64Encode

Executa a codificação Base64 segura para URL da cadeia de caracteres de entrada. Assume que a entrada é codificada em UTF-8.

Exemplo: Codificação de base de uma chave de documento

Somente caracteres seguros para URL podem aparecer em uma chave de documento do Azure AI Search (para que você possa endereçar o documento usando a API de Pesquisa). Se o campo de origem da sua chave contiver caracteres não seguros de URL, como - e \, use a função para convertê-la no momento da base64Encode indexação.

O exemplo a seguir especifica a função base64Encode para metadata_storage_name manipular caracteres sem suporte.

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 }
        } 
    }
  ]
}

Uma chave de documento (antes e depois da conversão) não pode ter mais de 1.024 caracteres. Quando você recuperar a chave codificada no momento da pesquisa, use a base64Decode função para obter o valor da chave original e use-o para recuperar o documento de origem.

Exemplo: Tornar um campo codificado em base "pesquisável"

Há momentos em que você precisa usar uma versão codificada de um campo como metadata_storage_path a chave, mas também precisa de uma versão não codificada para pesquisa de texto completo. Para dar suporte a ambos os cenários, você pode mapear metadata_storage_path para dois campos: um para a chave (codificada) e um segundo para um campo de caminho que podemos supor que é atribuído como searchable no esquema de índice.

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" }
      ]
}

Exemplo - preservar valores originais

O indexador de armazenamento de blob adiciona automaticamente um mapeamento de campo de , o URI do blob, ao campo de chave de índice se nenhum mapeamento de metadata_storage_pathcampo for especificado. Esse valor é codificado em Base64, portanto, é seguro usá-lo como uma chave de documento do Azure AI Search. O exemplo a seguir mostra como mapear simultaneamente uma versão codificada Base64 segura para URL para metadata_storage_path um index_key campo e preservar o valor original em um metadata_storage_path campo:

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

Se você não incluir uma propriedade parameters para sua função de mapeamento, o padrão será o valor {"useHttpServerUtilityUrlTokenEncode" : true}.

O Azure AI Search suporta duas codificações Base64 diferentes. Você deve usar os mesmos parâmetros ao codificar e decodificar o mesmo campo. Para obter mais informações, consulte Opções de codificação base64 para decidir quais parâmetros usar.

função base64Decode

Executa a decodificação Base64 da cadeia de caracteres de entrada. Presume-se que a entrada seja uma cadeia de caracteres codificada em Base64 segura para URL.

Exemplo - decodificar metadados de blob ou URLs

Seus dados de origem podem conter cadeias de caracteres codificadas em Base64, como cadeias de caracteres de metadados de blob ou URLs da Web, que você deseja tornar pesquisáveis como texto sem formatação. Você pode usar a base64Decode função para transformar os dados codificados novamente em cadeias de caracteres regulares ao preencher seu índice de pesquisa.

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

Se você não incluir uma propriedade parameters, o padrão será o valor {"useHttpServerUtilityUrlTokenEncode" : true}.

Opções de codificação base64

O Azure AI Search suporta codificação base64 segura para URL e codificação base64 normal. Uma cadeia de caracteres codificada em base64 durante a indexação deve ser decodificada posteriormente com as mesmas opções de codificação, caso contrário, o resultado não corresponderá ao original.

Se os parâmetros ou useHttpServerUtilityUrlTokenDecode para codificação e decodificação, useHttpServerUtilityUrlTokenEncode respectivamente, estiverem definidos como true, então base64Encode se comportará como HttpServerUtility.UrlTokenEncode e base64Decode se comportará como HttpServerUtility.UrlTokenDecode.

Aviso

Se base64Encode for usado para produzir valores de chave, useHttpServerUtilityUrlTokenEncode deve ser definido como true. Somente a codificação base64 segura para URL pode ser usada para valores de chave. Consulte Regras de nomenclatura para obter o conjunto completo de restrições de caracteres em valores de chave.

As bibliotecas .NET no Azure AI Search assumem o .NET Framework completo, que fornece codificação interna. As useHttpServerUtilityUrlTokenEncode opções e useHttpServerUtilityUrlTokenDecode aplicam essa funcionalidade interna. Se você estiver usando o .NET Core ou outra estrutura, recomendamos definir essas opções e false chamar as funções de codificação e decodificação da sua estrutura diretamente.

A tabela a seguir compara diferentes codificações base64 da cadeia de caracteres 00>00?00. Para determinar o processamento necessário (se houver) para suas funções base64, aplique sua função de codificação de biblioteca na cadeia de caracteres 00>00?00 e compare a saída com a saída MDA-MDA_MDAesperada.

Codificação	Saída de codificação Base64	Processamento extra após a codificação da biblioteca	Processamento extra antes da decodificação da biblioteca
Base64 com preenchimento	`MDA+MDA/MDA=`	Usar caracteres seguros para URL e remover preenchimento	Use caracteres base64 padrão e adicione preenchimento
Base64 sem preenchimento	`MDA+MDA/MDA`	Usar caracteres seguros para URL	Usar caracteres base64 padrão
Base segura para URL64 com preenchimento	`MDA-MDA_MDA=`	Remover preenchimento	Adicionar preenchimento
Base segura para URL64 sem preenchimento	`MDA-MDA_MDA`	Nenhuma	Nenhuma

função extractTokenAtPosition

Divide um campo de cadeia de caracteres usando o delimitador especificado e seleciona o token na posição especificada na divisão resultante.

Esta função utiliza os seguintes parâmetros:

delimiter: uma string para usar como separador ao dividir a string de entrada.
position: uma posição baseada em zero inteiro do token a ser escolhido depois que a cadeia de caracteres de entrada for dividida.

Por exemplo, se a entrada é Jane Doe, o delimiter é " "(espaço) e o position é 0, o resultado é Jane; se o position é 1, o resultado é Doe. Se a posição se referir a um token que não existe, um erro será retornado.

Exemplo - extrair um nome

Sua fonte de dados contém um PersonName campo e você deseja indexá-lo como dois campos e LastName separadosFirstName. Você pode usar essa função para dividir a entrada usando o caractere de espaço como delimitador.

"fieldMappings" : [
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "FirstName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 0 } }
  },
  {
    "sourceFieldName" : "PersonName",
    "targetFieldName" : "LastName",
    "mappingFunction" : { "name" : "extractTokenAtPosition", "parameters" : { "delimiter" : " ", "position" : 1 } }
  }]

Função jsonArrayToStringCollection

Transforma uma cadeia de caracteres formatada como uma matriz JSON de cadeias de caracteres em uma matriz de cadeia de caracteres que pode ser usada para preencher um Collection(Edm.String) campo no índice.

Por exemplo, se a cadeia de caracteres de entrada for ["red", "white", "blue"], o campo de destino do tipo Collection(Edm.String) será preenchido com os três valores red, white, e blue. Para valores de entrada que não podem ser analisados como matrizes de cadeia de caracteres JSON, um erro é retornado.

Exemplo - preencher a coleta a partir de dados relacionais

O Banco de Dados SQL do Azure não tem um tipo de dados interno que mapeia naturalmente para Collection(Edm.String) campos no Azure AI Search. Para preencher campos de coleta de cadeia de caracteres, você pode pré-processar seus dados de origem como uma matriz de cadeia de caracteres JSON e, em seguida, usar a função de jsonArrayToStringCollection mapeamento.

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

Função urlEncode

Esta função pode ser usada para codificar uma cadeia de caracteres para que ela seja "URL segura". Quando usada com uma cadeia de caracteres que contém caracteres que não são permitidos em uma URL, essa função converterá esses caracteres "inseguros" em equivalentes de entidade de caractere. Esta função usa o formato de codificação UTF-8.

Exemplo - pesquisa de chave de documento

urlEncode função pode ser usada como uma alternativa para a base64Encode função, se apenas caracteres não seguros URL devem ser convertidos, mantendo outros caracteres como estão.

Digamos, a string de entrada é <hello> - então o campo de destino do tipo (Edm.String) será preenchido com o valor %3chello%3e

Ao recuperar a chave codificada no momento da pesquisa, você pode usar a urlDecode função para obter o valor da chave original e usá-lo para recuperar o documento de origem.

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

Função urlDecode

Esta função converte uma cadeia de caracteres codificada por URL em uma cadeia de caracteres decodificada usando o formato de codificação UTF-8.

Exemplo - decodificar metadados de blob

Alguns clientes de armazenamento do Azure codificam automaticamente metadados de blob de codificação de URL se contiverem caracteres não ASCII. No entanto, se você quiser tornar esses metadados pesquisáveis (como texto sem formatação), você pode usar a urlDecode função para transformar os dados codificados de volta em cadeias de caracteres regulares ao preencher seu índice de pesquisa.

"fieldMappings" : [
  {
    "sourceFieldName" : "UrlEncodedMetadata",
    "targetFieldName" : "SearchableMetadata",
    "mappingFunction" : {
      "name" : "urlDecode"
    }
  }
]

função fixedLengthEncode

Esta função converte uma cadeia de caracteres de qualquer comprimento em uma cadeia de comprimento fixo.

Exemplo - mapear chaves de documento que são muito longas

Quando ocorrem erros relacionados com o comprimento da chave do documento superior a 1024 caracteres, esta função pode ser aplicada para reduzir o comprimento da chave do documento.


"fieldMappings" : [
 {
   "sourceFieldName" : "metadata_storage_path",
   "targetFieldName" : "your key field",
   "mappingFunction" : {
     "name" : "fixedLengthEncode"
   }
 }
]

função toJson

Esta função converte uma cadeia de caracteres em um objeto JSON formatado. Isso pode ser usado para cenários em que a fonte de dados, como o Azure SQL, não oferece suporte nativo a tipos de dados compostos ou hierárquicos e, em seguida, mapeia-a para campos complexos.

Exemplo - mapear conteúdo de texto para um campo complexo

Suponha que haja uma linha SQL com uma cadeia de caracteres JSON que precisa ser mapeada para um campo complexo (correspondentemente definido) no índice, a toJson função pode ser usada para conseguir isso. Por exemplo, se um campo complexo no índice precisar ser preenchido com os seguintes dados:

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

Isso pode ser feito usando a toJson função de mapeamento em uma coluna de cadeia de caracteres JSON em uma linha SQL que se parece com isto: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

O mapeamento de campo precisa ser especificado como mostrado abaixo.


"fieldMappings" : [
  {
    "sourceFieldName" : "content",
    "targetFieldName" : "complexField",
    "mappingFunction" : {
      "name" : "toJson"
    }
  }
]