Indexer les données d’Azure Database pour MySQL Flexible Server (préversion)

L’indexeur Azure Database pour MySQL (préversion) importe du contenu de Azure Database pour MySQL Serveur flexible dans un index Recherche Azure AI. Les entrées de l’indexeur sont des lignes d’une table ou d’une vue unique. La sortie est un index de recherche avec du contenu pouvant faire l’objet d’une recherche dans des champs individuels.

Cet article complète Créer un indexeur avec des informations spécifiques à l'indexation basée sur Azure Database pour MySQL Flexible Server. Il utilise les API REST pour illustrer un workflow en trois parties commune à tous les indexeurs : créer une source de données, créer un indexeur, créer un indexeur. L’extraction de données se produit lorsque vous envoyez la demande Create Indexer.

Lorsqu'il est configuré pour inclure un seuil maximal et une suppression douce, l'indexeur prend en compte toutes les modifications, les transferts et les suppressions pour votre base de données MySQL. Elle reflète ces modifications dans votre index de recherche. L’extraction de données se produit lorsque vous envoyez la demande Create Indexer.

Conditions préalables

• Remplissez le formulaire d’inscription à l’aperçu de l’indexeur. L’inscription est automatiquement approuvée.

• Serveur flexible Azure Database pour MySQL et exemples 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 complète inclut 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 dispose 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 Kit de développement logiciel (SDK) Azure pour .NET. Vous ne pouvez pas utiliser le portail Azure pour la création d'indexeur, mais vous pouvez gérer les indexeurs et les sources de données une fois qu'ils sont créés.

Limitations de l'aperçu

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

L'aperçu ne prend pas en charge les types géométriques et 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 et 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 pour identifier les modifications apportées aux données. La source de données est définie comme une ressource indépendante afin qu’elle puisse être utilisée par plusieurs indexeurs.

Créer ou mettre à jour la 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 clés :

• Défini type sur "mysql" (obligatoire).

• Définissez credentials sur une chaîne de connexion ADO.NET. Vous trouverez des chaînes de connexion dans le portail Azure, sur la page Chaînes de connexion pour MySQL.

• Assigner container au nom de la table.

• Définissez dataChangeDetectionPolicy si les données sont volatiles et que vous souhaitez que l’indexeur récupère uniquement les éléments nouveaux et mis à jour lors des exécutions suivantes.

• Définissez dataDeletionDetectionPolicy si vous souhaitez supprimer des documents de recherche d’un index de recherche lorsque l’élément source est supprimé.

Créer un index

Créer ou mettre à jour l’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 ce cas, « ID »), l’indexeur importe la clé primaire comme clé de document.

Types de données de mappage

Le tableau suivant établit une correspondance entre la base de données MySQL et les équivalents dans Recherche Azure AI. Pour plus d’informations, consultez Types de données pris en charge (Recherche Azure AI).

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 de temps d’exécution.

Créez ou mettez à jour un indexeur en lui donnant 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 clés :

• Spécifiez des mappages de champs s’il existe des différences dans le nom ou le type de champ, ou si vous avez besoin de plusieurs versions d’un champ source dans l’index de recherche.

• Un indexeur s’exécute automatiquement lors de sa création. Vous pouvez l’empêcher de s’exécuter en définissant disabled sur true. Pour contrôler l’exécution de l’indexeur, exécutez un indexeur à la demande ou placez-le selon une planification.

Vérifier l’état de l’indexeur

Envoyez une demande pour obtenir l'état de l'indexeur afin de surveiller l’exécution de l’indexeur :

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

La réponse inclut l’état et le nombre d’éléments traités. Il 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 des dernières exécutions terminées, triées dans l’ordre chronologique inverse afin que la dernière exécution soit effectuée en premier.

Indexation de lignes nouvelles et modifiées

Une fois qu’un indexeur a rempli entièrement un index de recherche, vous pouvez souhaiter que l’indexeur suivant s’exécute de manière incrémentielle pour indexer uniquement les lignes nouvelles et modifiées de votre base de données.

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

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

La stratégie de détection des modifications d’un indexeur s’appuie sur la présence d’une colonne de jalon 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 avec chaque insertion ou mise à jour.
• Les requêtes avec les clauses suivantes WHEREORDER BY 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 modifications :

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

Indexation des lignes supprimées

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

Étant donné une colonne qui fournit l'état de suppression, un indexeur peut être configuré afin de supprimer tous les documents de recherche pour lesquels l'état de suppression est défini à 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 source de données comme suit :

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

Le softDeleteMarkerValue doit être une chaîne. Par exemple, si vous avez une colonne entière où 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 extrayent du contenu à partir de Azure MySQL :

• Indexer des jeux de données volumineux
• Accès de l'indexeur au contenu protégé par les fonctionnalités de sécurité réseau d'Azure