Indexación de datos desde Azure Blob Storage

El indexador de blobs importa contenido de Azure Blob Storage y hace que se pueda buscar en Búsqueda de Azure AI. El indexador recibe blobs en un único contenedor como entrada. La salida es un índice de búsqueda que almacena contenido y metadatos que se pueden buscar en campos individuales.

En este artículo se usan las API REST del servicio de búsqueda para demostrar cómo configurar y ejecutar el indexador. Sin embargo, también puede usar:

• Un paquete de SDK de Azure (cualquier versión)
• Asistente para importación de datos en Azure Portal

Prerrequisitos

• 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 en niveles de acceso frecuente, esporádico y esporádico.

• 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 plan de tarifa.

  Los límites del indexador de blobs cubren el tamaño máximo del blob y el número de caracteres que Búsqueda de Azure AI extrae de un blob. Si usa un conjunto de aptitudes, el límite de entrada o servicio de cada aptitud se aplica por separado después del descifrado de documentos.

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

Tareas compatibles

Puede usar este indexador para las siguientes tareas:

• Indexación de datos e indexación incremental: el indexador puede indexar archivos y metadatos asociados desde carpetas y contenedores de blobs. Detecta archivos y metadatos nuevos y actualizados a través de la detección de cambios integrada. Puede configurar la actualización de datos según una programación o a petición.

• Detección de eliminación: el indexador puede detectar eliminaciones a través de eliminaciones temporales nativas o de metadatos personalizados.

• Ia aplicada a través de conjuntos de aptitudes: El indexador es totalmente compatible con conjuntos de aptitudes. Esta compatibilidad incluye características clave como la vectorización integrada, que agrega fragmentación e inserción de datos.

• Modos de análisis: el indizador admite modos de análisis JSON si desea analizar matrices o líneas JSON en documentos de búsqueda individuales. También admite el modo de análisis de Markdown.

• Compatibilidad con otras características: El indexador funciona sin problemas con otras características del indexador, como sesiones de depuración, caché del indexador para enriquecimientos incrementales (versión preliminar) y almacén de conocimiento.

Formatos de documento admitidos

El indexador de blob 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)
• Markdown
• 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 necesita realizar cambios. Un indexador puede indexar el contenido de un contenedor cada vez. De forma predeterminada, el indexador procesa 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 query parámetro que puede tomar una carpeta virtual. Si especifica una carpeta virtual, el indexador solo indexa esos blobs en 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 las opciones de configuración del indexador.

• Incluya o excluya blobs arbitrarios. Para omitir un blob específico, agregue las siguientes propiedades y valores de metadatos a blobs en Azure 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	Explanation
  AzureSearch_Skip	true	Indica al indizador de blob que pase completamente el blob. El indexador no intenta extraer metadatos ni contenido. Esta propiedad es útil cuando se produce un error en un blob determinado repetidamente e interrumpe el proceso de indexación.
  AzureSearch_SkipContent	true	El indexador omite el contenido y extrae solo los metadatos. Esta propiedad es equivalente a la "dataToExtract": "allMetadata" configuración descrita en los valores de configuración, pero se limita a un blob determinado.

Si no configura criterios de inclusión o exclusión, el indexador notifica un blob no apto como un error y sigue adelante. 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 devuelven 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 indexador extrae el contenido textual de un documento 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

Puede indexar metadatos de blob junto con el contenido. El indexador extrae propiedades de metadatos y las almacena en campos de índice, lo que resulta útil para crear filtros y consultas.

Defina campos en el índice de búsqueda para las propiedades de metadatos que desea capturar. No es necesario definir todas las propiedades de metadatos estándar o personalizadas disponibles. Solo tiene que capturar las propiedades que necesita para la aplicación.

Actualmente, este indexador no admite la indexación de etiquetas de índice de blobs.

Propiedades de metadatos de blobs estándar

Para los metadatos de blobs estándar, defina campos en el índice con los mismos nombres de subrayado. Para ver ejemplos de definición de campos paso a paso, consulte Adición de campos de búsqueda a un índice.

Para la configuración del indexador, incluida la dataToExtract configuración que controla qué metadatos se van a extraer, consulte Configuración y ejecución del indexador de blobs.

El indexador reconoce y puede asignar estas propiedades de metadatos estándar si define los campos correspondientes en el índice:

• metadata_storage_name (Edm.String) es el 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) es el URI completo del blob, incluida la cuenta de almacenamiento. Por ejemplo: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf. Use esta propiedad para incluir direcciones URL de blob en los resultados de búsqueda para la navegación o la atribución de origen.

• metadata_storage_content_type (Edm.String) es el tipo de contenido especificado por el código que usó para cargar el blob. Por ejemplo: application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset) es la última marca de tiempo modificada para el blob. Búsqueda de Azure AI usa esta marca de tiempo para identificar los blobs modificados y evitar volver a indexar todo después de la indexación inicial.

• metadata_storage_size (Edm.Int64) es el tamaño del blob en bytes.

• metadata_storage_content_md5 (Edm.String) es el hash MD5 del contenido del blob, si está disponible.

• metadata_storage_sas_token (Edm.String) es un token de SAS temporal que las aptitudes personalizadas pueden usar para obtener acceso al blob. No almacene este token para su uso posterior, ya que podría expirar.

Metadatos personalizados y específicos del contenido

Para metadatos de blobs personalizados o definidos por el usuario, defina un campo con el mismo nombre que la clave de metadatos del blob. Por ejemplo, si los blobs tienen una clave Sensitivity de metadatos con el valor High, defina un campo denominado Sensitivity de tipo Edm.String en el índice.

También puede representar propiedades de metadatos específicas del formato de documento de los blobs que está indexando. Para obtener más información, vea Propiedades de metadatos de contenido.

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.

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

2. Establezca type en azureblob (obligatorio).

3. Establezca credentials en una cadena de conexión de Azure Storage. En la sección siguiente, se describen los formatos admitidos.

4. Establezca container en el contenedor de blobs y use query para especificar las subcarpetas.

También puede incluir directivas de eliminación temporal en una definición de origen de datos si desea 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 siguientes conexiones.

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.

1. Cree o actualice un índice para definir campos de búsqueda que almacenan el contenido y los metadatos del blob:

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-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 },        
       ]
   }
   

2. 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 rellena con valores de metadata_storage_path porque es el valor predeterminado.

   • metadata_storage_name solo se puede usar 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 necesaria, los blobs que faltan en un valor no se pueden indexar. Si usa una propiedad de metadatos personalizada como clave, evite realizar cambios en esa propiedad. Los indexadores agregan 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.

3. Añada 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 usa, puede aprovechar las asignaciones de campos implícitas.

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

Después de crear el índice y el origen de datos, cree 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.

1. 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=2026-04-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" : [ ]
   }
   

2. Establezca batchSize si el valor predeterminado (10 documentos) infrautiliza o sobrecarga 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.

3. 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 para excludedFileNameExtensions indicar qué extensiones debe omitir el indexador. Si la misma extensión está en ambas listas, el indexador lo excluye de la indexación.

4. En configuration, establezca dataToExtract para controlar qué partes de los blobs se indexan:

   • contentAndMetadata especifica que el indexador indexa todos los metadatos y el contenido textual extraído del blob. Este es el valor predeterminado.

   • storageMetadata especifica que el indexador solo indexa las propiedades de blob estándar y los metadatos especificados por el usuario.

   • allMetadata especifica que el indexador extrae del contenido del blob e indexa las propiedades de blob estándar y los metadatos de los tipos de contenido encontrados.

   • Para obtener una lista completa de las propiedades de metadatos estándar disponibles y sus tipos de campo, consulte Indexación de metadatos de blobs.

5. En configuration, 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

6. 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 content y las propiedades de metadatos, a campos con nombres y tipos similares en un índice. En el caso de las propiedades de metadatos, el indizador reemplaza automáticamente los guiones - por guiones bajos en el índice de búsqueda.

7. 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 evitar esta acción estableciendo disabled en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o prográmelo.

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

Recuerde que un indexador solo puede indexar datos de un único contenedor. Si necesita indexar datos de varios contenedores y consolidarlos en un único índice de AI Search, configure varios indexadores que apunten al mismo índice. Tenga en cuenta el número máximo de indexadores disponibles por SKU.

Por ejemplo, puede usar dos indexadores para extraer 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=2026-04-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=2026-04-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=2026-04-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 hasta 50 de las ejecuciones completadas más recientemente. Las entradas se ordenan en orden cronológico inverso, por lo que la ejecución más reciente es la primera.

Solución de problemas

Use esta sección para diagnosticar los valores de metadatos que faltan y los errores comunes de indexación de blobs.

Los campos de metadatos son null en los resultados de búsqueda

Si ve valores NULL o vacíos para los campos de metadatos en los resultados de búsqueda, use esta lista de comprobación:

1. Compruebe que el campo existe en el esquema de índice: Compruebe que ha definido un campo para cada propiedad de metadatos que desea capturar. Ejecute una solicitud GET en el índice para confirmar que el campo está presente.

2. Use el nombre de campo correcto: En el caso de las propiedades de blob estándar, use el nombre subrayado, como metadata_storage_path en lugar de metadata-storage-path. Para los metadatos personalizados, el nombre del campo debe coincidir exactamente con la clave de metadatos del blob.

3. Confirme que el indexador tiene dataToExtract configurado correctamente:

   • contentAndMetadata (valor predeterminado) extrae tanto el contenido como los metadatos estándar o personalizados.
   • storageMetadata extrae solo las propiedades de blob estándar y los metadatos personalizados.
   • allMetadata extrae propiedades estándar más metadatos específicos del tipo de contenido.

   Compruebe la configuración del indexador para asegurarse de que la configuración coincide con la intención.

4. Vuelva a ejecutar el indexador después de las actualizaciones del esquema: Si ha agregado un nuevo campo al índice, vuelva a ejecutar el indexador para que los documentos se procesen en el esquema actualizado. Es posible que los documentos existentes deban volver a procesarse antes de rellenar el nuevo campo.

5. Compruebe el historial de ejecución del indexador: Vaya al indexador en el portal de Azure o use Obtener estado del indexador (API REST) para ver los detalles de ejecución y los mensajes de error.

Errores del indexador y tipos de contenido no admitidos

De forma predeterminada, el indexador de blobs se detiene en cuanto encuentra un blob con un tipo de contenido no admitido, como un archivo de audio. Puede usar el parámetro excludedFileNameExtensions para omitir determinados tipos de contenido.

Si desea que la indexación continúe cuando se produzca un error en algunos documentos, ajuste los parámetros siguientes y, a continuación, investigue los documentos individuales más adelante. Para obtener más información, consulte guía de solución de problemas del indizador y errores y advertencias del indizador.

Cuando se producen errores, cinco parámetros del indexador controlan la respuesta del indexador:

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

Contenido relacionado

• Detección de cambios y detección de eliminación
• Indexación de grandes conjuntos de datos
• Acceso del indizador a contenido protegido por las características de seguridad de red de Azure