Transformar y asignar campos mediante indexadores de Azure AI Search

Artículo
09/03/2024

En este artículo se explica cómo definir asignaciones de campos explícitas que establecen la ruta de acceso a datos entre los campos de origen de un origen de datos admitido y los campos de destino de un índice de búsqueda.

Cuándo definir una asignación de campos

Cuando un indizador de Búsqueda de Azure AI carga un índice de búsqueda, determina la ruta de acceso de datos mediante asignaciones de campos de origen a destino. Las asignaciones de campos implícitas son internas y se producen cuando los nombres de campo y los tipos de datos son compatibles entre el origen y el destino. Si las entradas y salidas no coinciden, puede definir asignaciones de campos explícitas para configurar la ruta de acceso de datos, tal como se describe en este artículo.

Las asignaciones de campos también se pueden usar para conversiones de datos ligeras, como codificación o descodificación, mediante funciones de asignación. Si se requiere más procesamiento, considere usar Azure Data Factory para salvar la brecha.

Las asignaciones de campos se aplican a:

Estructuras de datos físicas en ambos lados de la ruta de acceso a datos. Las estructuras de datos lógicas creadas mediante capacidades solo residen en la memoria. Use outputFieldMappings para asignar nodos en memoria para generar campos en un índice de búsqueda.
Solo índices primarios de AI Search. Para los índices "secundarios" con documentos "secundarios" o "fragmentos", consulte los escenarios de asignación de campos avanzados.
Solo campos de búsqueda de nivel superior, donde targetFieldName es un campo simple o una colección. Un campo de destino no puede ser un tipo complejo.

Escenarios admitidos

Asegúrese de que usa un origen de datos compatible para la indexación basada en el indexador.

Caso de uso	Descripción
Discrepancia de nombres	Supongamos que el origen de datos tiene un campo denominado `_city`. Dado que Azure AI Search no permite nombres de campo que empiecen por un carácter de subrayado, una asignación de campos permite asignar "_city" a "city" de forma efectiva. Si los requisitos de indexación incluyen recuperar contenido de varios orígenes de datos, donde los nombres de campo varían entre los orígenes, puede usar una asignación de campos para aclarar la ruta de acceso.
Discrepancia de tipos	Suponga que quiere que un campo entero de origen sea de tipo `Edm.String` para que se pueda buscar en el índice de búsqueda. Dado que los tipos son diferentes, deberá definir una asignación de campos para que la ruta de acceso de datos se realice correctamente. Ten en cuenta que Azure AI Search tiene un conjunto más pequeño de tipos de datos admitidos que muchos orígenes de datos. Si va a importar datos de SQL, una asignación de campos le permite asignar el tipo de datos de SQL que quiera en un índice de búsqueda.
Rutas de acceso de datos de tipo "uno a varios.	Puede rellenar varios campos en el índice con contenido del mismo campo de origen. Por ejemplo, es posible que quiera aplicar distintos analizadores a cada campo para admitir diferentes casos de uso en la aplicación de cliente.
Codificar y descodificar	Puede aplicar funciones de asignación para admitir la codificación o descodificación de datos en Base64 durante la indexación.
División de cadenas o redifusión de matrices en colecciones	Puede aplicar funciones de asignación para dividir una cadena que incluya un delimitador o para enviar una matriz JSON a un campo de búsqueda de tipo `Collection(Edm.String)`.

Nota:

Si no hay asignaciones de campo presentes, los indexadores asumen que los campos de origen de datos se deben asignar a campos de índice con el mismo nombre. Al agregar una asignación de campos, se invalidan las asignaciones de campos predeterminadas para el campo de origen y de destino. Algunos indexadores, como el indexador de Blob Storage, agregan asignaciones de campos predeterminadas para el campo de clave de índice automáticamente.

Los campos complejos no se admiten en una asignación de campos. La estructura de origen (estructuras anidadas o jerárquicas) debe coincidir exactamente con el tipo complejo del índice para que funcionen las asignaciones predeterminadas. Para más información, consulte Tutorial: Indexación de blobs JSON anidados para ver un ejemplo. Si recibe un error similar a "Field mapping specifies target field 'Address/city' that doesn't exist in the index", se debe a que las asignaciones de campos de destino no pueden ser un tipo complejo.

Opcionalmente, puede que desee solo unos pocos nodos en la estructura compleja. Para obtener nodos individuales, puede acoplar los datos entrantes en una colección de cadenas (consulte outputFieldMappings para esta solución alternativa).

Definición de una asignación de campos

En esta sección se explican los pasos para configurar asignaciones de campos.

API de REST
SDK de .NET (C#)

Use Crear índice o Crear o actualizar indexador o un método equivalente de un SDK de Azure. Este es un ejemplo de una definición de indexador.

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

Rellene la matriz fieldMappings para especificar las asignaciones. Una asignación de campos consta de tres partes.

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

Propiedad	Descripción
sourceFieldName	Necesario. Representa un campo de su origen de datos.
targetFieldName	Opcional. Representa un campo de su índice de búsqueda. Si se omite, se asume el valor de `sourceFieldName` para el destino. Los campos de destino deben ser campos o colecciones simples de nivel superior. No puede ser un tipo complejo ni una colección. Si está controlando un problema de tipo de datos, el tipo de datos de un campo se especifica en la definición del índice. La asignación de campos solo debe tener el nombre del campo.
mappingFunction	Opcional. Consta de funciones predefinidas que transforman datos.

Ejemplo: Discrepancia en el nombre o el tipo

Una asignación de campos explícita establece una ruta de acceso a datos para los casos en los que el nombre y el tipo no son idénticos.

Azure AI Search usa una comparación que no distingue mayúsculas de minúsculas para resolver los nombres de campo y función de las asignaciones de campos. Esto puede serle útil (no es necesario que el uso de mayúsculas y minúsculas sea correcto en todo momento), pero tenga en cuenta que su índice u origen de datos no puede tener campos que difieran únicamente en mayúsculas y 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" } ]
}

Ejemplo: Rutas de acceso a datos de uno a varios o bifurcadas

En este ejemplo se asigna un único campo de origen a varios campos de destino (asignaciones de uno a varios). Puede "bifurcar" un campo, copiando el mismo contenido de campo de origen en dos campos de índice diferentes que se analizarán o atribuirán de forma diferente en el índice.


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

Puede usar un enfoque similar para el contenido generado por capacidades.

En el SDK de Azure para .NET, use la clase FieldMapping que proporciona propiedades SourceFieldName y TargetFieldName y una referencia opcional MappingFunction.

Puede especificar asignaciones de campos al crear el indexador, o bien puede establecer SearchIndexer.FieldMappings directamente para especificarlas más adelante. En el siguiente ejemplo de C# se establecen las asignaciones de campo al crear un 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);

Funciones y ejemplos de asignación

Una función de asignación de campo transforma el contenido de un campo antes de almacenarlo en el índice. Actualmente, se admiten las siguientes funciones de asignación:

base64Encode
base64Decode
extractTokenAtPosition
jsonArrayToStringCollection
urlEncode
urlDecode

Tenga en cuenta que estas funciones se admiten exclusivamente para los índices primarios en este momento. No son compatibles con la asignación de índices fragmentados, por lo que estas funciones no se pueden usar para proyecciones de índice.

Función base64Encode

Realiza una codificación Base64 segura para direcciones URL de la cadena de entrada. Asume que la entrada presenta una codificación UTF-8.

Ejemplo: codificación Base de una clave de documento

Solo pueden aparecer caracteres seguros para direcciones URL en una clave de documento de Azure AI Search (para que se pueda abordar el documento con la API de búsqueda). Si el campo de origen de la clave contiene caracteres URL no seguros, como - y \, puede usar la función base64Encode para convertirlo en el momento de la indexación.

En el ejemplo siguiente se especifica la función base64Encode en metadata_storage_name para controlar los caracteres no admitidos.

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

Una clave de documento (tanto antes como después de la conversión) no puede tener más de 1024 caracteres. Al recuperar la clave codificada en el tiempo de búsqueda, use la función base64Decode para obtener el valor de clave original y usarlo para recuperar el documento de origen.

Ejemplo: hacer que un campo codificado en Base sea "buscable"

Hay ocasiones en las que es necesario usar una versión codificada de un campo como metadata_storage_path como clave, pero también se necesita una versión sin codificar para la búsqueda de texto completo. Para admitir ambos escenarios, puede asignar metadata_storage_path a dos campos; uno para la clave (codificado) y otro para un campo de ruta de acceso, que cabe suponer que se atribuirá como searchable en el 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" }
      ]
}

Ejemplo: conservación de los valores originales

El indizador de Blob Storage agrega automáticamente una asignación de campos de metadata_storage_path, el URI del blob, al campo clave del índice si no se especifica ninguna asignación de campos. Este valor está codificado en Base64, por lo que es seguro usarlo como una clave de documento de Azure AI Search. En el ejemplo siguiente, se muestra cómo asignar simultáneamente una versión codificada en Base64 con seguridad de direcciones URL de un campo metadata_storage_path a index_key y conservar el valor original en un campo metadata_storage_path:

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

Si no incluye una propiedad de parámetros de la función de asignación, el valor {"useHttpServerUtilityUrlTokenEncode" : true} se establece como valor predeterminado.

Azure AI Search admite dos codificaciones Base64 distintas. Debe usar los mismos parámetros al codificar y descodificar el mismo campo. Para más información, vea Opciones de codificación Base64 para decidir qué parámetros usar.

Función Base64Decode

Realiza una descodificación Base64 de la cadena de entrada. Se da por hecho que la entrada es una cadena con codificación Base64 segura para direcciones URL.

Ejemplo: descodificar direcciones URL o metadatos de blob

El origen de datos podría contener cadenas con codificación Base64, como cadenas de metadatos de blob o direcciones URL web, que quiera incluir en búsquedas como texto sin formato. Puede usar la función base64Decode para volver a convertir los datos codificados en cadenas normales al rellenar el índice de búsqueda.

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

Si no incluye una propiedad de parámetros, el valor {"useHttpServerUtilityUrlTokenEncode" : true} se establece como valor predeterminado.

Opciones de codificación Base64

Azure AI Search admite la codificación Base64 normal y la de seguridad de direcciones URL. Una cadena codificada con Base64 durante la indexación se debe descodificar más adelante con las mismas opciones de codificación o, de lo contrario, el resultado no coincidirá con el original.

Si los parámetros useHttpServerUtilityUrlTokenEncode o useHttpServerUtilityUrlTokenDecode para codificar y descodificar respectivamente se establecen en true, base64Encode se comporta como HttpServerUtility.UrlTokenEncode y base64Decode se comporta como HttpServerUtility.UrlTokenDecode.

Advertencia

Si se utiliza base64Encode para generar valores de clave, useHttpServerUtilityUrlTokenEncode debe establecerse en true. Solo se puede usar la codificación Base64 de seguridad de direcciones URL para los valores de clave. Consulte Reglas de nomenclatura para obtener el conjunto completo de restricciones sobre los caracteres de los valores de clave.

Las bibliotecas .NET de Azure AI Search asumen el .NET Framework completo, que proporciona codificación integrada. Las opciones useHttpServerUtilityUrlTokenEncode y useHttpServerUtilityUrlTokenDecode aprovechan esta funcionalidad integrada. Si usa .NET Core u otro marco, se recomienda establecer esas opciones en false y llamar directamente a las funciones de codificación y descodificación de su marco de trabajo.

La tabla siguiente compara diferentes codificaciones Base64 de la cadena 00>00?00. Para determinar el procesamiento necesario (si existe) para las funciones de Base64, aplique la función de codificación de bibliotecas en la cadena 00>00?00 y compare el resultado con el resultado esperado MDA-MDA_MDA.

Encoding	Salida de codificación Base64	Procesamiento adicional después de la codificación de bibliotecas	Procesamiento adicional antes de la descodificación de bibliotecas
Base64 con espaciado interno	`MDA+MDA/MDA=`	Use caracteres seguros para direcciones URL y quite el espaciado interno	Use caracteres estándar de Base64 y agregue espaciado interno
Base64 sin espaciado interno	`MDA+MDA/MDA`	Use caracteres seguros para direcciones URL	Use caracteres estándar de Base64
Base64 de seguridad de direcciones URL con espaciado interno	`MDA-MDA_MDA=`	Quite el espaciado interno	Agregue el espaciado interno
Base64 de seguridad de direcciones URL sin espaciado interno	`MDA-MDA_MDA`	Ninguno	Ninguno

Función extractTokenAtPosition

Divide un campo de cadena con el delimitador especificado y elige el token en la posición especificada de la división resultante.

Esta función utiliza los siguientes parámetros:

delimiter: una cadena para su uso como separador al dividir la cadena de entrada.
position: una posición de base cero entera del token que se va a elegir tras dividirse la cadena de entrada.

Por ejemplo, si la entrada es Jane Doe, delimiter es " "(espacio) y position es 0, el resultado es Jane; si position es 1, el resultado es Doe. Si la posición hace referencia a un token que no existe, se devolverá un error.

Ejemplo: extraer un nombre

Su origen de datos contiene un campo PersonName y desea indexarlo como dos campos FirstName y LastName independientes. Puede usar esta función para dividir la entrada con el carácter de espacio 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 } }
  }]

Función jsonArrayToStringCollection

Transforma una cadena con formato de una matriz JSON de cadenas en una matriz de cadenas que puede usarse para rellenar un campo Collection(Edm.String) del índice.

Por ejemplo, si la cadena de entrada es ["red", "white", "blue"], el campo de destino de tipo Collection(Edm.String) se rellenará con los tres valores red, white y blue. En el caso de los valores de entrada que no pueden analizarse como matrices de cadenas JSON, se devolverá un error.

Ejemplo: rellenar la colección de datos relacionales

Azure SQL Database no tiene un tipo de datos integrado que se asigne de forma natural a los campos Collection(Edm.String) de Azure AI Search. Para rellenar los campos de colección de cadenas, puede procesar previamente los datos de origen como una matriz de cadenas JSON y, luego, usar la función de asignación jsonArrayToStringCollection.

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

Función urlEncode

Esta función se puede utilizar para codificar una cadena de modo que sea "segura para la dirección URL". Cuando se usa con una cadena que contiene caracteres no permitidos en una dirección URL, esta función convertirá esos caracteres "no seguros" en equivalentes de carácter-entidad. Esta función utiliza el formato de codificación UTF-8.

Ejemplo: búsqueda de clave de documento

La función urlEncode se puede usar como alternativa a la función base64Encode, si solo se van a convertir los caracteres no seguros de la dirección URL y se mantienen los otros caracteres tal cual.

Por ejemplo, si la cadena de entrada es <hello>, el campo de destino de tipo (Edm.String) se rellenará con el valor %3chello%3e.

Al recuperar la clave codificada en el tiempo de búsqueda, puede usar la función urlDecode para obtener el valor de clave original y usarlo para recuperar el documento de origen.

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

Función urlDecode

Esta función convierte una cadena con codificación URL en una cadena descodificada mediante el formato de codificación UTF-8.

Ejemplo: descodificar metadatos de blob

Algunos clientes de almacenamiento de Azure codifican automáticamente en código URL los metadatos de un blob si contiene caracteres que no son ASCII. Sin embargo, si quiere que dichos metadatos se puedan buscar (como texto sin formato), puede usar la función urlDecode para volver a convertir los datos codificados en cadenas "normales" al rellenar su índice de búsqueda.

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

Función fixedLengthEncode

Esta función convierte una cadena de cualquier longitud en una cadena de longitud fija.

Ejemplo: asignar claves de documento demasiado largas

Cuando se producen errores relacionados con la longitud de clave de documento superior a 1024 caracteres, esta función se puede aplicar para reducir la longitud de la clave del documento.


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

Función toJson

Esta función convierte una cadena en un objeto JSON con formato. Esto se puede usar en escenarios en los que el origen de datos, como Azure SQL, no admite de forma nativa tipos de datos compuestos o jerárquicos y, a continuación, los asigna a campos complejos.

Ejemplo: asignar contenido de texto a un campo complejo

Supongamos que hay una fila SQL con una cadena JSON que debe asignarse a un campo complejo (definido) en el índice, se puede usar la función toJson para lograrlo. Por ejemplo, si es necesario rellenar un campo complejo en el índice con los datos siguientes:

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

Se puede lograr mediante la función de asignación toJson en una columna de cadena JSON de una fila SQL que tenga este aspecto: {"id": 5, "info": {"name": "Jane", "surname": "Smith", "skills": ["SQL", "C#", "Azure"]}, "dob": "2005-11-04T12:00:00"}.

La asignación de campos debe especificarse como se muestra a continuación.


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

Escenarios avanzados de asignación de campos

En escenarios en los que tiene relaciones de documento de uno a varios, como la fragmentación o la división de datos, siga estas instrucciones para asignar campos de documentos primarios a documentos "secundarios" (fragmentos):

1. Omitir la indexación de documentos primarios

Si va a omitir la indexación de documentos primarios (estableciendo projectionMode a skipIndexingParentDocuments en el conjunto indexProjections de aptitudes ), use proyecciones de índice para asignar campos de los documentos primarios a los documentos "secundarios".

2. Indexación de documentos primarios y "secundarios"

Si va a indexar documentos primarios y documentos "secundarios":

Use asignaciones de campos para asignar campos a los documentos primarios.
Use proyecciones de índice para asignar campos a los documentos "secundarios".

3. Asignación de valores transformados por funciones a documentos primarios o "secundarios"

Si un campo del documento primario requiere una transformación (mediante las funciones de asignación como la codificación) y debe asignarse a los documentos primarios o "secundarios":

Aplique la transformación mediante las funciones de asignaciones de campos en el indexador.
Use proyecciones de índice en el conjunto de aptitudes para asignar el campo transformado a los documentos "secundarios".

Compartir a través de