Tutorial: Indexación de datos SQL de Azure mediante el SDK de .NET

Artigo
09/25/2024

Configure un indexador que extraiga datos que permitan búsquedas desde Azure SQL Database y los envíe a un índice de búsqueda en Azure AI Search.

En este tutorial, usará C# y el SDK de Azure para .NET para realizar las tareas siguientes:

Creación de un origen de datos que se conecte a Azure SQL Database
Creación de un indexador
Ejecución de un indexador para cargar datos en un índice
Consulta de un índice como paso de comprobación

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Requisitos previos

Azure SQL Database mediante la autenticación de SQL Server
Visual Studio
Búsqueda de Azure AI. Creación o búsqueda de un servicio de búsqueda existente

Nota:

Puede usar un servicio de búsqueda gratuito para este tutorial. El nivel gratis le limita a tres índices, tres indexadores y tres orígenes de datos. En este tutorial se crea uno de cada uno. Antes de empezar, asegúrese de que haya espacio en el servicio para aceptar los nuevos recursos.

Descarga de archivos

El código fuente de este tutorial se encuentra en la carpeta DotNetHowToIndexer del repositorio Azure-Samples/search-dotnet-getting-started de GitHub.

1: Creación de servicios

En este tutorial se usa Azure AI Search en la indexación y las consultas y Azure SQL Database como origen de datos externo. Si es posible, cree ambos servicios en la misma región y grupo de recursos por proximidad y capacidad de administración. En la práctica, Azure SQL Database puede estar en cualquier región.

Empezar con Azure SQL Database

En este tutorial se proporciona el archivo hotels.sql en la descarga de ejemplo para rellenar la base de datos. Azure AI Search usa conjuntos de filas planas, como los que se generan a partir de una vista o una consulta. El archivo SQL de la solución de ejemplo crea y rellena una sola tabla.

Si tiene un recurso de Azure SQL Database existente, puede agregarle la tabla de hoteles, a partir del paso Abrir consulta.

Cree una instancia de Azure SQL Database mediante las instrucciones de Inicio rápido: Creación de una base de datos única.

La configuración del servidor para la base de datos es importante.
- Elija la opción de autenticación de SQL Server que le pide que especifique un nombre de usuario y una contraseña. Necesita esto para obtener la cadena de conexión de ADO.NET que utiliza el indizador.
- Elija una conexión pública. Hace que este tutorial sea más fácil de completar. No se recomienda una conexión pública para producción, y se recomienda eliminar este recurso al final del tutorial.
En Azure Portal, vaya al nuevo recurso.
Agregue una regla de firewall para permitir el acceso desde el cliente mediante las instrucciones de Inicio rápido: Creación de una regla de firewall a nivel de servidor en Azure Portal. Puede ejecutar ipconfig desde un símbolo del sistema para obtener la dirección IP.
Use el editor de consultas para cargar los datos de ejemplo. En el panel de navegación, seleccione Editor de consultas (versión preliminar) y escriba el nombre de usuario y la contraseña del administrador del servidor.

Si recibe un error de acceso denegado, copie la dirección IP del cliente del mensaje de error, abra la página de seguridad de red del servidor y agregue una regla de entrada que permita el acceso desde el cliente.
En el editor de consultas, seleccione Abrir consulta y vaya a la ubicación del archivo hotels.sql en el equipo local.
Seleccione el archivo y elija Abrir. El script debe tener un aspecto similar a la siguiente captura de pantalla:
Seleccione Ejecutar para ejecutar la consulta. En el panel Resultados, debe ver un mensaje de consulta correcta, correspondiente a tres filas.
Para devolver un conjunto de filas de esta tabla, puede ejecutar la siguiente consulta como paso de comprobación:
```
SELECT * FROM Hotels
```

Copie la cadena de conexión ADO.NET correspondiente a la base de datos. En Configuración>Cadenas de conexión, copie la cadena de conexión ADO.NET, como en el ejemplo siguiente.

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;

Necesitará esta cadena de conexión en el ejercicio siguiente, Configuración del entorno.

Azure AI Search

El siguiente componente es Azure AI Search, que se puede crear en el portal. Puede usar el nivel Gratis para completar este tutorial.

Obtención de una clave de API de administración y una dirección URL para Azure AI Search

Las llamadas API requieren la dirección URL del servicio y una clave de acceso. Con ambos se crea un servicio de búsqueda, por lo que si ha agregado Azure AI Search a su suscripción, siga estos pasos para obtener la información necesaria:

Inicie sesión en Azure Portal y en la página Introducción del servicio de búsqueda, y obtenga la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.
En Configuración>Claves, obtenga una clave de administrador para tener derechos completos en el servicio. Se proporcionan dos claves de administrador intercambiables para lograr la continuidad empresarial, por si necesitara sustituir una de ellas. Puede usar la clave principal o secundaria en las solicitudes para agregar, modificar y eliminar objetos.

2: Configuración del entorno

Inicie Visual Studio y abra DotNetHowToIndexers.sln.
En el Explorador de soluciones, abra appsettings.json para proporcionar información de conexión.
Para SearchServiceEndPoint, si la URL completa de la página de información general del servicio es "https://my-demo-service.search.windows.net"", el valor que hay que proporcionar es esa URL.
Para AzureSqlConnectionString, el formato de cadena es similar al siguiente: "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",
}
```
Reemplace la contraseña de usuario en la cadena de conexión SQL por una contraseña válida. Mientras que los nombres de la base de datos y de usuario se copiarán, la contraseña debe escribirse manualmente.

3: Creación de la canalización

Los indexadores requieren un objeto de origen de datos y un índice. El código pertinente aparece en dos archivos:

hotel.cs, que contiene un esquema que define el índice
Program.cs, que contiene las funciones para crear y administrar las estructuras del servicio

En hotel.cs

El esquema de índice define la colección de campos, incluidos los atributos que especifican las operaciones permitidas; por ejemplo, si un campo de texto completo permite búsquedas, filtros o clasificación, como se muestra en la siguiente definición de campo para HotelName. SearchableField es una clase de búsqueda de texto completo por definición. Otros atributos se asignan de forma explícita.

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

Un esquema también puede incluir otros elementos, como los perfiles de puntuación para aumentar una puntuación de búsqueda, analizadores personalizados y otras construcciones. Sin embargo, para nuestros fines, el esquema se define de forma dispersa, estando compuesto solo de los campos encontrados en los conjuntos de datos de ejemplo.

En Program.cs

El programa principal incluye la lógica para crear un cliente de indizador, un índice, un origen de datos y un indizador. El código busca y elimina los recursos existentes del mismo nombre, bajo el supuesto de que este programa se podría ejecutar varias veces.

El objeto de origen de datos está configurado con valores específicos de los recursos de Azure SQL Database, incluida la indexación parcial o incremental, para usar las características de detección de cambios integradas de Azure SQL. La base de datos de demostración de hoteles de Azure SQL tiene una columna de "eliminación temporal" denominada IsDeleted. Cuando esta columna se establece en true en la base de datos, el indexador quita el documento correspondiente del índice de 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);

Los objetos de indexador son independientes de la plataforma, donde la configuración la programación y la invocación son siempre los mismos, independientemente del origen. Este indexador de ejemplo incluye un programa, una opción de restablecimiento que elimina su historial y llama un método para crear el indexador y ejecutarlo inmediatamente. Para crear o actualizar un indizador, utilice 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);

Las ejecuciones de indizador normalmente están programadas, pero en la fase de desarrollo tal vez desee ejecutar el indizador inmediatamente con 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: Compilación de la solución

Presione F5 para compilar y ejecutar la solución. El programa se ejecuta en modo de depuración. Una ventana de consola informa del estado de cada operación.

El código se ejecuta localmente en Visual Studio y se conecta al servicio de búsqueda en Azure, que, a su vez, se conecta a Azure SQL Database y recupera el conjunto de datos. Con estas muchas operaciones, hay varios puntos de error posibles. Si recibe un error, compruebe primero las condiciones siguientes:

La información de conexión del servicio de búsqueda que proporcione es la URL completa. Si solo especificó el nombre del servicio, las operaciones se detendrán al crearse el índice y se generará un error de conexión.
La información de conexión de la base de datos appsettings.json. Debe ser la cadena de conexión de ADO.NET obtenida del portal, modificada para incluir un nombre de usuario y una contraseña que sean válidos para la base de datos. La cuenta de usuario debe tener permiso para recuperar datos. Hay que permitir acceso de entrada a la dirección IP del cliente local a través del firewall.
Los límites de recursos. Recuerde que el nivel Gratis tiene un límite de tres índices, tres indexadores y tres orígenes de datos. Un servicio que ha alcanzado el límite máximo no puede crear nuevos objetos.

5: Búsqueda

Use Azure Portal para comprobar la creación de objetos y use Explorador de búsqueda para consultar el índice.

Inicie sesión en Azure Portal y, en el panel de navegación izquierdo del servicio de búsqueda, abra cada página correspondiente para comprobar que el objeto se ha creado. Los índices, indizadores y orígenes de datos contendrán "hotels-sql-idx", "hotels-sql-indexer" y "hotels-sql-ds", respectivamente.
En la pestaña Índices, seleccione el índice hotels-sql-idx. En la página de hoteles, Explorador de búsqueda es la primera pestaña.
Haga clic en Buscar para emitir una consulta vacía.

Las tres entradas del índice se devuelven como documentos JSON. El Explorador de búsqueda devuelve documentos en JSON para que pueda ver la estructura completa.
A continuación, cambie a la vista JSON para poder escribir parámetros de consulta:
```
{
     "search": "river",
     "count": true
}
```
Esta consulta invoca la búsqueda de texto completo en el término river, y el resultado incluye un recuento de los documentos coincidentes. Devolver el número de documentos coincidencias es útil en escenarios de pruebas cuando se tiene un índice grande con miles o millones de documentos. En este caso, solo un documento coincide con la consulta.
Por último, escriba parámetros que limiten los resultados de búsqueda a campos de interés:
```
{
     "search": "river",
     "select": "hotelId, hotelName, baseRate, description",
     "count": true
}
```
La respuesta de la consulta se reduce a los campos seleccionados, lo que da lugar a una salida más concisa.

Restablecer y volver a ejecutar

En las primeras etapas experimentales de desarrollo, el enfoque más práctico para la iteración de diseño es eliminar los objetos de Azure AI Search y permitir que el código vuelva a generarlos. Los nombres de los recursos son únicos. La eliminación de un objeto permite volver a crearlo con el mismo nombre.

En el código de ejemplo de este tutorial se comprueban los objetos existentes y se eliminan para que pueda volver a ejecutar el código.

También puede usar el portal para eliminar los índices, indexadores y orígenes de datos.

Limpieza de recursos

Cuando trabaje con su propia suscripción, al final de un proyecto, es recomendable eliminar los recursos que ya no necesite. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Puede eliminar los recursos de forma individual o eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

Puede encontrar y administrar recursos en el portal, mediante el vínculo Todos los recursos o Grupos de recursos en el panel de navegación izquierdo.

Pasos siguientes

Ahora que está familiarizado con los aspectos básicos de la indexación de SQL Database, podemos abordar en detalle la configuración del indexador.

Configuración del indexador de SQL Database

Compartir por