Indexación de datos de Azure Table Storage

Artículo
02/22/2024

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

Azure Table Storage
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 concede acceso al contenido, pero si usted usa roles de Azure, asegúrese de que la identidad administrada del servicio de búsqueda disponga de permisos de datos y lector.
Use un cliente REST para formular llamadas REST similares a las que se muestran en este artículo.

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=2023-11-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 000 a 100, 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=2023-11-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 1 y el valor RowKey es 1_123, el valor de la clave es 11_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, el 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=2023-11-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,
        "base64EncodeKeys" : 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, envíe una solicitud para Obtener el estado del indexador:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-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":"2023-02-21T00:23:24.957Z",
            "endTime":"2023-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2023-02-21T00:23:24.957Z",
                "endTime":"2023-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

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: