Indexación de datos desde Azure Data Lake Storage Gen2

Artículo
12/10/2024

En este artículo, aprenderá a configurar un indexador que importa contenido de Azure Data Lake Storage (ADLS) Gen2 y hace que se pueda buscar en Azure AI Search. Las entradas al indexador son los blobs, en un solo contenedor. La salida es un índice de búsqueda con contenido que se puede buscar y metadatos almacenados en campos individuales.

En este artículo complementa el artículo sobre la creación de indexadores con información específica acerca de la indexación de ADLS Gen2. Usa las API REST para mostrar un flujo de trabajo de tres partes común a todos los indexadores: crear un origen de datos, crear un índice y crear un indexador. La extracción de datos se produce cuando se envía la solicitud para crear un indexador.

Para obtener un ejemplo de código en C#, consulta Indexar Data Lake Gen2 mediante Microsoft Entra ID en GitHub.

Requisitos previos

ADLS Gen2 con el espacio de nombres jerárquico habilitado. ADLS Gen2 está disponible a través de Azure Storage. Al configurar una cuenta de almacenamiento, tiene la opción de habilitar el espacio de nombres jerárquico con la organización de los archivos en una jerarquía de directorios y subdirectorios anidados. Al habilitar un espacio de nombres jerárquico, se habilita ADLS Gen2.
Entre los niveles de acceso de ADLS Gen2 se incluyen los de tipo frecuente, esporádico y archivo. Los indexadores de búsqueda solo tienen acceso frecuente y esporádico.
Blobs que contienen texto. Si tiene datos binarios, puede incluir el enriquecimiento con inteligencia artificial para el análisis de imágenes. El contenido del blob no puede superar los límites del indexador para el nivel de servicio de búsqueda.
Permisos de lectura en Azure Storage. Una cadena de conexión de "acceso completo" incluye una clave que concede acceso al contenido, pero si usted usa roles de Azure en su lugar, asegúrese de que la identidad administrada del servicio de búsqueda disponga de permisos de Lector de datos de blobs de almacenamiento.
Use un cliente REST para formular llamadas REST similares a las que se muestran en este artículo.

Nota:

ADLS Gen2 implementa un modelo de control de acceso compatible con el control de acceso basado en rol de Azure (RBAC de Azure) y las listas de control de acceso (ACL) tipo POSIX en el nivel de blob. Azure AI Search no admite permisos de nivel de documento. Todos los usuarios tienen el mismo nivel de acceso a todo el contenido que se puede buscar y recuperar del índice. Si los permisos de nivel de documento son un requisito de la aplicación, piense en el recorte de seguridad como posible solución.

Formatos de documento admitidos

El indexador de ADLS Gen2 puede extraer texto de los formatos de documento siguientes:

CSV (consulte Indexación de blobs CSV)
EML
EPUB
GZ
HTML
JSON (vea Indexación de blobs JSON)
KML (XML para representaciones geográficas)
Formatos de Microsoft Office: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (correos electrónicos de Outlook), XML (WORD XML 2003 y 2006)
Formatos de Open Document: ODT, ODS, ODP
PDF
Archivos de texto sin formato (vea también Indexing plain text (Indexación de texto sin formato))
RTF
XML
ZIP

Determinación de los blobs que se indexan

Antes de configurar la indexación, revise los datos de origen para determinar si los cambios deben realizarse por adelantado. Un indexador puede indexar el contenido de un contenedor cada vez. De manera predeterminada, se procesan todos los blobs del contenedor. Tiene varias opciones para un procesamiento más selectivo:

Coloque blobs en una carpeta virtual. Una definición de origen de datos del indexador incluye un parámetro de "consulta" que puede tomar una carpeta virtual. Si especifica una carpeta virtual, solo se indexan los blobs de la carpeta.
Incluya o excluya blobs por tipo de archivo. La lista de formatos de documento admitidos puede ayudarle a determinar qué blobs excluir. Por ejemplo, es posible que quiera excluir archivos de imagen o audio que no proporcionen texto que permite búsquedas. Esta funcionalidad se controla a través de los valores de configuración del indexador.

Incluya o excluya blobs arbitrarios. Si quiere omitir un blob específico por cualquier motivo, puede agregar las siguientes propiedades de metadatos y valores a blobs en Blob Storage. Cuando un indexador encuentra esta propiedad, omite el blob o su contenido en la ejecución de la indexación.

Nombre de propiedad	Valor de propiedad	Explicación
"AzureSearch_Skip"	`"true"`	Indica al indizador de blob que pase completamente el blob. No se trata de realizar la extracción de metadatos ni del contenido. Esto es útil cuando se produce un error repetidamente y se interrumpe el proceso de indización de un blob determinado.
"AzureSearch_SkipContent"	`"true"`	Omite el contenido y extrae solo los metadatos. Esto es equivalente a la configuración `"dataToExtract" : "allMetadata"` descrita en los valores de configuración, solo con ámbito en un blob determinado.

Si no configura criterios de inclusión o exclusión, el indexador mostrará un blob no apto como error y continuará. Si se producen errores suficientes, el procesamiento podría detenerse. Puede especificar tolerancia a errores en las opciones de configuración del indexador.

Normalmente, un indexador crea un documento de búsqueda por blob, donde el contenido de texto y los metadatos se capturan como campos que admiten búsquedas en un índice. Si los blobs son archivos enteros, puede analizarlos en varios documentos de búsqueda. Por ejemplo, puede analizar las filas de un archivo CSV para crear un documento de búsqueda por fila.

Indexación de metadatos de blob

Los metadatos de blob también se pueden indexar, lo cual es de ayuda si considera que cualquiera de las propiedades de metadatos estándar o personalizadas puede resultar útil en los filtros y las consultas.

Las propiedades de metadatos especificadas por el usuario se extraen textualmente. Para recibir los valores, debe definir el campo en el índice de búsqueda de tipo Edm.String con el mismo nombre que la clave de metadatos del blob. Por ejemplo, si un blob tiene una clave de metadatos de Sensitivity con el valor High, debe definir un campo denominado Sensitivity en el índice de búsqueda y se rellenará con el valor High.

Las propiedades de metadatos de blob estándar se pueden extraer en campos con nombres y tipos similares, como se muestra a continuación. El indexador de blobs crea asignaciones de campos internas para estas propiedades de metadatos de blob de manera automática; para ello, convierte el nombre con guion original ("nombre-almacenamiento-metadatos") en un nombre equivalente con subrayado ("nombre_almacenamiento_metadatos").

Aún así, tendrá que agregar los campos con subrayado a la definición de índice, pero puede omitir las asignaciones de campos porque el indexador hará la asociación de manera automática.

metadata_storage_name (Edm.String): nombre de archivo del blob. Por ejemplo, si tiene un blob /my-container/my-folder/subfolder/resume.pdf, el valor de este campo es resume.pdf.
metadata_storage_path (Edm.String): URI completo del blob, incluida la cuenta de almacenamiento. Por ejemplo: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf
metadata_storage_content_type (Edm.String): tipo de contenido tal como especifica el código que usó para cargar el blob. Por ejemplo, application/octet-stream.
metadata_storage_last_modified (Edm.DateTimeOffset): última marca de tiempo modificada del blob. Azure AI Search usa esta marca de tiempo para identificar los blobs modificados para evitar volver a indexar todo después de la indexación inicial.
metadata_storage_size (Edm.Int64): tamaño del blob en bytes.
metadata_storage_content_md5 (Edm.String): hash MD5 del contenido del blob, si está disponible.
metadata_storage_sas_token (Edm.String): un token de SAS temporal que pueden usar las aptitudes personalizadas para obtener acceso al blob. Este token no se debe almacenar para su uso posterior, ya que podría expirar.

Por último, las propiedades de metadatos específicas del formato de documento de los blobs que está indexando también se pueden representar en el esquema de índice. Para obtener más información sobre los metadatos específicos de contenido, vea Propiedades de metadatos de contenido.

Es importante señalar que no es necesario definir campos para todas las propiedades anteriores en el índice de búsqueda, capture solo las propiedades que necesita para la aplicación.

Definición del origen de datos

La definición del origen de datos especifica los datos que se indexan, las credenciales y las directivas para identificar los cambios en los datos. Un origen de datos se define como un recurso independiente de forma que puedan usarlo varios indexadores.

Cree o actualice un origen de datos para establecer su definición:

{
    "name" : "my-adlsgen2-datasource",
    "type" : "adlsgen2",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Establezca "type" en "adlsgen2" (obligatorio).
Establezca "credentials" en una cadena de conexión de Azure Storage. En la sección siguiente se describen los formatos admitidos.
Establezca "container" en el contenedor de blobs y use "query" para especificar las subcarpetas.

Una definición de origen de datos también puede incluir directivas de eliminación temporal, si quiere que el indexador elimine un documento de búsqueda cuando el documento de origen esté marcado para su eliminación.

Credenciales y cadenas de conexión admitidas

Los indexadores pueden conectarse a un contenedor de blobs mediante las conexiones siguientes.

Cadena de conexión de la cuenta de almacenamiento de acceso total
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
Para obtener la cadena de conexión de la página Cuenta de almacenamiento en Azure Portal, seleccione Claves de acceso en el panel de navegación izquierdo. Asegúrese de seleccionar una cadena de conexión completa y no solo una clave.

Cadena de conexión de identidad administrada
`{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }`
Esta cadena de conexión no requiere una clave de cuenta, pero debe haber configurado previamente un servicio de búsqueda para conectarse mediante una identidad administrada.

Cadena de conexión de la firma de acceso compartido** (SAS) de la cuenta de almacenamiento
`{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }`
La firma de acceso compartido debe tener permisos de enumeración y lectura sobre los contenedores y objetos (en este caso, los blobs).

Nota:

Si usa credenciales SAS, deberá actualizar las credenciales del origen de datos periódicamente con firmas renovadas para evitar que caduquen. Si las credenciales SAS expiran, el indexador produce un error con un mensaje parecido a este: "Las credenciales proporcionadas en la cadena de conexión no son válidas o han expirado".

Adición de campos de búsqueda a un índice

En un índice de búsqueda, agregue campos para aceptar el contenido y los metadatos de los blobs de Azure.

Cree o actualice un índice para definir campos de búsqueda que almacenarán el contenido y los metadatos del blob:

{
    "name" : "my-search-index",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }     
    ]
}

Cree un campo de clave de documento ("key": true). Para el contenido de los blobs, los mejores candidatos son las propiedades de metadatos.
- metadata_storage_path (valor predeterminado) es la ruta de acceso completa al objeto o archivo. El campo de clave ("ID" en este ejemplo) se rellenará con valores de metadata_storage_path porque es el valor predeterminado.
- metadata_storage_name utilizable solo si los nombres son únicos. Si desea que este campo sea la clave, pase "key": true a esta definición de campo.
- Propiedad de metadatos personalizada que se agrega a los blobs. Esta opción requiere que el proceso de carga de blobs agregue dicha propiedad de metadatos a todos los blobs. Dado que la clave es una propiedad obligatoria, todos los blobs a los que les falte esa propiedad no se indexarán. Si usa una propiedad de metadatos personalizada como clave, evite realizar cambios en esa propiedad. Los indexadores agregarán documentos duplicados para el mismo blob si cambia la propiedad de clave.
Las propiedades de metadatos suelen incluir caracteres, como / y -, que no son válidos para las claves de documento. El indexador codifica automáticamente la propiedad de metadatos de clave, sin que se requiera ninguna configuración ni asignación de campos.
Agregue un campo "content" para almacenar el texto extraído de cada archivo mediante la propiedad "content" del blob. No es necesario usar este nombre, pero, si lo hace, podrá aprovechar las asignaciones de campos implícitas.
Agregue campos para las propiedades de metadatos estándar. El indexador puede leer propiedades de metadatos personalizadas, propiedades de metadatos estándar y propiedades de metadatos específicos de contenido.

Configuración y ejecución del indexador de ADLS Gen2

Una vez creados el índice y el origen de datos, ya podrá crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos en tiempo de ejecución. También puede especificar qué partes de un blob se indexan.

Cree o actualice un indexador asignándole un nombre y haciendo referencia al origen de datos y al índice de destino:

{
  "name" : "my-adlsgen2-indexer",
  "dataSourceName" : "my-adlsgen2-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Establezca "batchSize" si el valor predeterminado (10 documentos) infrautiliza o sobreutiliza los recursos disponibles. Los tamaños de lote predeterminados son específicos para cada origen de datos. La indexación de blobs establece el tamaño de lote en 10 documentos en atención al tamaño máximo medio de los documentos.
En "configuration", controle qué blobs se indexan en función del tipo de archivo o deje sin especificar para recuperar todos los blobs.

En "indexedFileNameExtensions", proporcione una lista separada por comas de extensiones de archivo (con un punto inicial). Haga lo mismo con "excludedFileNameExtensions" para indicar qué extensiones se deben omitir. Si la misma extensión está en ambas listas, se excluirá de la indexación.
En "configuration", establezca "dataToExtract" para controlar qué partes de los blobs se indexan:
- "contentAndMetadata" especifica que se indexan todos los metadatos y el contenido textual extraído del blob. Este es el valor predeterminado.
- "storageMetadata" especifica que solamente se indexan las propiedades de blob estándar y los metadatos especificados por el usuario.
- "allMetadata" especifica que las propiedades de blob estándar y los metadatos para los tipos de contenido encontrados se extraen del contenido del blob y se indexan.
En "configuration", establezca "parsingMode" si los blobs deben asignarse a varios documentos de búsqueda o si constan de texto sin formato, documentos JSON o archivos CSV.
Especifique asignaciones de campos si hay diferencias en el nombre o el tipo de campo, o si necesita varias versiones de un campo de origen en el índice de búsqueda.

En la indexación de blobs, a menudo puede omitir las asignaciones de campos porque el indexador tiene compatibilidad integrada para asignar las propiedades "content" y de metadatos a campos con nombre y tipo similares en un índice. En el caso de las propiedades de metadatos, el indexador reemplazará automáticamente los guiones - por caracteres de subrayado en el índice de búsqueda.
Consulte Creación de un indexador para más información sobre otras propiedades. Para obtener la lista completa de descripciones de parámetros, consulte Crear indexador (REST) en la API de REST.

Un indexador se ejecuta automáticamente cuando se crea. Puede evitarlo estableciendo el valor de "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o prográmelo.

Comprobación del estado del indexador

Para supervisar el estado del indexador y el historial de ejecución, envíe una solicitud para Obtener el estado del indexador:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

La respuesta incluye el estado y el número de elementos procesados. Debe tener un aspecto similar al siguiente ejemplo:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

El historial de ejecución contiene como máximo las 50 ejecuciones completadas más recientemente en orden cronológico inverso (la ejecución más reciente aparece en primer lugar).

errores

Los errores que suelen producirse durante la indexación incluyen tipos de contenido no admitidos, contenido que falta o blobs demasiado grandes.

De manera predeterminada, el indexador de blobs se detiene cuando encuentra un blob con un tipo de contenido no admitido (por ejemplo, un archivo de audio). Puede usar el parámetro "excludedFileNameExtensions" para omitir determinados tipos de contenido. Sin embargo, es posible que quiera realizar la indexación para continuar aunque se produzcan errores y, a continuación, depurar documentos concretos posteriormente. Para obtener más información sobre los errores del indizador, vea Instrucciones de solución de problemas del indizador y Errores y advertencias del indizador.

Hay cinco propiedades de indexador que controlan la respuesta de este cuando se producen errores.

PUT /indexers/[indexer name]?api-version=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Parámetro	Valores válidos	Descripción
"maxFailedItems"	-1, nulo o 0, entero positivo	Continue con la indexación si se producen errores en cualquier punto del procesamiento, mientras se analizan blobs o se agregan documentos a un índice. Establezca estas propiedades en el número de errores aceptables. Un valor de `-1` permite el procesamiento, independientemente del número de errores que se produzcan. De lo contrario, el valor es un entero positivo.
"maxFailedItemsPerBatch"	-1, nulo o 0, entero positivo	Igual que antes, pero se usa para la indexación por lotes.
"failOnUnsupportedContentType"	true o false	Si el indexador no puede determinar el tipo de contenido, especifique si quiere continuar o no el trabajo.
"failOnUnprocessableDocument"	true o false	Si el indexador no puede procesar un documento de otro tipo de contenido admitido, especifique si quiere continuar o no el trabajo.
"indexStorageMetadataOnlyForOversizedDocuments"	true o false	Los blobs demasiado grandes se tratan como errores de forma predeterminada. Si establece este parámetro en true, el indexador intentará indexar sus metadatos aunque el contenido no se pueda indexar. Si quiere obtener información acerca de los límites de tamaño de los blobs, consulte los límites de servicio.

Limitaciones

A diferencia de los indexadores de blobs, los indexadores de ADLS Gen2 no pueden usar tokens de SAS de nivel de contenedor para enumerar e indexar contenido desde una cuenta de almacenamiento. Esto se debe a que el indexador realiza una comprobación para determinar si la cuenta de almacenamiento tiene espacios de nombres jerárquicos habilitados mediante una llamada a la API de obtención de propiedades del sistema de archivos. En el caso de las cuentas de almacenamiento en las que los espacios de nombres jerárquicos no están habilitados, se recomienda que los clientes usen indexadores de blobs para garantizar una enumeración de blobs eficaz.
Si la propiedad metadata_storage_path se asigna como el campo de clave de índice, no se garantiza que los blobs se vuelvan a indexar al cambiar el nombre de un directorio. Si quiere volver a indexar los blobs que forman parte de los directorios cuyo nombre ha cambiado, actualice las marcas de tiempo de LastModified de todos ellos.

Pasos siguientes

Ahora puede ejecutar el indexador, supervisar el estado o programar la ejecución del indexador. Los artículos siguientes se aplican a los indexadores que extraen contenido de Azure Storage:

Compartir a través de