Compartir a través de

Indexación de datos de Azure Files

  • Artículo

Importante

El indexador de Azure Files se encuentra actualmente en versión preliminar pública según los Términos de uso complementarios. Use una API de REST versión preliminar para crear el origen de datos del indexador.

En este artículo, aprenderá a configurar un indexador que importa contenido de Azure Files y hace que se pueda buscar en Azure AI Search. Las entradas en el indexador son los archivos, en un solo recurso compartido. La salida es un índice de búsqueda con contenido que se puede buscar y metadatos almacenados en campos individuales.

Este artículo complementa el artículo Creación de un indexador con información específica sobre la indexación de archivos de Azure 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.

Requisitos previos

Formatos de documento admitidos

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

Cómo se indexan Azure Files

De manera 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 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.

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.

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

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

    POST /datasources?api-version=2024-05-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 "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 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 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 recurso compartido de archivos mediante las siguientes conexiones.

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.

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

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

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

    POST /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_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). Para el contenido de los blobs, 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) es la ruta de acceso completa al objeto o archivo

    • metadata_storage_name utilizable solo si los nombres son únicos

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

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

  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): 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): 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 tal como especifica el código que usó para cargar el archivo. Por ejemplo, application/octet-stream.
    • metadata_storage_last_modified (Edm.DateTimeOffset): última marca de tiempo modificada del archivo. Azure AI Search usa esta marca de tiempo para identificar los archivos modificados, con el fin de no tener que volver a indexar todo después de la indexación inicial.
    • metadata_storage_size (Edm.Int64): tamaño del 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 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.

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

    POST /indexers?api-version=2024-07-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 "configuration", proporcione los criterios de inclusión o exclusión. Si se deja sin especificar, se recuperan todos los archivos del recurso compartido de archivos.

    Si los parámetros indexedFileNameExtensions y excludedFileNameExtensions están presentes, Azure AI Search mira primero en indexedFileNameExtensions y, luego, en excludedFileNameExtensions. Si la misma extensión de archivo está en las dos listas, se excluirá de la indexación.

  3. 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 archivos, 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.

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

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

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: