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

  • Artigo

Indexer Stages

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ísicos em ambos os lados do fluxo de dados (entre campos em uma fonte de dados com suporte e campos em um índice de pesquisa). Se você estiver importando conteúdo enriquecido por 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.

  • Pesquisar apenas índices. Se você estiver preenchendo um repositório de conhecimento, use projeções para a configuração do caminho de dados.

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

Observação

Se você estiver trabalhando com dados complexos (estruturas aninhadas ou hierárquicas) e quiser espelhar essa estrutura de dados no índice de pesquisa, o í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, 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).

Cenários com suporte

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

Definir um mapeamento de campo

Mapeamentos de campos são adicionados à matriz fieldMappings de uma definição de indexador. 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.

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. A solução alternativa é criar um esquema de índice idêntico ao conteúdo bruto para nomes de campo e tipos de dados. Consulte Tutorial: Indexar blobs JSON aninhados para obter um exemplo.

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.

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 chave de índice.

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

Use Criar indexador (REST) ou Atualizar indexador (REST) para qualquer versão da API.

Este exemplo manipula 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" }
]

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:

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=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. 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=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 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}.

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.

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 os campos da coleção de cadeia de caracteres, preprocesse os dados de origem como uma matriz de cadeia de caracteres JSON e use 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"
    }
  }
]

Confira também