Indexar dados do servidor flexível do Banco de Dados do Azure para MySQL

Neste artigo, saiba como configurar um indexador que importa o 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 os registros, numa só tabela ou exibição. A saída é 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 servidor flexível do Banco de Dados do Azure para 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 e criar um indexador. A extração de dados ocorre quando você envia a solicitação Criar Indexador.

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

Pré-requisitos

• Registre-se para a versão prévia para fornecer comentários sobre o cenário. Você pode acessar o recurso automaticamente após o envio do formulário.

• Servidor flexível do Banco de Dados do Azure para MySQL e dados de exemplo. Os dados devem residir em uma tabela ou exibição. Uma chave primária é necessária. Se você estiver usando uma exibição, ela precisará ter uma coluna de marca-d'água alta.

• Permissões de leitura. Uma cadeia de conexão de acesso completo inclui uma chave que permite acesso ao conteúdo, mas se você estiver usando funções do Azure, verifique se a identidade gerenciada do serviço de pesquisa tem as permissões Leitor no MySQL.

• Um cliente REST para criar a fonte de dados, índice e indexador.

  Use também o SDK do Azure para .NET. Não é possível usar o portal para a criação do indexador, mas pode gerenciar indexadores e fontes de dados depois que eles são criados.

Limitações de visualização

No momento, o controle de alterações e a detecção de exclusão não estão funcionando se a data ou o carimbo de data/hora é igual em todas as linhas. Essa limitação é um problema conhecido a ser resolvido em uma atualização da versão prévia. Até que esse problema seja resolvido, não adicione um conjunto de habilidades ao indexador do MySQL.

A versão prévia não dá suporte a tipos de geometria e blobs.

Como indicado, não há suporte no portal para a criação do indexador, mas uma fonte de dados e um indexador do MySQL podem ser gerenciados no portal depois de criados. 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, as credenciais e as 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 API REST de visualização 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 forem voláteis e você quiser que o indexador selecione apenas os itens novos e atualizados nas execuções seguintes.

• Defina dataDeletionDetectionPolicy se desejar remover documentos de pesquisa de um índice de pesquisa quando o item de origem for excluído.

Crie 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 (nesse caso, "ID"), o indexador importará a chave primária como a chave do documento.

Mapeamento de tipos de dados

A tabela a seguir mapeia o banco de dados MySQL para os equivalentes ao Azure AI Search. Para obter mais informações, confira Tipos de dados com suporte (Azure AI Search).

Configurar e executar o indexador do MySQL

Uma vez que o índice e a fonte de dados forem criados, será possível criar o indexador. A configuração do indexador especifica as entradas, os parâmetros e as propriedades que controlam os comportamentos de tempo de execução.

Crie ou atualize um indexador dando um nome a ele e referenciando a fonte de dados e o í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 você precisar de várias versões de um campo de origem no índice de pesquisa.

• Um indexador é executado automaticamente depois de criado. Você pode preveni-lo de ser executado definindo disabled como true. Para controlar a execução do indexador, execute um indexador sob demanda ou coloque-o em um agendamento.

Checar o status do indexador

Envie uma solicitação Obter Status do Indexador para monitorar a execução do indexador:

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

A resposta inclui o status e o número de itens processados. Ela deve ser parecida com o 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ções contém até 50 execuções mais recentes, classificadas em ordem cronológica inversa, de modo que a execução mais recente apareça em primeiro lugar.

Como indexar linhas novas e alteradas

Depois que um indexador preencher completamente um índice de pesquisa, o ideal será que o indexador seguinte seja executado para indexar de maneira incremental apenas as linhas novas e alteradas no banco de dados.

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

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

A política de detecção de alteração de um indexador depende da presença de uma coluna de marca d'água alta que captura a versão de linha ou a data e a hora da última atualização de uma linha. Muitas vezes, é uma coluna DATE, DATETIME ou TIMESTAMP com granularidade suficiente para atender aos requisitos de uma coluna de marca d'água alta.

No banco de dados MySQL, a coluna de marca d'água alta precisa atender aos seguintes requisitos:

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

O seguinte exemplo mostra uma definição de fonte de dados com uma política de detecção de alteração:

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

Como indexar linhas excluídas

Quando as linhas são excluídas da tabela ou da exibição, normalmente, o ideal também é excluí-las 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 a técnica de exclusão reversível para excluir logicamente as linhas sem removê-las da tabela. Adicione uma coluna à sua tabela ou exiba e marque as linhas como excluídas usando essa coluna.

Considerando uma coluna que fornece o estado de exclusão, um indexador pode ser configurado para remover todos os 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 política de detecçã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 de inteiros na qual as linhas excluídas são marcadas com o valor 1, use "1". Se você tiver uma coluna BIT na qual as linhas excluídas são marcadas com o valor true booliano, use a cadeia de caracteres literal True ou true, o caso não importa.

Próximas etapas

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

• Indexar conjuntos de dados grandes
• Acesso do indexador ao conteúdo protegido pelos recursos de segurança de rede do Azure