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

Configure um indexador para extrair dados pesquisáveis do Banco de Dados SQL do Azure, enviando-os para um índice de pesquisa no Azure AI Search.

Este tutorial usa C# e o SDK do Azure para .NET para executar as seguintes tarefas:

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

• Banco de Dados SQL do Azure usando a autenticação do SQL Server
• Visual Studio
• Azure AI Search. Criar ou localizar um serviço de pesquisa existente

Transferir ficheiros

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

1 - Criar serviços

Este tutorial usa o Azure AI Search para indexação e consultas e o 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 grupo de recursos para proximidade e capacidade de gerenciamento. Na prática, o Banco de Dados SQL do Azure pode estar em qualquer região.

Começar com o Banco de Dados SQL do Azure

Este tutorial fornece hotels.sql arquivo no download de exemplo para preencher o banco de dados. O Azure AI Search consome conjuntos de linhas nivelados, como um gerado a partir de uma exibição ou consulta. O ficheiro SQL na solução de exemplo cria e preenche uma única tabela.

Se você tiver um recurso existente do Banco de Dados SQL do Azure, poderá adicionar a tabela de hotéis a ele, começando na etapa de consulta Abrir.

1. Crie um banco de dados SQL do Azure, usando as instruções em Guia de início rápido: criar um único banco de dados.

   A configuração do servidor para o banco de dados é importante.

   • Escolha a opção de autenticação do 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. Isso torna este tutorial mais fácil de concluir. O público não é recomendado para produção e recomendamos excluir esse recurso no final do tutorial.

   

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

3. Adicione uma regra de firewall para permitir o acesso do seu cliente, usando as instruções em Guia de início rápido: criar uma regra de firewall no nível de servidor no portal do Azure. Você pode executar ipconfig a partir de um prompt de comando para obter seu endereço IP.

4. Use o Editor de consultas para carregar os dados de exemplo. No painel de navegação, selecione Editor de consultas (visualização) e digite 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 cliente.

5. No Editor de consultas, selecione Abrir consulta e navegue até hotels.sql local do arquivo no computador local.

6. Selecione o arquivo e selecione Abrir. O script deverá ser parecido com o da captura de ecrã seguinte:

   

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

8. Para devolver um conjunto de linhas a partir desta tabela, pode executar a consulta seguinte como passo de verificação:

   SELECT * FROM Hotels
   

9. Copie a cadeia de conexão ADO.NET para o banco de dados. Em Configurações>Cadeias de Conexão, copie a cadeia de conexão ADO.NET, semelhante ao exemplo abaixo.

   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á dessa cadeia de conexão no próximo exercício, configurando seu ambiente.

Pesquisa de IA do Azure

O próximo componente é o Azure AI Search, que você pode criar no portal do Azure. Você pode usar o nível Gratuito para concluir este passo a passo.

Obter uma chave de api de administrador e URL para o Azure AI Search

As chamadas de API requerem o URL do serviço e uma chave de acesso. Um serviço de pesquisa é criado com ambos, portanto, se você adicionou o Azure AI Search à sua assinatura, siga estas etapas para obter as informações necessárias:

1. Entre no portal do Azure e, na página Visão geral do serviço de pesquisa, obtenha a URL. Um ponto final de exemplo poderá ser parecido com https://mydemo.search.windows.net.

2. Em Teclas de Configurações>, obtenha uma chave de administrador para obter todos os direitos no serviço. Há duas chaves de administrador intercambiáveis, fornecidas para continuidade de negócios no caso de você precisar rolar uma. Você pode usar a chave primária ou secundária em solicitações para adicionar, modificar e excluir objetos.

   

2 - Configure o seu ambiente

1. Inicie o Visual Studio e abra DotNetHowToIndexers.sln.

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

3. Para SearchServiceEndPoint, se o URL completo na página de visão geral do serviço for "https://my-demo-service.search.windows.net", o valor a ser fornecido será o URL inteiro.

4. Para AzureSqlConnectionString, o formato de cadeia de caracteres é semelhante a este: "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 de usuário na cadeia de conexão SQL por uma senha válida. Embora o banco de dados e os nomes de usuário sejam copiados, a senha deve ser inserida manualmente.

3 - Crie o pipeline

Os indexadores exigem um objeto de fonte de dados e um índice. O código relevante está em dois ficheiros:

• hotel.cs, contendo um esquema que define o índice

• Program.cs, contendo funções para criar e gerir estruturas no seu serviço

Em hotel.cs

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

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

Os esquemas também podem incluir outros elementos, como perfis de classificação para otimizar as classificações de pesquisas, analisadores personalizados e outros construtores. No entanto, para a nossa finalidade, o esquema é definido de forma escassa, consistindo apenas em campos encontrados nos conjuntos de dados de exemplo.

Em Program.cs

O programa principal inclui lógica para criar um cliente indexador, um índice, uma fonte de dados e um indexador. Verifica e elimina os recursos existentes com o mesmo nome, no pressuposto de que poderá executar este programa várias vezes.

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

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 de plataforma, onde configuração, agendamento e invocação são os mesmos, independentemente da origem. Este indexador de exemplo inclui uma agenda, uma opção de redefinição que limpa o histórico do indexador e 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 você pode querer 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);
}

4 - Construa a solução

Pressione F5 para criar e executar a solução. O programa é executado no modo de depuração. O estado de cada operação é reportado numa janela da consola.

Seu código é executado localmente no Visual Studio, conectando-se ao seu serviço de pesquisa no Azure, que, por sua vez, se conecta ao Banco de Dados SQL do Azure e recupera o conjunto de dados. Com tantas operações, existem 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 fornecidas são a URL completa. Se você inseriu apenas o nome do serviço, as operações serão interrompidas na criação do índice, com um erro de falha na conexão.

• A informação de ligação da base de dados em appsettings.json. Deve ser a cadeia de conexão ADO.NET obtida do portal do Azure, modificada para incluir um nome de usuário e senha válidos para seu banco de dados. A conta de utilizador tem de ter permissão para obter dados. O endereço IP do cliente local deve ter acesso de entrada através do firewall.

• Limites dos recursos. Lembre-se de que a camada Gratuita tem limites de três índices, indexadores e fontes de dados. Um serviço no limite máximo não pode criar novos objetos.

5 - Pesquisa

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

1. Entre no portal do Azure e, no painel de navegação esquerdo do serviço de pesquisa, abra cada página para verificar se o objeto foi criado. Índices, indexadores e fontes de dados terão "hotels-sql-idx", "hotels-sql-indexer" e "hotels-sql-ds", respectivamente.

2. Na guia Índices, selecione o índice hotels-sql-idx. Na página de hotéis, o explorador de pesquisa é o primeiro separador.

3. Selecione Pesquisar para emitir uma consulta vazia.

   As três entradas no índice são devolvidas como documentos JSON. O Explorador de Pesquisa devolve documentos em JSON, para que possa ver a estrutura inteira.

   

4. Em seguida, alterne para JSON View para que você possa inserir parâmetros de consulta:

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

   Esta consulta invoca a pesquisa de texto completo para o termo river e o resultado inclui um contagem dos documentos correspondentes. Devolver a contagem de documentos correspondentes é útil em cenários de teste, em que tem um índice grande com milhares ou milhões de documentos. Neste caso, apenas um documento corresponde à consulta.

5. Por fim, insira parâmetros que limitam os resultados da pesquisa aos campos de interesse:

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

   A resposta da consulta é reduzida aos campos selecionados, resultando numa saída mais concisa.

Repor e executar novamente

Nos estágios experimentais iniciais de desenvolvimento, a abordagem mais prática para iteração de design é excluir os objetos da Pesquisa de IA do Azure e permitir que seu código os reconstrua. Os nomes dos recursos são exclusivos. Quando elimina um objeto, pode recriá-lo com o mesmo nome.

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

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

Clean up resources (Limpar recursos)

Quando estiver a trabalhar na sua própria subscrição, no final de um projeto, é uma boa ideia remover os recursos de que já não necessita. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal do Azure, usando o link Todos os recursos ou Grupos de recursos no painel de navegação esquerdo.

Próximos passos

Agora que você está familiarizado com os conceitos básicos da indexação do Banco de dados SQL, vamos examinar mais de perto a configuração do indexador.