Transformar y asignar campos mediante indexadores de Azure AI Search

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.

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.

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

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

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.

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.

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.

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.

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

Consulte también

• Tipos de datos admitidos en Azure AI Search
• Asignación de tipo de datos de SQL