Dados de índice do Banco de Dados do Azure para servidor flexível MySQL

Artigo
03/12/2024

Importante

O suporte ao MySQL está atualmente em pré-visualização pública sob Termos de Uso Suplementares. Use uma API REST de visualização (2020-06-30-preview ou posterior) para indexar seu conteúdo. Atualmente, não há suporte ao portal.

Neste artigo, saiba como configurar um indexador que importa conteúdo do Banco de Dados do Azure para MySQL e o torna pesquisável no Azure AI Search. As entradas para o indexador são a sua linha, numa única tabela ou vista. Output é um índice de pesquisa com conteúdo pesquisável em campos individuais.

Este artigo complementa Criar um indexador com informações específicas para indexação do Banco de Dados do Azure para servidor flexível MySQL. Ele usa as APIs REST para demonstrar um fluxo de trabalho de três partes comum a todos os indexadores: criar uma fonte de dados, criar um índice, criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar indexador.

Quando configurado para incluir uma marca d'água alta e exclusão suave, o indexador recebe todas as alterações, uploads e exclusões para seu banco de dados MySQL. Ele reflete essas alterações no seu índice de pesquisa. A extração de dados ocorre quando você envia a solicitação Criar indexador.

Pré-requisitos

Registre-se para a visualização para fornecer feedback sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.
Banco de Dados do Azure para MySQL, servidor flexível e dados de exemplo. Os dados devem residir em uma tabela ou exibição. É necessária uma chave primária. Se você estiver usando uma exibição, ela deve ter uma coluna de marca d'água alta.
Permissões de leitura. Uma cadeia de conexão de acesso total inclui uma chave que concede acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem permissões de Leitor no MySQL.
Um cliente REST para criar a fonte de dados, o índice e o indexador.

Você também pode usar o SDK do Azure para .NET. Você não pode usar o portal para a criação de indexadores, mas pode gerenciar indexadores e fontes de dados depois que eles são criados.

Limitações de pré-visualização

Atualmente, o controle de alterações e a deteção de exclusão não estão funcionando se o carimbo de data ou hora for uniforme para todas as linhas. Essa limitação é um problema conhecido a ser resolvido em uma atualização da visualização. Até que esse problema seja resolvido, não adicione um conjunto de habilidades ao indexador MySQL.

A pré-visualização não suporta tipos de geometria e blobs.

Como observado, não há suporte de portal para a criação de indexadores, mas um indexador MySQL e uma fonte de dados podem ser gerenciados no portal assim que existirem. Por exemplo, você pode editar as definições e redefinir, executar ou agendar o indexador.

Definir a fonte de dados

A definição da fonte de dados especifica os dados a serem indexados, credenciais e políticas para identificar alterações nos dados. A fonte de dados é definida como um recurso independente para que possa ser usada por vários indexadores.

Criar ou Atualizar Fonte de Dados especifica a definição. Certifique-se de usar uma versão da API REST de visualização (2020-06-30-Preview ou posterior) ao criar a fonte de dados.

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

Pontos principais:

Defina type como "mysql" (obrigatório).
Defina credentials como uma cadeia de conexão ADO.NET. Você pode encontrar cadeias de conexão no portal do Azure, na página Cadeias de conexão para MySQL.
Defina container como o nome da tabela.
Defina dataChangeDetectionPolicy se os dados são voláteis e você deseja que o indexador pegue apenas os itens novos e atualizados em execuções subsequentes.
Defina dataDeletionDetectionPolicy se deseja remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.

Criar um índice

Criar ou Atualizar Índice especifica o 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  }     
    ]
}

Se a chave primária na tabela de origem corresponder à chave do documento (neste caso, "ID"), o indexador importará a chave primária como a chave do documento.

Mapeando tipos de dados

A tabela a seguir mapeia o banco de dados MySQL para equivalentes do Azure AI Search. Para obter mais informações, consulte Tipos de dados suportados (Azure AI Search).

Nota

A pré-visualização não suporta tipos de geometria e blobs.

Tipos de dados MySQL	Tipos de campo do Azure AI Search
`bool`, `boolean`	Edm.Booleano, 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`, `longtexttext`, `enum`, `set`,`time`	Edm.String
dados numéricos não assinados, serial, decimal, dec, bit, blob, binário, geometria	N/A

Configurar e executar o indexador MySQL

Depois que o índice e a fonte de dados forem criados, você estará pronto para criar o indexador. A configuração do indexador especifica as entradas, parâmetros e propriedades que controlam os comportamentos de tempo de execução.

Crie ou atualize um indexador dando-lhe um nome e fazendo referência à fonte de dados e ao í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
}

Pontos principais:

Especifique mapeamentos de campo se houver diferenças no nome ou tipo de campo ou se precisar de várias versões de um campo de origem no índice de pesquisa.
Um indexador é executado automaticamente quando é criado. Você pode impedir que ele seja executado definindo disabled como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em uma programação.

Verificar o estado do indexador

Envie uma solicitação Get Indexer Status para monitorar a execução do indexador:

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

A resposta inclui o status e o número de itens processados. Deve ser semelhante ao seguinte exemplo:

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

O histórico de execução contém até 50 das execuções concluídas mais recentemente, que são classificadas na ordem cronológica inversa para que a execução mais recente venha primeiro.

Indexação de linhas novas e alteradas

Depois que um indexador tiver preenchido totalmente um índice de pesquisa, convém que as execuções subsequentes do indexador indexem incrementalmente apenas as linhas novas e alteradas em seu banco de dados.

Para habilitar a indexação incremental, defina a propriedade na definição da dataChangeDetectionPolicy fonte de dados. Essa propriedade informa ao indexador qual mecanismo de controle de alterações é usado em seus dados.

Para indexadores do Banco de Dados do Azure para MySQL, a única política com suporte é o HighWaterMarkChangeDetectionPolicy.

A política de deteção de alterações de um indexador depende de ter uma coluna de marca d'água alta que captura a versão da linha ou a data e hora em que uma linha foi atualizada pela última vez. Muitas vezes, é uma DATE, DATETIMEou TIMESTAMP coluna com uma granularidade suficiente para atender aos requisitos de uma coluna de marca d'água alta.

Em seu banco de dados MySQL, a coluna de marca d'água alta deve atender aos seguintes requisitos:

Todas as inserções de dados devem especificar um valor para a coluna.
Todas as atualizações de um item também alteram o valor da coluna.
O valor desta coluna aumenta a cada inserção ou atualização.
Consultas com o seguinte WHERE e ORDER BY cláusulas podem ser executadas de forma eficiente: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

O exemplo a seguir mostra uma definição de fonte de dados com uma política de deteção de alterações:

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

Se você estiver usando um modo de exibição, deverá definir uma política de marca d'água alta na fonte de dados do indexador.

Se a tabela de origem não tiver um índice na coluna de marca d'água alta, as consultas usadas pelo indexador MySQL podem atingir o tempo limite. Em particular, a ORDER BY [High Water Mark Column] cláusula requer que um índice seja executado de forma eficiente quando a tabela contém muitas linhas.

Indexação de linhas excluídas

Quando as linhas são excluídas da tabela ou exibição, normalmente você também deseja excluir essas linhas do índice de pesquisa. No entanto, se as linhas forem fisicamente removidas da tabela, um indexador não terá como inferir a presença de registros que não existem mais. A solução é usar uma técnica de exclusão suave para excluir logicamente linhas sem removê-las da tabela. Adicione uma coluna à sua tabela ou vista e marque as linhas como eliminadas utilizando essa coluna.

Dada uma coluna que fornece o estado de exclusão, um indexador pode ser configurado para remover quaisquer documentos de pesquisa para os quais o estado de exclusão esteja definido como true. A propriedade de configuração que dá suporte a esse comportamento é uma diretiva de deteção de exclusão de dados, que é especificada na definição da fonte de dados da seguinte maneira:

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

O softDeleteMarkerValue deve ser uma cadeia de caracteres. Por exemplo, se você tiver uma coluna inteira onde as linhas excluídas são marcadas com o valor 1, use "1". Se você tiver uma BIT coluna onde as linhas excluídas são marcadas com o valor verdadeiro booleano, use a cadeia de caracteres literal True ou true (o caso não importa).

Próximos passos

Agora você pode executar o indexador, monitorar o status ou agendar a execução do indexador. Os seguintes artigos se aplicam a indexadores que extraem conteúdo do Azure MySQL: