Compartir a través de

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

Aprenda a configurar un indexer para extraer datos que se pueden buscar de Azure SQL Database y enviarlos a un índice de búsqueda en Azure AI Search.

En este tutorial, usará C# y el SDK Azure para .NET para:

  • Creación de un origen de datos que se conecta 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

Requisitos previos

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 tiene 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 de la carpeta Azure-Samples/search-dotnet-getting-started GitHub.

Creación de servicios

En este tutorial se usa Azure AI Search para indexar y consultar 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.

Comience 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 consume conjuntos de filas aplanados, como los generados a partir de una vista o 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 agregar la tabla hotels a ella a partir del paso Open query.

  1. Crear un Azure SQL database. La configuración del servidor para la base de datos es importante:

    • Elija la opción de autenticación SQL Server que le pide que especifique un nombre de usuario y una contraseña. Necesita esto para la cadena de conexión de ADO.NET utilizada por el indizador.

    • Elija una conexión pública, lo que facilita la realización de este tutorial. No se recomienda público para producción y se recomienda eliminar este recurso al final del tutorial.

    Recorte de pantalla de la configuración del servidor.

  2. En el Azure portal, vaya al nuevo recurso.

  3. Agregar una regla de firewall que permita acceso desde tu cliente Puede ejecutar ipconfig desde un símbolo del sistema para obtener la dirección IP.

  4. Use el Query editor para cargar los datos de ejemplo. En el panel de navegación, seleccione Query editor (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 para el servidor y agregue una regla de entrada que permita el acceso desde el cliente.

  5. En Query editor, seleccione Abrir consulta y vaya a la ubicación de hotels.sql archivo en el equipo local.

  6. Seleccione el archivo y elija Abrir. El script debe tener un aspecto similar a la siguiente captura de pantalla:

    Captura de pantalla de un script SQL en una ventana del Editor de Consultas.

  7. Seleccione Ejecutar para ejecutar la consulta. En el panel Resultados, debe ver un mensaje de consulta correcta, correspondiente a tres filas.

  8. Para devolver un conjunto de filas de esta tabla, puede ejecutar la siguiente consulta como paso de comprobación:

    SELECT * FROM Hotels

  9. Copie la cadena de conexión ADO.NET para la base de datos. En Settings>Connection Strings, copie el ADO.NET connection string, que debe ser similar al 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á este connection string para configurar el entorno en el paso siguiente.

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

Las llamadas API requieren la dirección URL del servicio y una clave de access. Se crea un search service con ambos, por lo que si ha agregado Azure AI Search a la suscripción, siga estos pasos para obtener la información necesaria:

  1. Vaya al servicio de búsqueda en Azure Portal.

  2. En la página Información general , copie la dirección URL del punto de conexión. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.

  3. En Claves de configuración>, obtenga una clave de administrador para obtener 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 cualquiera de las claves en las solicitudes para agregar, modificar o eliminar objetos.

    Captura de pantalla de páginas del portal de Azure que muestran el punto de conexión HTTP y la ubicación de la clave de acceso para un servicio de búsqueda.

Configuración del entorno

  1. Inicie Visual Studio y abra DotNetHowToIndexers.sln.

  2. En Solution Explorer, abra appsettings.json para proporcionar información de conexión.

  3. Para SearchServiceEndPoint, si la URL completa de la página Overview de su servicio es https://my-demo-service.search.windows.net, proporcione la URL completa.

  4. Para AzureSqlConnectionString, el formato de cadena es similar 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. Reemplace la contraseña de usuario en el connection string de SQL por una contraseña válida. Aunque la base de datos y los nombres de usuario se copiarán, debe escribir la contraseña manualmente.

Creación de la canalización

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

  • hotel.cs contiene un esquema que define el índice
  • Program.cs contiene funciones para crear y administrar estructuras en el servicio

En hotel.cs

El esquema de índice define la colección fields, incluidos los atributos que especifican las operaciones permitidas, como si un campo es de texto completo que se puede buscar, filtrar o ordenar, como se muestra en la siguiente definición de campo para HotelName. Un SearchableField es, por definición, buscable de texto completo. Se asignan explícitamente otros atributos.

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

Un esquema también puede incluir otros elementos, como perfiles de puntuación para aumentar una puntuación de búsqueda y analizadores personalizados. Sin embargo, para este tutorial, el esquema se define dispersamente, que consta solo de campos que se encuentran en los conjuntos de datos de ejemplo.

En Program.cs

El programa principal incluye lógica para crear cliente de indexador, un índice, un origen de datos y un indexador. El código comprueba y elimina los recursos existentes del mismo nombre, suponiendo que pueda ejecutar este programa varias veces.

El objeto de origen de datos se configura con valores específicos para los recursos de Azure SQL Database, incluidas la indexación parcial o incremental para usar las funciones 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);

Un objeto indexador es independiente de la plataforma, donde la configuración, la programación y la invocación son iguales independientemente del origen. Este indexador de ejemplo incluye una programación y una opción de restablecimiento que borra el historial del indexador. También llama a un método para crear y ejecutar el indexador inmediatamente. Para crear o actualizar un 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);

Normalmente, las ejecuciones del indexador se programan, pero durante el desarrollo, es posible que desee ejecutar el indexador inmediatamente mediante 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);
}

Compile la solución

Seleccione 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.

Captura de pantalla que muestra la salida de la consola del programa.

El código se ejecuta localmente en Visual Studio, conectándose a la search service 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 usted proporcione es la dirección URL completa. Si solo introdujiste el nombre del servicio, las operaciones se detienen durante la creación del índice, debido a un error de conexión.

  • La información de conexión de la base de datos appsettings.json. Debe ser el ADO.NET connection string obtenido de la Azure portal, modificado para incluir un nombre de usuario y una contraseña 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.

Use el Azure portal para comprobar la creación de objetos y, a continuación, use Search explorer para consultar el índice.

  1. Vaya al servicio de búsqueda en Azure Portal.

  2. En el panel izquierdo, abra cada página para comprobar que se crean los objetos. Los índices, indexadores y orígenes de datos deben tener hotels-sql-idx, hotels-sql-idxr y hotels-sql-ds, respectivamente.

  3. 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.

  4. 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.

    Captura de pantalla de una consulta del Explorador de búsqueda para el índice de destino.

  5. Cambie a la vista JSON para que pueda escribir parámetros de consulta.

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

    Esta consulta invoca la búsqueda de texto completo en el término river. El resultado incluye un recuento de los documentos coincidentes. Devolver el recuento de documentos coincidentes es útil en escenarios de prueba en los que tiene un índice grande con miles o millones de documentos. En este caso, solo un documento coincide con la consulta.

  6. 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 fases experimentales del 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 los recompile. 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 Azure portal para eliminar índices, indexadores y orígenes de datos.

Limpieza de recursos

Cuando trabajas en tu propia suscripción, al finalizar un proyecto, es una buena idea eliminar los recursos que ya no necesitas. 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 Azure 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 conceptos básicos de la indexación de SQL Database, eche un vistazo más a la configuración del indexador:

Configuración del indexador de SQL Database

  • Last updated on