Tutorial: Indexar dados SQL do Azure usando o SDK do .NET

Saiba como configurar um indexer para extrair dados pesquisáveis de Banco de Dados SQL do Azure e enviá-los para um índice de pesquisa em Pesquisa de IA do Azure .

Neste tutorial, você usará o C# e o SDK Azure para .NET para:

Pré-requisitos

• Uma conta Azure com uma assinatura ativa. Criar uma conta gratuita.
• Banco de Dados SQL do Azure usando autenticação do SQL Server.
• Pesquisa de IA do Azure . Crie um serviço ou encontre um serviço existente em sua assinatura atual.
• Visual Studio.

Baixar arquivos

O código-fonte deste tutorial está na pasta DotNetHowToIndexer no repositório Azure-Samples/search-dotnet-getting-started GitHub.

Criar serviços

Este tutorial usa Pesquisa de IA do Azure  para indexação e consultas e Banco de Dados SQL do Azure como uma fonte de dados externa. Se possível, crie ambos os serviços na mesma região e no mesmo grupo de recursos para facilitar a proximidade e a capacidade de gerenciamento. Na prática, Banco de Dados SQL do Azure pode estar em qualquer região.

Comece com Banco de Dados SQL do Azure

Este tutorial fornece o arquivo hotels.sql no download de exemplo para preencher o banco de dados. O Pesquisa de IA do Azure  consome conjuntos de linhas bidimensionais, como aqueles gerados em uma exibição ou consulta. O arquivo SQL na solução de exemplo cria e preenche uma única tabela.

Se você tiver um recurso de Banco de Dados SQL do Azure existente, poderá adicionar a tabela de hotéis a ele a partir da etapa Consulta aberta.

1. Criar um banco de dados do SQL do Azure. A configuração do servidor para o banco de dados é importante:

   • Escolha a opção de autenticação SQL Server que solicita que você especifique um nome de usuário e uma senha. Você precisa disso para a cadeia de conexão ADO.NET usada pelo indexador.

   • Escolha uma conexão pública, o que facilita a conclusão deste tutorial. O público não é recomendado para produção e é recomendável excluir esse recurso no final do tutorial.

   

2. No Azure portal, vá para o novo recurso.

3. Adicione uma regra de firewall que permita acesso do seu cliente. Você pode executar ipconfig em um prompt de comando para obter seu endereço IP.

4. Use o Query editor para carregar os dados de exemplo. No painel de navegação, selecione Query editor (versão prévia) e insira o nome de usuário e a senha do administrador do servidor.

   Se você receber um erro de acesso negado, copie o endereço IP do cliente da mensagem de erro, abra a página de segurança de rede do servidor e adicione uma regra de entrada que permita o acesso do seu cliente.

5. Em Query editor, selecione Open query e navegue até o local do arquivo hotels.sql no computador local.

6. Selecione o arquivo e selecione Abrir. O script deve ser semelhante à captura de tela a seguir:

   

7. Selecione Executar para executar a consulta. No painel Resultados , você deverá ver uma mensagem bem-sucedida de consulta para três linhas.

8. Para retornar um conjunto de linhas desta tabela, você pode executar a consulta a seguir como uma etapa de verificação:

   SELECT * FROM Hotels
   

9. Copie o ADO.NET cadeia de conexão para o banco de dados. Em Settings>Connection Strings, copie o ADO.NET cadeia de conexão, que deve ser semelhante ao exemplo a seguir:

   Server=tcp:<YOUR-DATABASE-NAME>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<YOUR-USER-NAME>;Password=<YOUR-PASSWORD>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
   

Você precisará desse cadeia de conexão para configurar seu ambiente na próxima etapa.

Pesquisa de IA do Azure 

O próximo componente é Pesquisa de IA do Azure , que você pode criar no portal do Azure. Você pode usar a camada Gratuita para concluir este tutorial.

Obter uma chave de administrador e uma URL para Pesquisa de IA do Azure 

As chamadas à API exigem a URL do serviço e uma chave de acesso. Um serviço de busca é criado com as duas opções, portanto, se você adicionou o "Pesquisa de IA do Azure " à sua assinatura, siga estas etapas para obter as informações necessárias:

1. Acesse seu serviço de pesquisa no portal do Azure.

2. Na página Visão geral, copie a URL do endpoint. Um exemplo de endpoint pode ter a aparência de https://mydemo.search.windows.net.

3. Em Chaves de Configurações>, obtenha uma chave de administrador para direitos completos no serviço. Há duas chaves de administração intercambiáveis, fornecidas para a continuidade dos negócios, caso seja necessário sobrepor uma. Você pode usar uma chave em solicitações para adicionar, modificar ou excluir objetos.

   

Configure seu ambiente

1. Inicie Visual Studio e abra DotNetHowToIndexers.sln.

2. Em Gerenciador de Soluções, abra appsettings.json para fornecer informações de conexão.

3. Para SearchServiceEndPoint, se a URL completa na página Visão Geral do serviço for https://my-demo-service.search.windows.net, forneça a URL completa.

4. Para AzureSqlConnectionString, o formato de cadeia de caracteres é semelhante a "Server=tcp:<your-database-name>.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID=<your-user-name>;Password=<your-password>;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;".

   {
     "SearchServiceEndPoint": "<placeholder-search-full-url>",
     "SearchServiceAdminApiKey": "<placeholder-admin-key-for-search-service>",
     "AzureSqlConnectionString": "<placeholder-ADO.NET-connection-string",
   }
   

5. Substitua a senha do usuário no sql cadeia de conexão por uma senha válida. Embora o banco de dados e os nomes de usuário sejam copiados, você deve inserir a senha manualmente.

Criar o pipeline

Os indexadores exigem um objeto de fonte de dados e um índice. O código relevante encontra-se em dois arquivos:

• hotel.cs contém um esquema que define o índice
• Program.cs contém funções para criar e gerenciar estruturas em seu serviço

Em hotel.cs

O esquema de índice define a coleção de campos, incluindo atributos que especificam operações permitidas, como se um campo é pesquisável em texto completo, filtre ou classificável, conforme mostrado na definição de campo a seguir para HotelName. Um SearchableField é, por definição, pesquisável em texto completo. Outros atributos são atribuídos explicitamente.

. . . 
[SearchableField(IsFilterable = true, IsSortable = true)]
[JsonPropertyName("hotelName")]
public string HotelName { get; set; }
. . .

Um esquema também pode incluir outros elementos, como perfis de pontuação para aumentar uma pontuação de pesquisa e analisadores personalizados. No entanto, para este tutorial, o esquema é pouco definido, consistindo apenas em campos encontrados nos conjuntos de dados de exemplo.

Em Program.cs

O programa principal inclui lógica para criar an indexador client, um índice, uma fonte de dados e um indexador. O código verifica e exclui os recursos existentes de mesmo nome, supondo que você possa executar esse programa várias vezes.

O objeto de fonte de dados é configurado com configurações específicas para recursos de Banco de Dados SQL do Azure, incluindo indexação parcial ou incremental para usar os recursos internos de detecção de alterações de SQL do Azure. O banco de dados de hotéis de demonstração de origem no SQL do Azure tem uma coluna de "exclusão reversível" chamada IsDeleted. Quando essa coluna é definida como true no banco de dados, o indexador remove o documento correspondente do índice Pesquisa de IA do Azure .

Console.WriteLine("Creating data source...");

var dataSource =
      new SearchIndexerDataSourceConnection(
         "hotels-sql-ds",
         SearchIndexerDataSourceType.AzureSql,
         configuration["AzureSqlConnectionString"],
         new SearchIndexerDataContainer("hotels"));

indexerClient.CreateOrUpdateDataSourceConnection(dataSource);

Um objeto indexador é independente da plataforma, em que a configuração, o agendamento e a invocação são os mesmos, independentemente da origem. Este indexador de exemplo inclui um agendamento e uma opção de redefinição que limpa o histórico do indexador. Ele também chama um método para criar e executar o indexador imediatamente. Para criar ou atualizar um indexador, use CreateOrUpdateIndexerAsync.

Console.WriteLine("Creating Azure SQL indexer...");

var schedule = new IndexingSchedule(TimeSpan.FromDays(1))
{
      StartTime = DateTimeOffset.Now
};

var parameters = new IndexingParameters()
{
      BatchSize = 100,
      MaxFailedItems = 0,
      MaxFailedItemsPerBatch = 0
};

// Indexer declarations require a data source and search index.
// Common optional properties include a schedule, parameters, and field mappings
// The field mappings below are redundant due to how the Hotel class is defined, but 
// we included them anyway to show the syntax 
var indexer = new SearchIndexer("hotels-sql-idxr", dataSource.Name, searchIndex.Name)
{
      Description = "Data indexer",
      Schedule = schedule,
      Parameters = parameters,
      FieldMappings =
      {
         new FieldMapping("_id") {TargetFieldName = "HotelId"},
         new FieldMapping("Amenities") {TargetFieldName = "Tags"}
      }
};

await indexerClient.CreateOrUpdateIndexerAsync(indexer);

As execuções do indexador geralmente são agendadas, mas durante o desenvolvimento, convém executar o indexador imediatamente usando RunIndexerAsync.

Console.WriteLine("Running Azure SQL indexer...");

try
{
      await indexerClient.RunIndexerAsync(indexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
      Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

Compilar a solução

Selecione F5 para compilar e executar a solução. O programa é executado no modo de depuração. Uma janela de console relata o status de cada operação.

Seu código é executado localmente em Visual Studio, conectando-se ao seu search service no Azure, que por sua vez se conecta ao Banco de Dados SQL do Azure e recupera o conjunto de dados. Com essas muitas operações, há vários pontos potenciais de falha. Se você receber um erro, verifique as seguintes condições primeiro:

• As informações de conexão do serviço de pesquisa que você fornece são a URL completa. Se você inserir apenas o nome do serviço, as operações param na criação do índice, resultando em um erro de falha de conexão.

• Informações de conexão do banco de dados em appsettings.json. Deve ser o ADO.NET cadeia de conexão obtido do Azure portal, modificado para incluir um nome de usuário e uma senha válidos para o banco de dados. A conta de usuário deve ter permissão para recuperar dados. O endereço IP do cliente local deve ter permissão para acesso de entrada através do firewall.

• Limites de recursos. Não esqueça que a Camada gratuita tem um limite de três índices, indexadores e fontes de dados. Um serviço no limite máximo não pode criar novos objetos.

Pesquisa

Use o Azure portal para verificar a criação de objetos e, em seguida, use Search Explorer para consultar o índice.

1. Acesse seu serviço de pesquisa no portal do Azure.

2. No painel esquerdo, abra cada página para verificar se os objetos foram criados. Índices, indexadores e fontes de dados devem ter hotels-sql-idx, hotels-sql-idxr e hotels-sql-ds, respectivamente.

3. Na guia Índices , selecione o índice hotels-sql-idx . Na página de hotéis, a primeira aba é o Explorador de pesquisa.

4. Selecione Pesquisar para emitir uma consulta vazia.

   As três entradas no índice são retornadas como documentos JSON. O Gerenciador de pesquisa retorna documentos em JSON para que você possa exibir toda a estrutura.

   

5. Alterne para o modo de exibição JSON para que você possa inserir parâmetros de consulta.

   {
        "search": "river",
        "count": true
   }
   

   Essa consulta invoca a pesquisa de texto completo no termo river. O resultado inclui uma contagem dos documentos correspondentes. Retornar a contagem de documentos correspondentes é útil em cenários de teste em que você tem um índice grande com milhares ou milhões de documentos. Nesse caso, apenas um documento corresponde à consulta.

6. Insira parâmetros que limitam os resultados da pesquisa a campos de interesse.

   {
        "search": "river",
        "select": "hotelId, hotelName, baseRate, description",
        "count": true
   }
   

   A resposta da consulta é reduzida para os campos selecionados, resultando em uma saída mais concisa.

Redefinir e execute novamente

Nos estágios experimentais iniciais do desenvolvimento, a abordagem mais prática para iteração de design é excluir os objetos de Pesquisa de IA do Azure  e permitir que seu código os recompile. Nomes de recurso são exclusivos. Excluir um objeto permite que você recriá-la usando o mesmo nome.

O código de exemplo deste tutorial verifica se há objetos existentes e os exclui, de modo que você possa executar novamente o código.

Você também pode usar o Azure portal para excluir índices, indexadores e fontes de dados.

Limpar os recursos

Quando você está trabalhando em sua própria assinatura, no final de um projeto, é recomendável remover os recursos que já não são necessários. Recursos deixados em execução podem custar dinheiro. É possível excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no Azure portal, usando o link Todos os recursos ou grupos de recursos no painel de navegação à esquerda.

Próximas etapas

Agora que você está familiarizado com os conceitos básicos da indexação do Banco de Dados SQL, examine mais de perto a configuração do indexador: