Indexación de datos desde Azure Blob Storage

Artículo
09/03/2024

En este artículo, aprenderá a configurar un indexador que importa contenido de Azure Blob Storage 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 se complementa la creación de un indexador con información específica de Blob Storage. 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.

Los indexadores de blobs se suelen usar para el enriquecimiento con IA y el procesamiento basado en texto. Este artículo se centra en los indexadores para la indexación basada en texto, donde solo se ingieren el contenido textual y los metadatos para escenarios de búsqueda de texto completo.

Requisitos previos

Azure Blob Storage, rendimiento estándar (uso general v2).
Los niveles de acceso son frecuente, esporádico, frío y archivo. Los indexadores pueden recuperar blobs de los niveles de acceso frecuente, esporádico y frío.
Blobs que proporcionan contenido de texto y metadatos. Si los blobs contienen contenido binario o texto no estructurado, considere la posibilidad de agregar enriquecimiento con IA para el procesamiento de imágenes y lenguaje natural. El contenido del blob no puede superar los límites del indexador para el nivel de servicio de búsqueda.
Configuración de red admitida y acceso a datos. Como mínimo, necesitará permisos de lectura en Azure Storage. Una cadena de conexión de almacenamiento que incluya una clave de acceso le proporciona acceso de lectura al contenido de almacenamiento. Si en su lugar usa los inicios de sesión y roles de Microsoft Entra, asegúrese de que la identidad administrada del servicio de búsqueda tenga permisos de lector de datos de Storage Blob.

De forma predeterminada, tanto la búsqueda como el almacenamiento aceptan solicitudes de direcciones IP públicas. Si la seguridad de red no es un problema inmediato, puede indexar datos de blob con solo la cadena de conexión y los permisos de lectura. Cuando esté listo para agregar protecciones de red, consulte Acceso del indexador al contenido protegido por las características de seguridad de red de Azure para obtener instrucciones sobre el acceso a datos.
Use un cliente REST para formular llamadas REST similares a las que se muestran en este artículo.

Formatos de documento admitidos

El indizador de blobs puede extraer texto de los siguientes formatos de documento:

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.

Un documento compuesto o insertado (por ejemplo, un archivo ZIP o un documento de Word con correo electrónico de Outlook insertado que contiene datos adjuntos, o un archivo .MSG con datos adjuntos) también se indexa como un solo documento. Por ejemplo, todas las imágenes extraídas de los datos adjuntos de un archivo MSG se devolverán en el campo normalized_images. Si tiene imágenes, considere la posibilidad de agregar el enriquecimiento con IA para obtener más utilidades de búsqueda a partir de ese contenido.

El contenido textual de un documento se extrae en un campo de cadena denominado "content". También puede extraer metadatos estándar y definidos por el usuario.

Indexación de metadatos de blob

Los metadatos de blob también se pueden indexar. Esto es útil si considera que cualquiera de las propiedades de metadatos estándar o personalizadas puede venir bien para 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.

Actualmente, este indexador no admite etiquetas de índice de blobs.

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-blob-datasource",
    "type" : "azureblob",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
}

Establezca "type" en "azureblob" (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).

Firma de acceso compartido de contenedor
`{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }`
La firma de acceso compartido debe tener permisos de enumeración y lectura sobre el contenedor. Para más información, consulte Uso de firmas de acceso compartido.

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:

POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
{
    "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. Sin embargo, 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 blobs

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:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer",
  "dataSourceName" : "my-blob-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) subutiliza los recursos disponibles o los utiliza en exceso. 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 "configuración", establezca "parsingMode". El modo de análisis predeterminado es un documento de búsqueda por blob. Si los blobs son texto sin formato, puede obtener un mejor rendimiento cambiando al análisis de texto sin formato. Si necesita un análisis más granular que asigne blobs a varios documentos de búsqueda, especifique otro modo. El análisis de uno a varios es compatible con blobs que constan de:
- Documentos JSON
- 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, vea API 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.

Indización de datos de varios contenedores de blobs de Azure a un único índice

Tenga en cuenta que un indizador solo puede indizar datos de un único contenedor. Si el requisito es indizar datos de varios contenedores y consolidarlos en un único índice de búsqueda de IA, esto se puede lograr configurando varios indizadores, todos dirigidos al mismo índice. Tenga en cuenta el número máximo de indizadores disponibles por SKU.

Para ilustrarlo, veamos un ejemplo de dos indizadores, que extraen datos de dos orígenes de datos distintos, denominados my-blob-datasource1 y my-blob-datasource2. Cada origen de datos apunta a un contenedor de blobs de Azure independiente, pero ambos se dirigen al mismo índice denominado my-search-index.

Primer ejemplo de definición del indizador:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

Segunda definición del indizador que se ejecuta en el ejemplo paralelo:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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.

Compartir a través de