Indicizzare i dati dal server flessibile di Database di Azure per MySQL

Questo articolo illustra come configurare un indicizzatore che importa contenuto da Database di Azure per MySQL e lo rende ricercabile in Azure AI Search. Gli input per l'indicizzatore sono le righe, in una singola tabella o vista. L'output è un indice di ricerca con contenuto ricercabile in singoli campi.

Questo articolo integra Creare un indicizzatore con informazioni specifiche per l'indicizzazione dal server flessibile di Database di Azure per MySQL. Usa le API REST per illustrare un flusso di lavoro in tre passaggi comune a tutti gli indicizzatori: creare un'origine dati, creare un indice, creare un indicizzatore. L'estrazione di dati avviene all'invio della richiesta Crea indicizzatore.

Se è configurato per includere un limite massimo e l'eliminazione temporanea, l'indicizzatore acquisisce tutte le modifiche, i caricamenti e le eliminazioni per il database MySQL. Riflette queste modifiche nell'indice di ricerca. L'estrazione di dati avviene all'invio della richiesta Crea indicizzatore.

Prerequisiti

• Registrarsi per l'anteprima per fornire feedback sullo scenario. È possibile accedere automaticamente alla funzionalità dopo l'invio del modulo.

• Server flessibile di Database di Azure per MySQL e dati di esempio. I dati devono trovarsi in una tabella o in una vista. È necessaria una chiave primaria. Se si usa una vista, è necessario avere una colonna del limite massimo.

• Autorizzazioni di lettura. Una stringa di connessione per l'accesso completo include una chiave che concede l'accesso al contenuto, ma se si usano i ruoli di Azure, assicurarsi che l'identità gestita del servizio di ricerca abbia le autorizzazioni di lettura in MySQL.

• Un client REST per creare l'origine dati, l'indice e l'indicizzatore.

  È anche possibile usare Azure SDK per .NET. Non è possibile usare il portale di Azure per la creazione dell'indicizzatore, ma è possibile gestire indicizzatori e origini dati dopo la creazione.

Limiti dell'anteprima

Attualmente, il rilevamento delle modifiche e il rilevamento dell'eliminazione non funzionano se la data o il timestamp è uniforme per tutte le righe. Questa limitazione è un problema noto che verrà risolto in un aggiornamento dell'anteprima. Finché questo problema non viene risolto, non aggiungere un set di competenze all'indicizzatore MySQL.

L'anteprima non supporta tipi geometria e BLOB.

Come indicato, non esiste alcun supporto del portale per la creazione dell'indicizzatore, ma un indicizzatore MySQL e un'origine dati possono essere gestiti nel portale di Azure una volta esistenti. Ad esempio, è possibile modificare le definizioni e reimpostare, eseguire o pianificare l'indicizzatore.

Definire l'origine dati

La definizione dell'origine dati specifica i dati da indicizzare, le credenziali e i criteri per identificare le modifiche nei dati. L'origine dati è definita come risorsa indipendente affinché possa essere usata da più indicizzatori.

Creare o aggiornare l'origine dati specifica la definizione. Assicurarsi di usare un'API REST di anteprima durante la creazione dell'origine dati.

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

Punti principali:

• Impostare type su "mysql" (obbligatorio).

• Impostare credentials su una stringa di connessione ADO.NET. Le stringhe di connessione sono disponibili nel portale di Azure nella pagina Stringhe di connessione per MySQL.

• Impostare container sul nome della tabella.

• Impostare dataChangeDetectionPolicy se i dati sono volatili e si vuole che l'indicizzatore recuperi solo gli elementi nuovi e aggiornati nelle esecuzioni successive.

• Impostare dataDeletionDetectionPolicy se si vogliono rimuovere i documenti di ricerca da un indice di ricerca quando l'elemento di origine viene eliminato.

Creare un indice

Creare o aggiornare indici specifica lo schema dell'indice:

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

Se la chiave primaria nella tabella di origine corrisponde alla chiave del documento (in questo caso "ID"), l'indicizzatore importa la chiave primaria come chiave del documento.

Mapping di tipi di dati

La tabella seguente definisce il mapping tra il database MySQL e gli equivalenti di Azure AI Search. Per altre informazioni, vedere Tipi di dati supportati (Azure AI Search).

Configurare ed eseguire l'indicizzatore MySQL

Dopo aver creato l'indice e l'origine dati, è possibile creare l'indicizzatore. La configurazione dell'indicizzatore specifica gli input, i parametri e le proprietà che controllano i comportamenti della fase di esecuzione.

Creare o aggiornare l'indicizzatore assegnandogli un nome e il riferimento all’origine dati e all'indice di destinazione:

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

Punti principali:

• Specificare i mapping dei campi se sono presenti differenze nel nome o nel tipo di campo oppure se sono necessarie più versioni di un campo di origine nell'indice di ricerca.

• Un indicizzatore viene eseguito automaticamente al momento della sua creazione. È possibile impedirne l'esecuzione impostando disabled su true. Per controllare l'esecuzione dell'indicizzatore, eseguire un indicizzatore su richiesta o inserirlo in una pianificazione.

Controllare lo stato dell'indicizzatore

Inviare una richiesta per ottenere lo stato dell'indicizzatore per monitorare l'esecuzione dell'indicizzatore:

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

La risposta include lo stato e il numero di elementi elaborati. Dovrebbe risultare simile all'esempio seguente:

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

La cronologia di esecuzione contiene fino a 50 delle ultime completate, ordinate in ordine cronologico inverso in modo che l'esecuzione più recente venga visualizzata per prima.

Indicizzazione di righe nuove e modificate

Dopo che un indicizzatore ha popolato completamente un indice di ricerca, può essere utile che le esecuzioni successive indicizzino in modo incrementale solo le righe nuove e modificate nel database.

Per abilitare l'indicizzazione incrementale, impostare la proprietà dataChangeDetectionPolicynella definizione dell'origine dati. Questa proprietà indica all'indicizzatore quale meccanismo di rilevamento delle modifiche viene usato sui dati.

Per gli indicizzatori di Database di Azure per MySQL, l'unico criterio supportato è HighWaterMarkChangeDetectionPolicy.

I criteri di rilevamento delle modifiche di un indicizzatore si basano sulla presenza di una colonna del limite massimo che acquisisce la versione o la data e l'ora dell'ultimo aggiornamento di una riga. Spesso si tratta di una colonna DATE, DATETIME o TIMESTAMP con una granularità sufficiente per soddisfare i requisiti di una colonna del limite massimo.

Nel database MySQL la colonna del limite massimo deve soddisfare i requisiti seguenti:

• Tutti gli inserimenti di dati devono specificare un valore per la colonna.
• Tutti gli aggiornamenti a un elemento modificano anche il valore della colonna.
• Il valore di questa colonna aumenta in base a ogni modifica o aggiornamento.
• Le query con le clausole ORDER BY e WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column] seguenti possono essere eseguite in modo efficiente: WHERE

L'esempio seguente mostra una definizione dell'origine dati con un criterio di rilevamento delle modifiche:

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

Indicizzazione di righe eliminate

Quando si eliminano righe dalla tabella o dalla vista, in genere si desidera eliminarle anche dall'indice di ricerca. Tuttavia, se le righe vengono rimosse fisicamente dalla tabella, un indicizzatore non può dedurre in alcun modo la presenza di record che non esistono più. La soluzione è usare la tecnica di eliminazione temporanea per eliminare in modo logico le righe senza rimuoverle dalla tabella. Aggiungere una colonna alla tabella o alla vista e contrassegnare le righe come eliminate tramite la colonna.

Data una colonna che fornisce lo stato di eliminazione, è possibile configurare un indicizzatore in modo da rimuovere tutti i documenti di ricerca per cui lo stato di eliminazione è impostato su true. La proprietà di configurazione che supporta questo comportamento è un criterio di rilevamento dell'eliminazione dei dati, specificato nella definizione dell'origine dati come indicato di seguito:

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

softDeleteMarkerValue deve essere una stringa. Ad esempio, se si dispone di una colonna di valori integer in cui le righe eliminate sono contrassegnate con il valore 1, usare "1". Se si ha una colonna BIT in cui le righe eliminate sono contrassegnate con il valore booleano true, usare il valore letterale stringa True o true. La distinzione tra maiuscole e minuscole non è rilevante.

Passaggi successivi

Ora è possibile eseguire l'indicizzatore, monitorare lo stato o pianificare l'esecuzione dell'indicizzatore. Gli articoli seguenti si applicano agli indicizzatori che eseguono il pull di contenuto da Azure MySQL:

• Indicizzare set di dati di grandi dimensioni
• Accesso dell'indicizzatore a contenuto protetto dalle funzionalità di sicurezza di rete di Azure