Indexación de datos del Servidor flexible de Azure Database for MySQL

Artículo
03/11/2024

Importante

La compatibilidad con MySQL se encuentra actualmente en versión preliminar pública según los Términos de uso complementarios. Use una API REST en versión preliminar (2020-06-30-preview o posterior) para indexar el contenido. Actualmente no se presta soporte técnico para el portal.

En este artículo, aprenderá a configurar un indexador que importa contenido desde Azure Database for MySQL y hace que se pueda buscar en Azure AI Search. Las entradas del indexador son las filas, en una única tabla o vista. La salida es un índice de búsqueda con contenido que se puede buscar en campos individuales.

En este artículo se complementa la Creación de un indexador con información específica de la indexación desde el Servidor flexible de Azure Database for MySQL. 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.

Si se configura para incluir un límite máximo y eliminación temporal, el indexador realiza todos los cambios, las cargas y las eliminaciones de la base de datos MySQL. Refleja estos cambios en el índice de búsqueda. La extracción de datos se produce cuando se envía la solicitud para crear un indexador.

Requisitos previos

Regístrese para obtener la versión preliminar y proporcionar comentarios sobre escenarios. Puede acceder a la característica automáticamente después del envío del formulario.
Servidor flexible de Azure Database for MySQL y datos de ejemplo. Los datos deben residir en una tabla o vista. Se requiere una clave principal. Si usa una vista, debe tener una columna de límite máximo.
Permisos de lectura. Una cadena de conexión de acceso completo incluye una clave que concede acceso al contenido, pero si usa roles de Azure, asegúrese de que la identidad administrada del servicio de búsqueda disponga de permisos de Lector en MySQL.
Un cliente de REST para crear el origen de datos, el índice y el indexador.

También puede usar el SDK de Azure para .NET. No puede usar el portal para la creación de indexadores, pero puede administrar los indexadores y los orígenes de datos una vez creados.

Limitaciones de vista previa

Actualmente el seguimiento de cambios y la detección de eliminaciones no funcionan si la fecha o la marca de tiempo es uniforme en todas las filas. La limitación es un problema conocido que se solucionará en una actualización de la versión preliminar. Hasta que se solucione este problema, no agregue ningún conjunto de aptitudes al indexador MySQL.

La versión preliminar no admite tipos de geometría ni blobs.

Como se ha indicado, no hay compatibilidad con el portal para la creación de indexadores, pero un indexador y un origen de datos MySQL ya existentes sí se pueden administrar en el portal. Por ejemplo, puede editar las definiciones y restablecer, ejecutar o programar el indexador.

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. El origen de datos se define como un recurso independiente para que puedan usarlo múltiples indizadores.

Crear o actualizar origen de datos especifica la definición. Asegúrese de usar una versión preliminar de la API de REST (2020-06-30-Preview o posterior) al crear el origen de datos.

{   
    "name" : "hotel-mysql-ds",
    "description" : "[Description of MySQL data source]",
    "type" : "mysql",
    "credentials" : { 
        "connectionString" : 
            "Server=[MySQLServerName].MySQL.database.azure.com; Port=3306; Database=[DatabaseName]; Uid=[UserName]; Pwd=[Password]; SslMode=Preferred;" 
    },
    "container" : { 
        "name" : "[TableName]" 
    },
    "dataChangeDetectionPolicy" : { 
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "[HighWaterMarkColumn]"
    }
}

Puntos clave:

Establezca type en "mysql" (obligatorio).
Establezca credentials en una cadena de conexión de ADO.NET. Puede encontrar cadenas de conexión en Azure Portal, en la página Cadenas de conexión de MySQL.
Establezca container en el nombre de la tabla.
Establezca dataChangeDetectionPolicy si los datos son volátiles y desea que el indexador seleccione solo los elementos nuevos y actualizados en ejecuciones posteriores.
Establezca dataDeletionDetectionPolicy si desea quitar documentos de búsqueda de un índice de búsqueda cuando se elimine el elemento de origen.

Creación de un índice

Crear o actualizar índice especifica el esquema de índice:

{
    "name" : "hotels-mysql-ix",
    "fields": [
        { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
        { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false },
        { "name": "Category", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
        { "name": "City", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },
        { "name": "Description", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false  }     
    ]
}

Si la clave principal de la tabla de origen coincide con la clave de documento (en este caso, "ID"), el indexador importa la clave principal como clave de documento.

Tipos de datos de asignación

En la tabla siguiente se asigna la base de datos MySQL a equivalentes de Azure AI Search. Para obtener más información, consulte Tipos de datos admitidos (Azure AI Search).

Nota:

La versión preliminar no admite tipos de geometría ni blobs.

Tipos de datos de MySQL	Tipos de campos de Azure AI Search
`bool`, `boolean`	Edm.Boolean, Edm.String
`tinyint`, `smallint`, `mediumint`, `int`, `integer`, `year`	Edm.Int32, Edm.Int64, Edm.String
`bigint`	Edm.Int64, Edm.String
`float`, `double`, `real`	Edm.Double, Edm.String
`date`, `datetime`, `timestamp`	Edm.DateTimeOffset, Edm.String
`char`, `varchar`, `tinytext`, `mediumtext`, `text`, `longtext`, `enum`, `set`, `time`	Edm.String
unsigned numerical data, serial, decimal, dec, bit, blob, binary, geometry	N/D

Configuración y ejecución del indexador de MySQL

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.

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

{
    "name" : "hotels-mysql-idxr",
    "dataSourceName" : "hotels-mysql-ds",
    "targetIndexName" : "hotels-mysql-ix",
    "disabled": null,
    "schedule": null,
    "parameters": {
        "batchSize": null,
        "maxFailedItems": null,
        "maxFailedItemsPerBatch": null,
        "base64EncodeKeys": null,
        "configuration": { }
        },
    "fieldMappings" : [ ],
    "encryptionKey": null
}

Puntos clave:

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.
Un indexador se ejecuta automáticamente cuando se crea. Puede evitar que se ejecute si establece 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

Envíe una solicitud Get Indexer Status para supervisar la ejecución 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":"2024-02-21T00:23:24.957Z",
        "endTime":"2024-02-21T00:36:47.752Z",
        "errors":[],
        "itemsProcessed":1599501,
        "itemsFailed":0,
        "initialTrackingState":null,
        "finalTrackingState":null
    },
    "executionHistory":
    [
        {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-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).

Indexación de filas nuevas y modificadas

Una vez que un indexador ha rellenado por completo un índice de búsqueda, es posible que desee que las ejecuciones posteriores del indexador indexen incrementalmente solo las filas nuevas y modificadas de la base de datos.

Para habilitar la indexación incremental, establezca la propiedad dataChangeDetectionPolicy en la definición del origen de datos. Esta propiedad indica al indexador qué mecanismo de seguimiento de cambios se usa en los datos.

En el caso de los indexadores de Azure Database for MySQL, la única directiva admitida es HighWaterMarkChangeDetectionPolicy.

La directiva de detección de cambios de un indexador se basa en tener una columna de límite máximo que capture la versión de fila o la fecha y hora en que se actualizó por última vez una fila. Suele ser una columna DATE, DATETIME o TIMESTAMP con una granularidad suficiente para cumplir los requisitos de una columna de límite máximo.

En la base de datos de MySQL, la columna de límite máximo debe cumplir los siguientes requisitos:

Todas las inserciones de datos deben especificar un valor para la columna.
Todas las actualizaciones de un elemento también cambian el valor de la columna.
El valor de esta columna aumenta con cada inserción o actualización.
Las consultas con las cláusulas WHERE y ORDER BY siguientes se pueden ejecutar de forma eficaz: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

En el ejemplo siguiente se muestra una definición de origen de datos con una directiva de detección de cambios:

{
    "name" : "[Data source name]",
    "type" : "mysql",
    "credentials" : { "connectionString" : "[connection string]" },
    "container" : { "name" : "[table or view name]" },
    "dataChangeDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName" : "[last_updated column name]"
    }
}

Importante

Si usa una vista, debe establecer una directiva de límite máximo en el origen de datos del indexador.

Si la tabla de origen no tiene un índice en la columna de límite superior, las consultas utilizadas por el indexador MySQL pueden agotar el tiempo de espera. En concreto, la cláusula ORDER BY [High Water Mark Column] requiere un índice para ejecutarse de forma eficaz cuando la tabla contiene muchas filas.

Indexación de las filas eliminadas

Cuando se eliminan filas de la tabla o la vista, lo habitual es que también se quieran eliminar esas filas del índice de búsqueda. Sin embargo, si las filas se quitaron físicamente de la tabla, un indexador no tiene forma de deducir la presencia de registros que ya no existen. La solución pasa por usar una técnica de eliminación temporal para eliminar filas de forma lógica sin quitarlas de la tabla. Agregue una columna a la tabla o vista y marque filas como eliminadas mediante esa columna.

Dada una columna que proporciona el estado de eliminación, se puede configurar un indexador para quitar cualquier documento de búsqueda cuyo estado de eliminación esté establecido en true. La propiedad de configuración que admite este comportamiento es una directiva de detección de eliminación de datos, que se especifica en la definición del origen de datos de la siguiente manera:

{
    …,
    "dataDeletionDetectionPolicy" : {
        "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName" : "[a column name]",
        "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
    }
}

softDeleteMarkerValue debe ser una cadena. Por ejemplo, si tiene una columna de enteros donde las filas eliminadas se marcan con el valor 1, use "1". Si tiene una columna BIT donde las filas eliminadas se marcan con el valor booleano true, use el literal de cadena True o true, no importan las mayúsculas y minúsculas.

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