Indexación de datos de Azure Table Storage
En este artículo, aprenderá a configurar un indexador que importa contenido de Azure Table Storage y hace que se pueda buscar en Azure AI Search. Las entradas en el indexador son las entidades, en una sola tabla. La salida es un índice de búsqueda con contenido que se puede buscar y metadatos almacenados en campos individuales.
Este artículo complementa Creación de un indexador con información específica sobre la indexación desde Azure Table Storage. Usa Azure Portal y las API de REST para demostrar 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
Tablas que contienen texto. Si tiene datos binarios, considere la posibilidad de usar el enriquecimiento con IA para analizar imágenes.
Permisos de lectura en Azure Storage. Una cadena de conexión de «acceso completo» incluye una clave que da acceso al contenido, pero si usa roles de Azure, asegúrese de que la identidad administrada del servicio de búsqueda tenga permisos de Lector y Acceso a datos.
Para trabajar con los ejemplos de este artículo, necesita Azure Portal o un Cliente REST. Si usa Azure Portal, asegúrese de que el acceso a todas las redes públicas está habilitado. Otros enfoques para crear un indexador de tablas de Azure incluyen SDK de Azure.
Pruebe con datos de ejemplo
Siga estas instrucciones para crear una tabla en Azure Storage con fines de prueba.
Inicie sesión en Azure Portal, vaya a la cuenta de almacenamiento y cree una tabla denominada hoteles.
Descargue HotelsData_toAzureSearch.csv desde GitHub. Este archivo es un subconjunto del conjunto de datos de ejemplo de hoteles integrados. Omite la colección rooms, las descripciones traducidas y las coordenadas geográficas.
En el Explorador de Azure Storage, inicie sesión en Azure, seleccione la suscripción y a continuación, seleccione la cuenta de almacenamiento.
Abra Tablas y seleccione hoteles.
Seleccione Importar en la barra de comandos y a continuación, seleccione el archivo HotelsData_toAzureSearch.csv.
Acepte los valores predeterminados. Seleccione Importar para cargar los datos.
Debe tener 50 registros de hotel en la tabla con una partitionKey, rowKey y marca de tiempo generada automáticamente. Ahora puede usar este contenido para la indexación en Azure Portal, el cliente REST o un SDK de Azure.
El campo Descripción proporciona el contenido más detallado. Debe dirigirse a este campo para la búsqueda de texto completo y las consultas vectoriales opcionales.
Uso de Azure Portal
Puede usar el Asistente de Importación de datos o el Asistente de Importación y vectorización de datos para automatizar la indexación desde una tabla o vista de base de datos SQL. La configuración del origen de datos es similar para ambos asistentes.
En Conectarse a los datos, seleccione o compruebe que el tipo de origen de datos sea Azure Table Storage o que los campos de selección de datos pidan tablas.
El nombre del origen de datos hace referencia al objeto de conexión del origen de datos en Búsqueda de Azure AI. Si usa el asistente para vectores, el nombre del origen de datos se genera automáticamente mediante un prefijo personalizado especificado al final del flujo de trabajo del asistente.
Especifique la cuenta de almacenamiento y el nombre de la tabla. La consulta es opcional. Resulta útil si tiene columnas específicas que desea importar.
Especifique un método de autenticación, ya sea una identidad administrada o una clave de API integrada. Si no especifica una conexión de identidad administrada, Azure Portal usa la clave.
Si configurar la Búsqueda de Azure AI para que use una identidad administrada, y cree una asignación de roles en Azure Storage que conceda permisos Lector y acceso a datos a la identidad, el indexador puede conectarse al almacenamiento de tablas mediante Microsoft Entra ID y los roles.
Para el asistente Importar y vectorizar datos, puede especificar opciones para la detección de eliminación,
La detección de eliminación requiere que tenga un campo preexistente en la tabla que se pueda usar como marca de eliminación temporal. Debe ser un campo booleano (podría asignarle el nombre IsDeleted). Especifique
truecomo valor de eliminación temporal. En el índice de búsqueda, agregue un campo de búsqueda correspondiente denominado IsDeleted establecido en recuperable y filtrable.Continúe con los pasos restantes para completar el asistente:
Usar las API REST
En esta sección se muestran las llamadas a la API de REST que crean un origen de datos, un índice y un indexador.
Definición del origen de datos
La definición del origen de datos especifica los datos de origen que se van a indexar, las credenciales y las directivas para la detección de cambios. Un origen de datos es un recurso independiente que varios indexadores pueden usar.
Cree o actualice un origen de datos para establecer su definición:
POST https://[service name].search.windows.net/datasources?api-version=2024-07-01 { "name": "my-table-storage-ds", "description": null, "type": "azuretable", "subtype": null, "credentials": { "connectionString": "DefaultEndpointsProtocol=https;AccountName=<account name>" }, "container": { "name": "my-table-in-azure-storage", "query": "" }, "dataChangeDetectionPolicy": null, "dataDeletionDetectionPolicy": null, "encryptionKey": null, "identity": null }Establezca "type" en
"azuretable"(obligatorio).Establezca "credentials" en una cadena de conexión de Azure Storage. En la sección siguiente se describen los formatos admitidos.
Establezca "contenedor" en el nombre de la tabla.
Opcionalmente, establezca "query" en un filtro en PartitionKey. Establecer esta propiedad es un procedimiento recomendado que mejora el rendimiento. Si "query" es null, el indexador ejecutará un recorrido de tabla completo, lo que puede dar lugar a un rendimiento deficiente si las tablas son grandes.
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 una tabla 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. |
| 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 las tablas y entidades. |
| 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. Cuando expiren las credenciales SAS, 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".
Partición para mejorar el rendimiento
De forma predeterminada, Azure AI Search usa el siguiente filtro de consulta interno para realizar un seguimiento de las entidades de origen que se han actualizado desde la última ejecución: Timestamp >= HighWaterMarkValue. Como las tablas de Azure no tienen un índice secundario en el campo Timestamp, este tipo de consulta requiere un examen de toda la tabla y, por tanto, es lento para tablas grandes.
Para evitar un examen completo, puede usar particiones de tabla para restringir el ámbito de cada trabajo de indexador.
Si los datos se pueden dividir de forma natural en varios intervalos de partición, cree un origen de datos y un indexador correspondiente para cada intervalo de partición. Cada indexador tiene que procesar solo un intervalo de partición concreto, lo que mejora el rendimiento de las consultas. Si los datos que hay que indexar tienen un número pequeño de particiones fijas, aún mejor: cada indexador solo realiza el examen de una partición.
Por ejemplo, para crear un origen de datos para procesar un intervalo de partición con las claves de
000a100, utilice una consulta como esta:"container" : { "name" : "my-table", "query" : "PartitionKey ge '000' and PartitionKey lt '100' " }.Si los datos se dividen por tiempo (por ejemplo, se crea una partición cada día o semana), considere el siguiente enfoque:
En la definición del origen de datos, especifique una consulta similar al ejemplo siguiente:
(PartitionKey ge <TimeStamp>) and (other filters).Supervise el progreso del indexador mediante la API de obtención del estado del indexador y actualice periódicamente la condición
<TimeStamp>de la consulta según el valor alto correcto de la marca de agua más reciente.Con este enfoque, si necesita desencadenar una reindexación completa, restablezca la consulta del origen de datos además de restablecer el indexador.
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 las entidades de tabla.
Cree o actualice un índice para definir campos de búsqueda que almacenarán el contenido de entidades:
POST https://[service name].search.windows.net/indexes?api-version=2024-07-01 { "name" : "my-search-index", "fields": [ { "name": "Key", "type": "Edm.String", "key": true, "searchable": false }, { "name": "SomeColumnInMyTable", "type": "Edm.String", "searchable": true } ] }Cree un campo de clave de documento ("clave": true), pero permita que el indexador lo rellene automáticamente. Un indexador de tabla rellena el campo de clave con claves de partición y fila concatenadas de la tabla. Por ejemplo, si el valor PartitionKey de una fila es
1y el valor RowKey es1_123, el valor de la clave es11_123. Si la clave de partición es NULL, solo se usa la clave de fila.Si usa el Asistente para importar datos para crear el índice, Azure Portal deduce un campo "Clave" para el índice de búsqueda y usa una asignación de campos implícita para conectar los campos de origen y destino. No tiene que agregar el campo por sus propios medios ni es necesario configurar ninguna asignación de campos.
Si usa las API de REST y quiere asignaciones de campos implícitas, cree y asigne el nombre al campo de clave de documento "Clave" en la definición del índice de búsqueda, tal como se muestra en el paso anterior (
{ "name": "Key", "type": "Edm.String", "key": true, "searchable": false }). El indexador rellena automáticamente el campo "Clave", sin asignaciones de campos necesarias.Si no desea un campo denominado "Clave" en el índice de búsqueda, agregue una asignación de campos explícita en la definición del indexador con el nombre de campo que desee, estableciendo el campo de origen en "Clave":
"fieldMappings" : [ { "sourceFieldName" : "Key", "targetFieldName" : "MyDocumentKeyFieldName" } ]Ahora agregue cualquier otro campo de entidad que desee en el índice. Por ejemplo, si una entidad es similar al ejemplo siguiente, el índice de búsqueda debe tener campos para HotelName, Description y Category para recibir esos valores.
El uso de los mismos nombres y tipos de datos compatibles minimiza la necesidad de asignaciones de campos. Cuando los nombres y los tipos son los mismos, el indexador puede determinar automáticamente la ruta de acceso de datos.
Configuración y ejecución del indexador de tablas
Una vez que tenga un índice y un origen de datos, estará listo para 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.
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-table-indexer", "dataSourceName" : "my-table-storage-ds", "targetIndexName" : "my-search-index", "disabled": null, "schedule": null, "parameters" : { "batchSize" : null, "maxFailedItems" : null, "maxFailedItemsPerBatch" : null, "configuration" : { } }, "fieldMappings" : [ ], "cache": null, "encryptionKey": null }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. El campo Destino es el nombre del campo en el índice de búsqueda.
"fieldMappings" : [ { "sourceFieldName" : "Description", "targetFieldName" : "HotelDescription" } ]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, compruebe el historial de ejecución del indexador en Azure Portal, o envíe una API de RESTObtener estado del indexador
En la página del servicio de búsqueda, abra Administración de búsqueda>indexadores.
Seleccione un indexador para acceder al historial de configuración y ejecución.
Seleccione un trabajo de indexador específico para ver detalles, advertencias y errores.
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
Obtenga más información sobre cómo ejecutar el indexador, supervisar el estadoo programar la ejecución del indexador. Los artículos siguientes se aplican a los indexadores que extraen contenido de Azure Storage: