Indexer des données à partir du serveur flexible Azure Database pour MySQL

Article
12/10/2024

Important

MySQL est pris en charge en préversion publique dans le cadre de Conditions d’utilisation supplémentaires. Vous pouvez utiliser 2020-06-30-preview ou une version ultérieure pour indexer votre contenu. Nous vous recommandons l’API dans la préversion la plus récente. Il n’y a actuellement pas de prise en charge du portail.

Dans cet article, découvrez comment configurer un indexeur qui importe du contenu d’Azure Database pour MySQL et le rend utilisable dans une requête de Azure AI Search. Les entrées de l’indexeur sont votre ligne, dans une seule table ou vue. La sortie est un index de recherche avec du contenu pouvant faire l’objet de recherches dans des champs individuels.

Cet article vient en complément de l’article Créer un indexeur avec des informations spécifiques à l’indexation à partir du serveur flexible Azure Database pour MySQL. Il utilise les API REST pour illustrer un workflow en trois parties commun à tous les indexeurs : créer une source de données, créer un index, créer un indexeur. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Lorsqu’il est configuré pour inclure une limite supérieure et une suppression réversible, l’indexeur prend en compte toutes les modifications, tous les chargements et toutes les suppressions de votre base de données MySQL. Il reflète ces modifications dans votre index de recherche. L’extraction de données se produit quand vous envoyez la demande de création d’un indexeur.

Prérequis

Inscrivez-vous à la préversion pour donner votre avis sur le scénario. Vous pouvez accéder automatiquement à la fonctionnalité après l’envoi du formulaire.
Serveur flexible Azure Database pour MySQL et échantillon de données. Les données doivent résider dans une table ou une vue. Une clé primaire est requise. Si vous utilisez une vue, elle doit avoir une colonne de limite supérieure.
Autorisations de lecture. Une chaîne de connexion accès complet ajoute une clé qui accorde l’accès au contenu, mais si vous utilisez des rôles Azure, vérifiez que l’identité managée du service de recherche a des autorisations de Lecteur sur MySQL.
Un client REST pour créer la source de données, l’index et l’indexeur.

Vous pouvez également utiliser le SDK Azure pour .NET. Vous ne pouvez pas utiliser le portail Azure pour la création d’indexeurs, mais vous pouvez gérer les indexeurs et les sources de données une fois qu’ils sont créés.

Limitations de la version préliminaire

Actuellement, le suivi des modifications et la détection des suppressions ne fonctionnent pas si la date ou le timestamp est uniforme pour toutes les lignes. Cette limitation est un problème connu qui sera traité dans une mise à jour de la préversion. Tant que ce problème n’est pas résolu, n’ajoutez pas d’ensembles de compétences à l’indexeur MySQL.

La préversion ne prend pas en charge les types de géométrie ni les blobs.

Comme indiqué, il n’existe aucune prise en charge du portail pour la création d’indexeur, mais un indexeur MySQL et une source de données peuvent être gérés dans le portail Azure une fois qu’ils existent. Par exemple, vous pouvez modifier les définitions ainsi que réinitialiser, exécuter ou planifier l’indexeur.

Définir la source de données

La définition de la source de données spécifie les données à indexer, les informations d’identification et les stratégies permettant d’identifier les changements de données. La source de données est définie en tant que ressource indépendante de manière à pouvoir être utilisée par plusieurs indexeurs.

Créer ou mettre à jour une source de données spécifie la définition. Veillez à utiliser une API REST en préversion lors de la création de la source de données.

{   
    "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]"
    }
}

Points essentiels :

Définissez type sur "mysql" (obligatoire).
Définissez credentials sur une chaîne de connexion ADO.NET. Vous pouvez rechercher des chaînes de connexion dans Portail Azure, dans la page Chaînes de connexion pour MySQL.
Définissez container sur le nom de la table.
Définissez dataChangeDetectionPolicy si les données sont volatiles et que vous voulez que l’indexeur récupère uniquement les éléments nouveaux et mis à jour pendant les exécutions suivantes.
Définissez dataDeletionDetectionPolicy si vous voulez supprimer les documents de recherche d’un index de recherche quand l’élément source est supprimé.

Création d'un index

Créer ou mettre à jour un index spécifie le schéma d’index :

{
    "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 clé primaire de la table source correspond à la clé de document (dans le cas présent, « ID »), l’indexeur importe la clé primaire en tant que clé de document.

Mappage de types de données

Le tableau suivant mappe la base de données MySQL aux équivalents de Azure AI Search. Pour plus d’informations, consultez Types de données pris en charge (Azure AI Search).

Remarque

La préversion ne prend pas en charge les types de géométrie ni les blobs.

Type de données MySQL	Types de champs 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
données numériques non signées, serial, decimal, dec, bit, blob, binary, geometry	N/A

Configurer et exécuter l’indexeur MySQL

Une fois l’index et la source de données créés, vous êtes prêt à créer l’indexeur. La configuration de l’indexeur spécifie les entrées, les paramètres et les propriétés qui contrôlent les comportements d’exécution.

Créez ou mettez à jour un indexeur en lui attribuant un nom, et en référençant la source de données et l’index cible :

{
    "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
}

Points essentiels :

Spécifiez les mappages de champs s’il existe des différences dans le nom ou le type du champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.
Un indexeur s’exécute automatiquement quand il est créé. Vous pouvez empêcher son exécution en définissant disabled sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le dans une planification.

Vérifier l’état de l’indexeur

Envoyez une requête Obtenir l’état de l’indexeur pour surveiller l’exécution de l’indexeur :

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-05-01-preview
  Content-Type: application/json  
  api-key: [admin key]

La réponse comprend l’état et le nombre d’éléments traités. Le résultat doit ressembler à l’exemple suivant :

{
    "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
    ]
}

L’historique d’exécution contient jusqu’à 50 exécutions les plus récentes, classées par ordre chronologique inversé, la dernière exécution apparaissant en premier.

Indexation des lignes nouvelles et modifiées

Dès qu’un indexeur a entièrement rempli un index de recherche, vous pouvez définir que les exécutions suivantes de l’indexeur indexent de manière incrémentielle uniquement les lignes nouvelles et modifiées dans votre base de données.

Pour activer l’indexation incrémentielle, définissez la propriétédataChangeDetectionPolicy dans la définition de votre source de données. Cette propriété indique à l’indexeur le mécanisme de suivi des changements utilisé sur vos données.

Pour les indexeurs Azure Database pour MySQL, la seule stratégie prise en charge est HighWaterMarkChangeDetectionPolicy.

La stratégie de détection des changements d’un indexeur s’appuie sur une colonne limite supérieure qui capture la version de ligne, ou la date et l’heure de la dernière mise à jour d’une ligne. Il s’agit souvent d’une colonne DATE, DATETIME ou TIMESTAMP avec un niveau de granularité suffisant pour répondre aux exigences d’une colonne de limite supérieure.

Dans votre base de données MySQL, la colonne de limite supérieure doit remplir les exigences suivantes :

Toutes les insertions de données doivent spécifier une valeur pour la colonne.
Toutes les mises à jour d'un élément modifient également la valeur de la colonne.
La valeur de cette colonne augmente à chaque insertion ou mise à jour.
Les requêtes utilisant les clauses WHERE et ORDER BY suivantes peuvent être exécutées efficacement : WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

L’exemple suivant montre une définition de source de données avec une stratégie de détection des changements :

{
    "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]"
    }
}

Important

Si vous utilisez une vue, vous devez définir une stratégie de limite supérieure dans la source de données de votre indexeur.

Si la table source n’a pas d’index sur la colonne de limite supérieure, le délai d’attente des requêtes utilisées par l’indexeur MySQL peut expirer. En particulier, la clause ORDER BY [High Water Mark Column] requiert qu’un index s’exécute efficacement lorsque la table contient de nombreuses lignes.

Indexation des lignes supprimées

Quand des lignes sont supprimées de la table ou de la vue, vous devez normalement supprimer également ces lignes de l’index de recherche. Toutefois, si les lignes sont physiquement supprimées de la table, l’indexeur n’a aucun moyen de déduire la présence d’enregistrements qui n’existent plus. La solution est d’utiliser la technique de suppression réversible pour supprimer logiquement les lignes sans les supprimer de la table. Ajoutez une colonne à votre table ou votre vue et marquez les lignes comme supprimées à l’aide de cette colonne.

Avec une colonne qui fournit l’état de suppression, l’indexeur peut être configuré pour supprimer tous les documents de recherche dont l’état de suppression est défini sur true. La propriété de configuration qui prend en charge ce comportement est une stratégie de détection de suppression de données, qui est spécifiée dans la définition de la source de données, de la façon suivante :

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

La softDeleteMarkerValue doit être une chaîne. Par exemple, si vous avez une colonne d’entiers dans laquelle les lignes supprimées sont marquées avec la valeur 1, utilisez "1". Si vous avez une colonne BIT dans laquelle les lignes supprimées sont marquées avec la valeur booléenne True, utilisez le littéral de chaîne True ou true (la casse est sans importance).

Étapes suivantes

Vous pouvez maintenant exécuter l’indexeur, surveiller l’état ou planifier l’exécution de l’indexeur. Les articles suivants s’appliquent aux indexeurs qui tirent du contenu d’Azure MySQL :

Partager via