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

Artigo
09/03/2024

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

Quando definir um mapeamento de campo

Quando um indexador da Pesquisa de IA do Azure carrega um índice de pesquisa, ele determina o caminho de dados por meio de 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 de saída se aplicam a:

Estruturas de dados físicas em ambos os lados do caminho de dados. As estruturas de dados lógicos criadas por habilidades residem somente 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 que atuam como elemento pai. Para índices "secundários" com documentos "filho" ou "partes", confira os cenários avançados de mapeamento de campo.
Somente campos de pesquisa de nível superior, em que o targetFieldName é um campo simples ou uma coleção. Um campo de destino não pode ser um tipo complexo.

Cenários com suporte

Certifique-se de estar usando uma fonte de dados com suporte para indexação controlada por indexador.

Caso de uso	Descrição
Discrepância de nome	Suponha que sua fonte de dados tenha um campo chamado `_city`. Considerando que o Azure AI Search não permite nomes de campo que começam com um sublinhado, um mapeamento de campo permite renomear um mapa de nome "_city" para "city". Se seus requisitos de indexação incluem a recuperação de conteúdo de várias fontes de dados, em que os nomes de campo variam entre as fontes, você pode 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 ele seja pesquisável no índice de pesquisa. Como os tipos são diferentes, você precisará definir um mapeamento de campo para que o caminho de dados tenha êxito. Observe que o Azure AI Search tem um conjunto menor de tipos de dados com suporte do que muitas fontes de dados. Se estiver importando dados SQL, um mapeamento de campo permitirá mapear o tipo de dados SQL desejado em um índice de pesquisa.
Caminhos de dados de 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 decodificaçã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 enviar uma matriz JSON para um campo de pesquisa do tipo `Collection(Edm.String)`.

Observação

Se nenhum mapeamento de campo estiver presente, os indexadores presumem que os campos de fonte de dados devem ser mapeados para campos de índice com o mesmo nome. Adicionar um mapeamento de campo substitui esses mapeamentos de campo padrão para o campo de origem e de destino. Alguns indexadores, como o indexador de armazenamento de blobs, adicionam mapeamentos de campo padrão para o campo de chave do í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 mais informações, consulte Tutorial: Indexar blobs JSON aninhados para um exemplo. Se você receber um erro semelhante a "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, talvez você queira apenas alguns nós na estrutura complexa. Para obter nós individuais, você pode nivelar os dados de entrada em uma coleção de cadeias de caracteres (consulte outputFieldMappings para ver essa solução alternativa).

Definir um mapeamento de campo

Esta seção explica as etapas de configuração dos mapeamentos de campo.

APIs REST
SDK do .NET (C#)

Use Criar Indexador ou Criar ou Atualizar Indexador ou um método equivalente em um SDK do Azure. Veja a seguir um exemplo de definição de indexador.

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

Preencha a matriz fieldMappings para especificar os mapeamentos. Um mapeamento de campo é composto por três partes.

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

Propriedade	Descrição
sourceFieldName	Obrigatório. Representa um campo na fonte de dados.
targetFieldName	Opcional. Representa um campo em seu índice de pesquisa. Se omitido, o valor de `sourceFieldName` será assumido para o destino. Os campos de destino devem ser campos ou coleções simples de nível superior. Não pode ser um tipo complexo ou uma coleção. Se você estiver tratando 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.
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 o nome e o tipo não são idênticos.

O Azure AI Search usa a comparação que não diferencia maiúsculas de minúsculas para resolver os nomes de campo e a função em mapeamentos de campo. Isso é conveniente (você não precisa obter todas as maiúsculas e minúsculas corretas), mas isso significa que a fonte de dados ou o índice não pode ter campos que diferem somente 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 de um para muitos ou bifurcado

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 o conteúdo gerado por habilidades.

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

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

Exemplos e funções de mapeamento de campo

Uma função de mapeamento de campos transforma o conteúdo de um campo antes que ele seja armazenado no índice. Atualmente, há suporte para as seguintes funções de mapeamento:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Observe que essas funções são suportadas exclusivamente para índices pais 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 codificação Base64 de URL segura da cadeia de caracteres de entrada. Pressupõe-se que a entrada é codificada para UTF-8.

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

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

O exemplo a seguir especifica a função base64Encode em metadata_storage_name para lidar com 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. Ao recuperar a chave codificada no momento da pesquisa, use a função para obter o valor da chave original e base64Decode use-a 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 como 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 (codificado) e um segundo para um campo de caminho que podemos supor ser 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 metadata_storage_path, o URI do blob, ao campo chave de índice se nenhum mapeamento de campo 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 com base em Base64 de URL segura de metadata_storage_path para um campo index_key e preservar o valor original em um campo metadata_storage_path:

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

Se não for incluída uma propriedade de parâmetros na função de mapeamento, seu valor padrão será {"useHttpServerUtilityUrlTokenEncode" : true}.

O Azure AI Search dá suporte a duas codificações Base64 diferentes. Devem ser usados 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 de Base64 da cadeia de caracteres de entrada. A entrada é considerada uma cadeia de caracteres de codificação Base64 de URL segura.

Exemplo – decodificar metadados ou URLs de blobs

Os dados de origem podem conter cadeias de caracteres codificadas em Base64, como cadeias de caracteres de metadados de blobs ou URLs da Web, que se deseja tornar pesquisáveis como texto sem formatação. No entanto, para que a pesquisa seja significativa, é possível usar essa base64Decode função para transformar os dados codificados novamente em cadeias de caracteres "normais" ao popular o índice de pesquisa.

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

Se não for incluída uma propriedade Parâmetros, o valor padrão será {"useHttpServerUtilityUrlTokenEncode" : true}.

Opções de codificação Base64

O Azure AI Search dá suporte à codificação Base64 de URL segura 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 useHttpServerUtilityUrlTokenEncode ou useHttpServerUtilityUrlTokenDecode de codificação e decodificação forem respectivamente definidos como true, então base64Encode se comportará como HttpServerUtility.UrlTokenEncode, e base64Decode, como HttpServerUtility.UrlTokenDecode.

Aviso

Se base64Encode for usado para produzir valores de chave, useHttpServerUtilityUrlTokenEncode deverá ser definido como true. Somente a codificação Base64 para URL segura pode ser usada para valores de chave. Consulte Regras de nomenclatura (Azure Cognitive Search) para obter o conjunto completo de restrições em caracteres em valores de chave.

As bibliotecas do .NET no Azure AI Search assumem o .NET Framework completo, que fornece codificação interna. As opções useHttpServerUtilityUrlTokenEncode e useHttpServerUtilityUrlTokenDecode aproveitam essa funcionalidade interna. Se usar o .NET Core ou outra estrutura, é recomendável definir essas opções como false e chamar as funções de codificação e decodificação da estrutura diretamente.

A tabela a seguir compara codificações diferentes de base64 da cadeia de caracteres 00>00?00. Para determinar o processamento necessário (se houver) para suas funções de 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 esperada MDA-MDA_MDA.

Codificação	Saída de codificação Base64	Processamento adicional após a codificação da biblioteca	Processamento adicional antes da decodificação da biblioteca
Base64 com preenchimento	`MDA+MDA/MDA=`	Use caracteres com URL segura e remova o preenchimento	Use caracteres base64 padrão e adicione o preenchimento
Base64 sem preenchimento	`MDA+MDA/MDA`	Use caracteres com URL segura	Use caracteres base64 padrão
Base64 com preenchimento e URL segura	`MDA-MDA_MDA=`	Remover preenchimento	Adicionar preenchimento
Base64 sem preenchimento e URL segura	`MDA-MDA_MDA`	Nenhum	Nenhum

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.

Essa função usa os seguintes parâmetros:

delimiter: uma cadeia de caracteres a ser usado como o separador ao dividir a cadeia de caracteres de entrada.
position: uma posição baseada em zero do número inteiro do token para escolher depois que a cadeia de caracteres de entrada for dividida.

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

Exemplo – extrair um nome

Sua fonte de dados contém um campo PersonName e você deseja indexá-la como dois campos FirstName e LastName separados. Você pode usar essa função para dividir a entrada usando o caractere de espaço como o 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 campo Collection(Edm.String) 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 retornará.

Exemplo – preencher a coleção de dados relacionais

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

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

Função urlEncode

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

Exemplo – pesquisa de chave de documento

A função urlEncode pode ser usada como uma alternativa à função base64Encode, se apenas caracteres não seguros de URL forem convertidos, mantendo outros caracteres como estão.

Por exemplo, se a cadeia de caracteres de entrada for <hello> – o campo de destino do tipo (Edm.String) será preenchido com o valor %3chello%3e

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

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

Função urlDecode

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

Exemplo – decodificar metadados de blobs

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

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

Função fixedLengthEncode

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

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

Quando ocorrem erros relacionados ao comprimento da chave do documento que excede 1024 caracteres, essa 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

Essa 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 SQL do Azure, não dá suporte nativo a tipos de dados compostos ou hierárquicos e, em seguida, mapeia-os 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 função toJson 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 alcançado usando a função de mapeamento toJson em uma coluna de cadeia de caracteres JSON em uma linha SQL semelhante a esta: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

O mapeamento de campo precisa ser especificado, conforme mostrado abaixo.


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

Cenários avançados de mapeamento de campo

Quando você tem relações de documentos "um-para-muitos", como fragmentação ou separação de dados, siga estas dicas para mapear campos a partir de documentos "pai" para documentos "filhos" (partes):

1. Ignorar a indexação de documentos "pai"

Se você pular a indexação de documentos "pai" (definindo projectionMode como skipIndexingParentDocuments no indexProjections do conjunto de habilidades), use as projeções de índice para mapear campos de documentos "pai" para documentos "filhos".

2. Indexar documentos "pai" e "filhos"

Se você está indexando tanto documentos "pai" quanto documentos "filhos":

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

3. Mapear valores transformados por função dos documentos "pai" e/ou "filhos"

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

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

Compartilhar via