Mapeamentos de campos e transformações com indexadores de Azure Cognitive Search

Artigo
06/01/2023

Quando um indexador de Azure Cognitive Search carrega um índice de pesquisa, determina o caminho dos dados através dos mapeamentos de campos 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, pode definir mapeamentos de campo explícitos para configurar o caminho de dados, conforme descrito neste artigo. Os mapeamentos de campos também podem ser utilizados para introduzir uma conversão de dados leve, como codificação ou descodificação, através de funções de mapeamento. Se for necessário mais processamento, considere Azure Data Factory para colmatar a lacuna.

Os mapeamentos de campos aplicam-se a:

Estruturas de dados físicas em ambos os lados do fluxo de dados (entre uma origem de dados suportada e um índice de pesquisa). Se estiver a importar conteúdos enriquecidos com competências que residem na memória, utilize outputFieldMappings como alternativa.
Procurar apenas índices. Se estiver a preencher um arquivo de conhecimento, utilize projeções para a configuração do caminho de dados.
Apenas campos de pesquisa de nível superior, em que "targetFieldName" é um campo simples ou uma coleção. Um campo de destino não pode ser um tipo complexo.

Nota

Se estiver a trabalhar com dados complexos (estruturas aninhadas ou hierárquicas) e quiser espelhar essa estrutura de dados no índice de pesquisa, o índice de pesquisa tem de corresponder exatamente à estrutura de origem (os mesmos nomes de campo, níveis e tipos) para que os mapeamentos predefinidos funcionem. Opcionalmente, poderá querer apenas alguns nós na estrutura complexa. Para obter nós individuais, pode aplanar os dados recebidos numa coleção de cadeias (veja outputFieldMappings para esta solução).

Cenários suportados

Caso de utilização	Descrição
Discrepância de nomes	Suponha que a origem de dados tem um campo com o nome `_city`. Dado que Azure Cognitive Search não permite nomes de campos que começam com um caráter de sublinhado, um mapeamento de campos permite mapear efetivamente "_city" para "cidade". Se os requisitos de indexação incluírem a obtenção de conteúdo de várias origens de dados, em que os nomes dos campos variam entre as origens, pode utilizar um mapeamento de campos para clarificar o caminho.
Discrepância de tipos	Supostamente, pretende que um campo inteiro de origem seja do tipo `Edm.String` para que seja pesquisável no índice de pesquisa. Uma vez que os tipos são diferentes, terá de definir um mapeamento de campos para que o caminho de dados seja bem-sucedido. Tenha em atenção que o Cognitive Search tem um conjunto menor de tipos de dados suportados do que muitas origens de dados. Se estiver a importar dados SQL, um mapeamento de campos permite-lhe mapear o tipo de dados SQL que pretende num índice de pesquisa.
Caminhos de dados um-para-muitos	Pode preencher vários campos no índice com conteúdo do mesmo campo de origem. Por exemplo, poderá querer aplicar diferentes analisadores a cada campo para suportar diferentes casos de utilização na sua aplicação cliente.
Codificação e descodificação	Pode aplicar funções de mapeamento para suportar a codificação base64 ou a descodificação de dados durante a indexação.
Dividir cadeias ou reformular matrizes em coleções	Pode aplicar funções de mapeamento para dividir uma cadeia que inclui um delimitador ou para enviar uma matriz JSON para um campo de pesquisa do tipo `Collection(Edm.String)`.

Definir um mapeamento de campos

Os mapeamentos de campos são adicionados à matriz "fieldMappings" de uma definição de indexador. Um mapeamento de campos consiste em três partes.

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

Propriedade	Descrição
sourceFieldName	Obrigatório. Representa um campo na sua origem de dados.
targetFieldName	Opcional. Representa um campo no índice de pesquisa. Se for omitido, é assumido o valor de "sourceFieldName" para o destino. Os campos de destino têm de ser campos ou coleções simples de nível superior. Não pode ser um tipo ou coleção complexo. Se estiver a lidar com um problema de tipo de dados, o tipo de dados de um campo é especificado na definição do índice. O mapeamento de campos só precisa de ter o nome do campo.
mappingFunction	Opcional. Consiste em funções predefinidas que transformam dados.

Azure Cognitive Search utiliza comparação não sensível a maiúsculas e minúsculas para resolver os nomes dos campos e das funções nos mapeamentos de campos. Isto é conveniente (não tem de acertar todas as maiúsculas/minúsculas), mas significa que a sua origem de dados ou índice não pode ter campos que diferem apenas por maiúsculas e minúsculas.

Nota

Se não existirem mapeamentos de campos, os indexadores assumem que os campos de origem de dados devem ser mapeados para campos de índice com o mesmo nome. Adicionar um mapeamento de campo substitui os mapeamentos de campo predefinidos para o campo de origem e de destino. Alguns indexadores, como o indexador de armazenamento de blobs, adicionam mapeamentos de campos predefinidos para o campo de chave de índice.

Pode utilizar a API REST ou um SDK do Azure para definir mapeamentos de campos.

REST APIs
SDK .NET (C#)

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

Este exemplo processa 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"). Pode "bifurcar" um campo ao copiar 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, utilize a classe FieldMapping que fornece as propriedades "SourceFieldName" e "TargetFieldName" e uma referência opcional "MappingFunction".

Especifique os mapeamentos de campos ao construir o indexador ou posterior ao definir diretamente SearchIndexer.FieldMappings. O exemplo C# seguinte define os mapeamentos de campos 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);

Funções e exemplos de mapeamento

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

base64Encode
códigodede base64
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Função base64Encode

Executa a codificação Base64 segura para URL da cadeia de entrada. Parte do princípio de que a entrada tem codificação UTF-8.

Exemplo: codificar base uma chave de documento

Apenas os carateres seguros de URL podem aparecer numa chave de documento Azure Cognitive Search (para que possa abordar o documento com a API de Pesquisa). Se o campo de origem da sua chave contiver carateres não seguros de URL, como - e \, utilize a base64Encode função para convertê-lo no momento da indexação.

O exemplo seguinte especifica a função base64Encode em "metadata_storage_name" para processar carateres não suportados.

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 1024 carateres. Quando obter a chave codificada no momento da pesquisa, utilize a base64Decode função para obter o valor da chave original e utilize-a para obter o documento de origem.

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

Por vezes, é necessário utilizar 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 a pesquisa em texto completo. Para suportar ambos os cenários, pode mapear "metadata_storage_path" para dois campos: um para a chave (codificado) e um segundo para um campo de caminho que podemos assumir que é atribuído como "pesquisável" 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 os valores originais

O indexador de armazenamento de blobs adiciona automaticamente um mapeamento de campo do metadata_storage_path, o URI do blob, ao campo da chave de índice se não for especificado nenhum mapeamento de campos. Este valor é codificado com Base64, pelo que é seguro utilizá-lo como uma chave de documento Azure Cognitive Search. O exemplo seguinte mostra como mapear simultaneamente uma versão codificada de Base64 segura para URL de metadata_storage_path para um index_key campo e preservar o valor original num metadata_storage_path campo:

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

Se não incluir uma propriedade de parâmetros para a função de mapeamento, a predefinição é o valor {"useHttpServerUtilityUrlTokenEncode" : true}.

Azure Cognitive Search suporta duas codificações Base64 diferentes. Deve utilizar os mesmos parâmetros ao codificar e descodificar o mesmo campo. Para obter mais informações, veja opções de codificação base64 para decidir quais os parâmetros a utilizar.

Função base64Decode

Efetua a descodificação Base64 da cadeia de entrada. Presume-se que a entrada é uma cadeia codificada por Base64 segura para URL .

Exemplo – descodificar metadados ou URLs de blobs

Os dados de origem podem conter cadeias codificadas em Base64, como cadeias de metadados de blobs ou URLs Web, que pretende tornar pesquisáveis como texto simples. Pode utilizar a base64Decode função para transformar os dados codificados novamente em cadeias regulares ao preencher o índice de pesquisa.

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

Se não incluir uma propriedade de parâmetros, a predefinição é o valor {"useHttpServerUtilityUrlTokenEncode" : true}.

opções de codificação base64

Azure Cognitive Search suporta codificação base64 segura para URL e codificação base64 normal. Uma cadeia codificada em base64 durante a indexação deve ser descodificada posteriormente com as mesmas opções de codificação ou o resultado não corresponderá ao original.

Se os useHttpServerUtilityUrlTokenEncode parâmetros ou useHttpServerUtilityUrlTokenDecode para codificação e descodificação estiverem definidos truecomo , base64Encode então comporta-se como HttpServerUtility.UrlTokenEncode e base64Decode comporta-se como HttpServerUtility.UrlTokenDecode.

Aviso

Se base64Encode for utilizado para produzir valores chave, useHttpServerUtilityUrlTokenEncode tem de ser definido como verdadeiro. Apenas a codificação base64 segura para URL pode ser utilizada para valores de chave. Veja Regras de nomenclatura para obter o conjunto completo de restrições de carateres em valores chave.

As bibliotecas .NET no Azure Cognitive Search assumem a .NET Framework completa, que fornece codificação incorporada. As useHttpServerUtilityUrlTokenEncode opções e useHttpServerUtilityUrlTokenDecode aplicam esta funcionalidade incorporada. Se estiver a utilizar o .NET Core ou outra arquitetura, recomendamos que defina essas opções para false e chame diretamente as funções de codificação e descodificação da arquitetura.

A tabela seguinte compara diferentes codificações base64 da cadeia 00>00?00. Para determinar o processamento necessário (se existir) para as funções base64, aplique a função de codificação da biblioteca na cadeia 00>00?00 e compare o resultado com o resultado MDA-MDA_MDAesperado.

Encoding	Resultado de codificação Base64	Processamento extra após a codificação da biblioteca	Processamento adicional antes da descodificação da biblioteca
Base64 com preenchimento	`MDA+MDA/MDA=`	Utilizar carateres seguros de URL e remover preenchimento	Utilizar carateres base64 padrão e adicionar preenchimento
Base64 sem preenchimento	`MDA+MDA/MDA`	Utilizar carateres seguros de URL	Utilizar carateres base64 padrão
Base64 seguro de URL com preenchimento	`MDA-MDA_MDA=`	Remover preenchimento	Adicionar preenchimento
Base64 segura para URLs sem preenchimento	`MDA-MDA_MDA`	Nenhuma	Nenhuma

função extractTokenAtPosition

Divide um campo de cadeia com o delimitador especificado e escolhe o token na posição especificada na divisão resultante.

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

delimiter: uma cadeia a utilizar como separador ao dividir a cadeia de entrada.
position: uma posição baseada em zero de número inteiro do token a escolher após a divisão da cadeia de entrada.

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

Exemplo - extrair um nome

A origem de dados contém um PersonName campo e pretende indexá-lo como dois campos e LastName separadosFirstName. Pode utilizar esta função para dividir a entrada com o caráter 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 formatada como uma matriz JSON de cadeias numa matriz de cadeia que pode ser utilizada para preencher um Collection(Edm.String) campo no índice.

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

Exemplo – preencher a recolha a partir de dados relacionais

SQL do Azure Base de Dados não tem um tipo de dados incorporado que mapeia naturalmente para Collection(Edm.String) campos no Azure Cognitive Search. Para preencher campos de coleção de cadeias, pode pré-processar os dados de origem como uma matriz de cadeiaS JSON e, em seguida, utilizar a jsonArrayToStringCollection função de mapeamento.

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

função urlEncode

Esta função pode ser utilizada para codificar uma cadeia de carateres para que seja "SEGURO para URLs". Quando utilizada com uma cadeia que contém carateres que não são permitidos num URL, esta função irá converter esses carateres "não seguros" em equivalentes de entidade-caráter. Esta função utiliza o formato de codificação UTF-8.

Exemplo - pesquisa da chave do documento

urlEncode A função pode ser utilizada como alternativa à base64Encode função, se apenas os carateres não seguros de URL forem convertidos, mantendo outros carateres tal como estão.

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

Quando obtém a chave codificada no momento da pesquisa, pode utilizar a urlDecode função para obter o valor da chave original e utilizá-la para obter o documento de origem.

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

função urlDecode

Esta função converte uma cadeia codificada por URL numa cadeia de carateres descodificada com o formato de codificação UTF-8.

Exemplo – descodificar metadados de blobs

Alguns clientes de armazenamento do Azure codificam automaticamente metadados de blobs de codificação de URL se contiverem carateres não ASCII. No entanto, se quiser tornar esses metadados pesquisáveis (como texto simples), pode utilizar a urlDecode função para transformar os dados codificados novamente em cadeias normais ao preencher o índice de pesquisa.

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

função fixedLengthEncode

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

Exemplo – mapear chaves de documento demasiado longas

Quando ocorrem erros relacionados com o comprimento da chave do documento superior a 1024 carateres, 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"
   }
 }]