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

Artigo
09/01/2024

Este artigo explica como definir mapeamentos de campo explícitos que estabelecem o caminho de dados entre campos de origem em uma fonte de dados suportada e campos de destino em um índice de pesquisa.

Quando definir um mapeamento de campo

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 caminho de dados. As estruturas de dados lógicas criadas pelas habilidades residem apenas na memória. Use outputFieldMappings para mapear nós na memória para campos de saída em um índice de pesquisa.
Somente índices de pesquisa de IA pai. Para índices "secundários" com documentos "filho" ou "partes", consulte os cenários avançados de mapeamento de campo.
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.

Cenários suportados

Certifique-se de que está a utilizar uma fonte de dados suportada para indexação de condução de indexação.

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)`.

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 automaticamente.

Não há suporte para campos complexos em um mapeamento de campo. Sua estrutura de origem (estruturas aninhadas ou hierárquicas) deve corresponder exatamente ao tipo complexo no índice para que os mapeamentos padrão funcionem. Para obter mais informações, consulte Tutorial: Indexar blobs JSON aninhados para obter um exemplo. 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.

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

Definir um mapeamento de campo

Esta seção explica as etapas para configurar mapeamentos de campo.

APIs REST
SDK .NET (C#)

Use Criar Indexador ou Criar ou Atualizar Indexador ou um método equivalente em um SDK do Azure. Aqui está um exemplo de uma definição de indexador.

{
   "name": "myindexer",
   "description": null,
   "dataSourceName": "mydatasource",
   "targetIndexName": "myindex",
   "schedule": { },
   "parameters": { },
   "fieldMappings": [],
   "disabled": false,
   "encryptionKey": { }
 }

Preencha a fieldMappings matriz para especificar os mapeamentos. 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.

Exemplo: discrepância de nome ou tipo

Um mapeamento de campo explícito estabelece um caminho de dados para casos em que nome e tipo não são idênticos.

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.

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

Exemplo: Caminhos de dados um-para-muitos ou bifurcados

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

Você pode usar uma abordagem semelhante para conteúdo gerado por habilidades.

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

Observe que essas funções são suportadas exclusivamente para índices pai no momento. Eles não são compatíveis com o mapeamento de índice em partes, portanto, essas funções não podem ser usadas para projeções de índice.

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=2024-07-01
{
  "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=2024-07-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" }
      ]
}

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 jsonArrayToStringCollection função de 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"
    }
  }
]

Cenários avançados de mapeamento de campo

Em cenários em que você tem relações de documento "um-para-muitos", como fragmentação ou divisão de dados, siga estas diretrizes para mapear campos de documentos pai para documentos "filho" (blocos):

1. Ignorando a indexação de documentos pai

Se você estiver ignorando a indexação de documentos pai (definindo projectionMode como skipIndexingParentDocuments no conjunto de indexProjectionshabilidades), use projeções de índice para mapear campos dos documentos pai para os documentos "filho".

2. Indexação de documentos pai e "filho"

Se você estiver indexando documentos pai e documentos "filho":

Use mapeamentos de campo para mapear campos para os documentos pai.
Use projeções de índice para mapear campos para os documentos "filho".

3. Mapeando valores transformados por função para documentos pai e/ou "filho"

Se um campo no documento pai exigir uma transformação (usando as funções de mapeamento, como codificação) e precisar ser mapeado para os documentos pai e/ou "filho":

Aplique a transformação usando funções de mapeamentos de campo no indexador.
Use projeções de índice no conjunto de habilidades para mapear o campo transformado para os documentos "filho".

Partilhar via