Indexar datos de Azure Files (versión preliminar)

El indexador Azure Files (versión preliminar) importa contenido de un recurso compartido de archivos en un índice de Búsqueda de Azure AI. Las entradas en el indexador son los archivos, en un solo recurso compartido. La salida es un índice de búsqueda con contenido y metadatos que se pueden buscar almacenados en campos individuales.

Para configurar y ejecutar el indexador, puede usar:

• API de REST de la versión preliminar del servicio Search, cualquier versión preliminar.
• Un paquete SDK de Azure, cualquier versión.
• Asistente de importación de datos en el portal de Azure.

Requisitos previos

• Azure Files, nivel Optimizado para transacciones.

• Un compartido de archivos SMB que proporciona el contenido fuente. No se admiten recursos compartidos NFS.

• Archivos que contienen texto. Si tiene datos binarios, puede incluir el enriquecimiento con IA para el análisis de imágenes.

• Los archivos de origen procesados por el indexador de Azure Files aplican los límites compartidos de tamaño de archivo de origen y de caracteres extraídos para los indexadores similares a los de blobs.

• Permisos de lectura en Azure Storage. Una cadena de conexión de "acceso total" incluye una clave que concede acceso al contenido.

• 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 de tablas. 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 metadatos personalizados.
• La inteligencia artificial aplicada a través de conjuntos de aptitudes:los conjuntos de aptitudes son totalmente compatibles con el indexador. Esto incluye características clave como la vectorización integrada que agrega pasos de fragmentación e inserción de datos.
• Modos de análisis: El indexador 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 está diseñado para funcionar sin problemas con otras características del indexador, como sesiones de depuración, caché del indexador para enriquecimientos incrementales y almacén de conocimiento.

Formatos de documento admitidos

El indizador de Azure Files puede extraer texto de los siguientes formatos de documento:

• CSV (consulte Indexación de blobs CSV)
• EML
• EPUB
• GZ
• HTML
• JSON (consulte Indexación de blobs JSON)
• KML (XML para representaciones geográficas)
• Markdown
• Microsoft Office formatos: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook correos electrónicos), XML (tanto 2003 como 2006 WORD XML)
• Abrir formatos de documento: ODT, ODS, ODP
• PDF
• Archivos de texto sin formato (consulte también Indexación de texto sin formato)
• RTF
• XML
• ZIP

Cómo se indexan los Azure Files

De forma predeterminada, la mayoría de los archivos se indexan como un único documento de búsqueda en el índice, incluidos los archivos con contenido estructurado, como JSON o CSV, que se indexan como un único fragmento de texto.

Un documento compuesto o incrustado (como un archivo ZIP, un documento Word con Outlook correo electrónico incrustado que contiene datos adjuntos o . El archivo MSG con datos adjuntos) también se indexa como un único 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 enriquecimiento con IA para obtener más utilidad de búsqueda 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.

Definición del origen de datos

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

Puede usar 2020-06-30-preview o posterior para "type": "azurefile". Se recomienda la API de versión preliminar más reciente.

1. Cree un origen de datos para establecer su definición mediante una API en versión preliminar para "type": "azurefile".

   POST /datasources?api-version=2026-08-01-preview
   {
       "name" : "my-file-datasource",
       "type" : "azurefile",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
   }
   

2. Establezca "type" en "azurefile" (obligatorio).

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

4. Establezca "container" en el recurso compartido de archivos raíz y use "query" para especificar las subcarpetas.

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

Credenciales admitidas y cadenas de conexión

Los indexadores pueden conectarse a un recurso compartido de archivos mediante las siguientes conexiones.

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

En el índice search, agregue campos para aceptar el contenido y los metadatos de los archivos de Azure.

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

   POST /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_path", "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": true, "filterable": true, "sortable": true }        
     ]
   }
   

2. Cree un campo de clave de documento ("key": true). En el caso del contenido del blob, los mejores candidatos son las propiedades de metadatos. 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.

   • metadata_storage_path (valor predeterminado) ruta de acceso completa al objeto o archivo

   • metadata_storage_name solo se puede usar si los nombres son únicos

   • Propiedad de metadatos personalizada que tú añades a los blobs. Esta opción requiere que el proceso de carga de blobs agregue esa propiedad de metadatos a todos los blobs. Dado que la clave es una propiedad necesaria, los blobs que carezcan de un valor 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.

3. Agregue un campo "content" para almacenar texto extraído de cada archivo a través de la propiedad "content" del blob. No es obligatorio usar este nombre, pero hacerlo permite aprovechar las asignaciones de campos implícitas.

4. Agregue campos para las propiedades de metadatos estándar. En la indexación de archivos, las propiedades de metadatos estándar son las mismas que las propiedades de metadatos de blob. El indexador de Azure Files crea automáticamente asignaciones de campos internas para estas propiedades que convierten los nombres de propiedad con guion en nombres de propiedad con subrayado. Todavía tiene que agregar los campos que quiere usar para la definición de índice, pero puede omitir la creación de asignaciones de campos en el origen de datos.

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

Configuración y ejecución del indexador de Azure Files

Una vez creado el índice y el origen de datos, está listo para crear el indexador. La configuración del indexador especifica las entradas, los parámetros y las propiedades que controlan los comportamientos de tiempo de ejecución.

1. Cree o actualice un indexador ; para ello, asígnele un nombre y haga referencia al origen de datos y al índice de destino:

   POST /indexers?api-version=2026-04-01
   {
     "name" : "my-file-indexer",
     "dataSourceName" : "my-file-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "configuration": {
           "indexedFileNameExtensions" : ".pdf,.docx",
           "excludedFileNameExtensions" : ".png,.jpeg" 
       }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. En la sección opcional "configuración", proporcione cualquier criterio de inclusión o exclusión. Si no se especifica, se recuperan todos los archivos de la compartición de archivos.

   Si ambos parámetros indexedFileNameExtensions y excludedFileNameExtensions están presentes, Búsqueda de Azure AI examina primero indexedFileNameExtensions, a continuación, en excludedFileNameExtensions. Si la misma extensión de archivo está presente en ambas listas, se excluirá de la indexación.

3. Especifique las 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 archivos, a menudo puede omitir las asignaciones de campos porque el indexador tiene compatibilidad integrada para asignar las propiedades de metadatos y "contenido" a campos con nombre y tipados de forma similar 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.

4. Consulte Creación de un indexador para obtener más información sobre otras propiedades.

Un indexador se ejecuta automáticamente cuando se crea. Para evitarlo, establezca "disabled" en true. Para controlar la ejecución del indexador, ejecute un indexador a petición o colóquelo según una programación.

Comprobación del estado del indexador

Para supervisar el estado del indexador y el historial de ejecución, envíe una solicitud Obtener 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. Debería ser similar al ejemplo siguiente:

    {
        "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, que se ordenan en el orden cronológico inverso para que la ejecución más reciente llegue primero.

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:

• Detección de cambios y detección de eliminación
• Indexación de grandes conjuntos de datos