Tutorial de C#: Cómo rastrear una base de datos de Azure SQL mediante los indexadores de Azure SearchC# Tutorial: Crawl an Azure SQL database using Azure Search indexers

Aprenda a configurar un indexador para extraer datos que permiten búsquedas de una base de datos de Azure SQL de ejemplo.Learn how to configure an indexer for extracting searchable data from a sample Azure SQL database. Los indexadores son un componente de Azure Search que rastrean orígenes de datos externos y rellenan un índice de búsqueda con contenido.Indexers are a component of Azure Search that crawl external data sources, populating a search index with content. De todos los indexadores, el más usado es el indexador de Azure SQL Database.Of all indexers, the indexer for Azure SQL Database is the most widely used.

Tener un profundo conocimiento de la configuración del indexador resulta de utilidad porque simplifica la cantidad de código que se tiene que escribir y mantener.Proficiency in indexer configuration is helpful because it simplifies the amount of code you have to write and maintain. En lugar de preparar e insertar un conjunto de datos JSON conforme a un esquema, puede asociar un indexador a un origen de datos, hacer que el indexador extraiga los datos y los inserte en un índice y, luego, de manera opcional, puede ejecutar el indexador según una programación recurrente para seleccionar los cambios en el origen subyacente.Rather than preparing and pushing a schema-compliant JSON dataset, you can attach an indexer to a data source, have the indexer extract data and insert it into an index, and optionally run the indexer on a recurring schedule to pick up changes in the underlying source.

En este tutorial, se usarán las bibliotecas cliente .NET de Azure Search y una aplicación de consola de .NET Core para realizar las siguientes tareas:In this tutorial, use the Azure Search .NET client libraries and a .NET Core console application to perform the following tasks:

  • Agregar información del servicio de búsqueda a la configuración de la aplicaciónAdd search service information to application settings
  • Preparar un conjunto de datos externo en la base de datos de Azure SQLPrepare an external dataset in Azure SQL database
  • Revisar las definiciones de índice e indexador en el código de ejemploReview the index and indexer definitions in sample code
  • Ejecutar el código de indexador para importar los datosRun the indexer code to import data
  • Buscar en el índiceSearch the index
  • Ver la configuración del indexador en el portalView indexer configuration in the portal

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Requisitos previosPrerequisites

En este inicio rápido se usan los siguientes servicios, herramientas y datos.The following services, tools, and data are used in this quickstart.

Cree un servicio Azure Search o busque un servicio existente en su suscripción actual.Create an Azure Search service or find an existing service under your current subscription. Puede usar un servicio gratuito para este tutorial.You can use a free service for this tutorial.

Azure SQL Database almacena el origen de datos externo usado por un indexador.Azure SQL Database stores the external data source used by an indexer. La solución de ejemplo proporciona un archivo de datos SQL para crear la tabla.The sample solution provides a SQL data file to create the table. En este tutorial se indican los pasos para crear el servicio y la base de datos.Steps for creating the service and database are provided in this tutorial.

Se puede usar cualquier edición de Visual Studio 2017 para ejecutar la solución de ejemplo.Visual Studio 2017, any edition, can be used to run the sample solution. Se han probado código de ejemplo e instrucciones en la edición Community Edition gratuita.Sample code and instructions were tested on the free Community edition.

En Azure-Samples/search-dotnet-getting-started puede encontrar la solución de ejemplo, en el repositorio de GitHub de ejemplos de Azure.Azure-Samples/search-dotnet-getting-started provides the sample solution, located in the Azure samples GitHub repository. Descargue y extraiga la solución.Download and extract the solution. De forma predeterminada, las soluciones son de solo lectura.By default, solutions are read-only. Haga clic con el botón derecho en la solución y borre el atributo de solo lectura para que se puedan modificar los archivos.Right-click the solution and clear the read-only attribute so that you can modify files.

Nota

Si va a usar el servicio gratuito de Azure Search, está limitado a tres índices, tres indexadores y tres orígenes de datos.If you are using the free Azure Search service, you are limited to three indexes, three indexers, and three data sources. En este tutorial se crea uno de cada uno.This tutorial creates one of each. Asegúrese de que haya espacio en el servicio para aceptar los nuevos recursos.Make sure you have room on your service to accept the new resources.

Obtención de una clave y una dirección URLGet a key and URL

Las llamadas de REST requieren la dirección URL del servicio y una clave de acceso en cada solicitud.REST calls require the service URL and an access key on every request. Con ambos se crea un servicio de búsqueda, por lo que si ha agregado Azure Search a su suscripción, siga estos pasos para obtener la información necesaria:A search service is created with both, so if you added Azure Search to your subscription, follow these steps to get the necessary information:

  1. Inicie sesión en Azure Portal y en la página Introducción del servicio de búsqueda, obtenga la dirección URL.Sign in to the Azure portal, and in your search service Overview page, get the URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.An example endpoint might look like https://mydemo.search.windows.net.

  2. En Configuración > Claves, obtenga una clave de administrador para tener derechos completos en el servicio.In Settings > Keys, get an admin key for full rights on the service. Se proporcionan dos claves de administrador intercambiables para lograr la continuidad empresarial, por si necesitara sustituir una de ellas.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Puede usar la clave principal o secundaria en las solicitudes para agregar, modificar y eliminar objetos.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

Obtención de una clave de acceso y un punto de conexión HTTPGet an HTTP endpoint and access key

Todas las solicitudes requieren una clave de API en cada solicitud enviada al servicio.All requests require an api-key on every request sent to your service. Tener una clave válida genera la confianza, solicitud a solicitud, entre la aplicación que envía la solicitud y el servicio que se encarga de ella.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

Configuración de las conexionesSet up connections

La información de conexión para los servicios requeridos se especifica en el archivo appsettings.json de la solución.Connection information to required services is specified in the appsettings.json file in the solution.

  1. En Visual Studio, abra el archivo DotNetHowToIndexers.sln.In Visual Studio, open the DotNetHowToIndexers.sln file.

  2. En el Explorador de soluciones, abra appsettings.json para que pueda rellenar cada valor de configuración.In Solution Explorer, open appsettings.json so that you can populate each setting.

Las dos primeras entradas las puede rellenar en este mismo momento mediante las claves de dirección URL y de administrador del servicio Azure Search.The first two entries you can fill in right now, using the URL and admin keys for your Azure Search service. Dado un punto de conexión de https://mydemo.search.windows.net, el nombre del servicio que debe proporcionar es mydemo.Given an endpoint of https://mydemo.search.windows.net, the service name to provide is mydemo.

{
  "SearchServiceName": "Put your search service name here",
  "SearchServiceAdminApiKey": "Put your primary or secondary API key here",
  "AzureSqlConnectionString": "Put your Azure SQL database connection string here",
}

La última entrada requiere una base de datos existente.The last entry requires an existing database. La creará en el paso siguiente.You'll create it in the next step.

Preparación de datos de ejemploPrepare sample data

En este paso, creará un origen de datos externo que se pueda rastrear con un indexador.In this step, create an external data source that an indexer can crawl. Puede usar Azure Portal y el archivo hotels.sql del ejemplo para crear el conjunto de datos en Azure SQL Database.You can use the Azure portal and the hotels.sql file from the sample to create the dataset in Azure SQL Database. Azure Search usa conjuntos de filas planas, como los que se generan a partir de una vista o una consulta.Azure Search consumes flattened rowsets, such as one generated from a view or query. El archivo SQL de la solución de ejemplo crea y rellena una sola tabla.The SQL file in the sample solution creates and populates a single table.

En el ejercicio siguiente se da por supuesto que no hay ningún servidor ni base de datos, y se le indica que cree ambos en el paso 2.The following exercise assumes no existing server or database, and instructs you to create both in step 2. Opcionalmente, si tiene un recurso existente, puede agregar en él la tabla de hoteles, a partir del paso 4.Optionally, if you have an existing resource, you can add the hotels table to it, starting at step 4.

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.

  2. Busque o cree una instancia de Azure SQL Database para crear una base de datos, un servidor y un grupo de recursos.Find or create an Azure SQL Database to create a database, server, and resource group. Puede usar los valores predeterminados y el plan de tarifa más bajo.You can use defaults and the lowest level pricing tier. Una ventaja de la creación de un servidor es que puede especificar un nombre de usuario y una contraseña de administrador, que son necesarios para crear y cargar las tablas en un paso posterior.One advantage to creating a server is that you can specify an administrator user name and password, necessary for creating and loading tables in a later step.

    Página Nueva base de datos

  3. Haga clic en Crear para implementar el nuevo servidor y la nueva base de datos.Click Create to deploy the new server and database. Espere a que se implementen el servidor y la base de datos.Wait for the server and database to deploy.

  4. Abra la página SQL Database de la nueva base de datos, si aún no está abierta.Open the SQL Database page for your new database, if it's not already open. En el nombre del recurso debe poner SQL Database y no SQL Server.The resource name should say SQL database and not SQL Server.

    Página SQL Database

  5. En el panel de navegación, haga clic en Editor de consultas (versión preliminar) .On the navigation pane, click Query editor (preview).

  6. Haga clic en Iniciar sesión y escriba el nombre de usuario y la contraseña del administrador del servidor.Click Login and enter the user name and password of server admin.

  7. Haga clic en Abrir consulta y navegue a la ubicación de hotels.sql.Click Open query and navigate to the location of hotels.sql.

  8. Seleccione el archivo y haga clic en Abrir.Select the file and click Open. El script debe tener un aspecto similar a la siguiente captura de pantalla:The script should look similar to the following screenshot:

    Script de SQL

  9. Haga clic en Ejecutar para ejecutar la consulta.Click Run to execute the query. En el panel de resultados, verá un mensaje de consulta correcta, correspondiente a 3 filas.In the Results pane, you should see a query succeeded message, for 3 rows.

  10. Para devolver un conjunto de filas de esta tabla, puede ejecutar la siguiente consulta como paso de comprobación:To return a rowset from this table, you can execute the following query as a verification step:

    SELECT HotelId, HotelName, Tags FROM Hotels
    

    La consulta prototipo, SELECT * FROM Hotels, no funciona en el Editor de consultas.The prototypical query, SELECT * FROM Hotels, doesn't work in the Query Editor. Los datos de ejemplo incluyen coordenadas geográficas en el campo Ubicación, que no se gestionan en el editor por el momento.The sample data includes geographic coordinates in the Location field, which is not handled in the editor at this time. Para obtener una lista de otras columnas para consultar, puede ejecutar esta instrucción:SELECT * FROM sys.columns WHERE object_id = OBJECT_ID('dbo.Hotels')For a list of other columns to query, you can execute this statement: SELECT * FROM sys.columns WHERE object_id = OBJECT_ID('dbo.Hotels')

  11. Ahora que tiene un conjunto de datos externo, copie la cadena de conexión de ADO.NET correspondiente a la base de datos.Now that you have an external dataset, copy the ADO.NET connection string for the database. En la página SQL Database de la base de datos, vaya a Configuración > Cadenas de conexión y copie la cadena de conexión de ADO.NET.On the SQL Database page of your database, go to Settings > Connection Strings, and copy the ADO.NET connection string.

    Una cadena de conexión de ADO.NET se parece al ejemplo siguiente, modificada para usar un nombre de base de datos, un nombre de usuario y una contraseña válidos.An ADO.NET connection string looks like the following example, modified to use a valid database name, user name, and password.

    Server=tcp:hotels-db.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;
    
  12. Pegue la cadena de conexión en "AzureSqlConnectionString" como tercera entrada en el archivo appsettings.json en Visual Studio.Paste the connection string into "AzureSqlConnectionString" as the third entry in appsettings.json file in Visual Studio.

    {
      "SearchServiceName": "<placeholder-Azure-Search-service-name>",
      "SearchServiceAdminApiKey": "<placeholder-admin-key-for-Azure-Search>",
      "AzureSqlConnectionString": "Server=tcp:hotels-db.database.windows.net,1433;Initial Catalog=hotels-db;Persist Security  Info=False;User ID={your_username};Password={your_password};MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;",
    }
    

Comprendiendo el códigoUnderstand the code

Una vez que los valores de configuración y los datos estén en su lugar, el ejemplo de programa de DotNetHowToIndexers.sln estará listo para la compilación y la ejecución.Once the data and configuration settings are in place, the sample program in DotNetHowToIndexers.sln is ready to build and run. Antes de hacerlo, dedique un minuto a estudiar las definiciones de índice e indexador de este ejemplo.Before doing that, take a minute to study the index and indexer definitions for this sample. El código pertinente aparece en dos archivos:The relevant code is in two files:

  • hotel.cs, que contiene el esquema que define el índice.hotel.cs, containing the schema that defines the index
  • Program.cs, que contiene las funciones para crear y administrar las estructuras del servicio.Program.cs, containing the functions for creating and managing structures in your service

En hotel.csIn 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.The index schema defines the fields collection, including attributes specifying allowed operations, such as whether a field is full-text searchable, filterable, or sortable as shown in the following field definition for HotelName.

. . . 
[IsSearchable, IsFilterable, IsSortable]
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.A schema can also include other elements, including scoring profiles for boosting a search score, custom analyzers, and other constructs. 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.However, for our purposes, the schema is sparsely defined, consisting only of fields found in the sample datasets.

En este tutorial, el indexador extrae los datos de un origen de datos.In this tutorial, the indexer pulls data from one data source. En la práctica, puede asociar varios indexadores al mismo índice y crear un índice de búsqueda consolidado a partir de varios orígenes de datos.In practice, you can attach multiple indexers to the same index, creating a consolidated searchable index from multiple data sources. Puede usar el mismo par de indexador-índice y variar solo los orígenes de datos, o un índice con varias combinaciones de indexador y origen de datos, según dónde necesite la flexibilidad.You can use the same index-indexer pair, varying just the data sources, or one index with various indexer and data source combinations, depending on where you need the flexibility.

En Program.csIn Program.cs

El programa principal incluye lógica para la creación de un cliente, un índice, un origen de datos y un indexador.The main program includes logic for creating a client, an index, a data source, and an indexer. 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.The code checks for and deletes existing resources of the same name, under the assumption that you might run this program multiple times.

El objeto de origen de datos está configurado con valores específicos de los recursos de Azure SQL Database, indexación incremental incluida, para aprovechar las características de detección de cambios integradas de Azure SQL.The data source object is configured with settings that are specific to Azure SQL database resources, including incremental indexing for leveraging the built-in change detection features of Azure SQL. La base de datos de demostración de hoteles de Azure SQL tiene una columna de "eliminación temporal" denominada IsDeleted.The demo hotels database in Azure SQL has a "soft delete" column named IsDeleted. Cuando esta columna se establece en true en la base de datos, el indexador quita el documento correspondiente del índice de Azure Search.When this column is set to true in the database, the indexer removes the corresponding document from the Azure Search index.

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

DataSource dataSource = DataSource.AzureSql(
    name: "azure-sql",
    sqlConnectionString: configuration["AzureSQLConnectionString"],
    tableOrViewName: "hotels",
    deletionDetectionPolicy: new SoftDeleteColumnDeletionDetectionPolicy(
        softDeleteColumnName: "IsDeleted",
        softDeleteMarkerValue: "true"));
dataSource.DataChangeDetectionPolicy = new SqlIntegratedChangeTrackingPolicy();

searchService.DataSources.CreateOrUpdateAsync(dataSource).Wait();

Los objetos de indexador son independientes de las plataformas, donde la configuración la programación y la invocación son siempre los mismos, no importa el origen.An indexer object is platform-agnostic, where configuration, scheduling, and invocation are the same regardless of the source. 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.This example indexer includes a schedule, a reset option that clears indexer history, and calls a method to create and run the indexer immediately.

Console.WriteLine("Creating Azure SQL indexer...");
Indexer indexer = new Indexer(
    name: "azure-sql-indexer",
    dataSourceName: dataSource.Name,
    targetIndexName: index.Name,
    schedule: new IndexingSchedule(TimeSpan.FromDays(1)));
// Indexers contain metadata about how much they have already indexed
// If we already ran the sample, the indexer will remember that it already
// indexed the sample data and not run again
// To avoid this, reset the indexer if it exists
exists = await searchService.Indexers.ExistsAsync(indexer.Name);
if (exists)
{
    await searchService.Indexers.ResetAsync(indexer.Name);
}

await searchService.Indexers.CreateOrUpdateAsync(indexer);

// We created the indexer with a schedule, but we also
// want to run it immediately
Console.WriteLine("Running Azure SQL indexer...");

try
{
    await searchService.Indexers.RunAsync(indexer.Name);
}
catch (CloudException e) when (e.Response.StatusCode == (HttpStatusCode)429)
{
    Console.WriteLine("Failed to run indexer: {0}", e.Response.Content);
}

Ejecución del indexadorRun the indexer

En este paso, compile y ejecute el programa.In this step, compile and run the program.

  1. En el Explorador de soluciones, haga clic con el botón derecho en DotNetHowToIndexers y seleccione Compilar.In Solution Explorer, right-click DotNetHowToIndexers and select Build.
  2. De nuevo, haga clic con el botón derecho en DotNetHowToIndexers, seguido de Depurar > Iniciar nueva instancia.Again, right-click DotNetHowToIndexers, followed by Debug > Start new instance.

El programa se ejecuta en modo de depuración.The program executes in debug mode. Una ventana de consola informa del estado de cada operación.A console window reports the status of each operation.

Script de SQL

El código se ejecuta localmente en Visual Studio y se conecta al servicio de búsqueda en Azure, que, a su vez, usa la cadena de conexión para conectarse a Azure SQL Database y recuperar el conjunto de datos.Your code runs locally in Visual Studio, connecting to your search service on Azure, which in turn uses the connection string to connect to Azure SQL Database and retrieve the dataset. Con estas muchas operaciones, existen varios posibles puntos de error, pero si recibe un error, compruebe primero las siguientes condiciones:With this many operations, there are several potential points of failure, but if you get an error, check the following conditions first:

  • La información de conexión del servicio de búsqueda que proporciona está limitada al nombre del servicio en este tutorial.Search service connection information that you provide is limited to the service name in this tutorial. Si escribió la dirección URL completa, las operaciones se detienen durante la creación del índice, con un error de conexión.If you entered the full URL, operations stop at index creation, with a failure to connect error.

  • La información de conexión de la base de datos appsettings.json.Database connection information in 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.It should be the ADO.NET connection string obtained from the portal, modified to include a username and password that are valid for your database. La cuenta de usuario debe tener permiso para recuperar datos.The user account must have permission to retrieve data.

  • Los límites de recursos.Resource limits. Recuerde que el servicio compartido (gratuito) tiene límites de tres índices, tres indexadores y tres orígenes de datos.Recall that the shared (free) service has limits of 3 indexes, indexers, and data sources. Un servicio en el límite máximo no puede crear nuevos objetos.A service at the maximum limit cannot create new objects.

Búsqueda en el índiceSearch the index

En Azure Portal, en la página Información general del servicio de búsqueda, haga clic en Explorador de búsqueda en la parte superior para enviar algunas consultas sobre el nuevo índice.In the Azure portal, in the search service Overview page, click Search explorer at the top to submit a few queries on the new index.

  1. Haga clic en Cambiar índice en la parte superior para seleccionar el índice hotels.Click Change index at the top to select the hotels index.

  2. Haga clic en el botón Buscar para emitir una búsqueda vacía.Click the Search button to issue an empty search.

    Las tres entradas del índice se devuelven como documentos JSON.The three entries in your index are returned as JSON documents. El Explorador de búsqueda devuelve documentos en JSON para que pueda ver la estructura completa.Search explorer returns documents in JSON so that you can view the entire structure.

  3. A continuación, escriba una cadena de búsqueda: search=river&$count=true.Next, enter a search string: 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.This query invokes full text search on the term river, and the result includes a count of the matching documents. 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.Returning the count of matching documents is helpful in testing scenarios when you have a large index with thousands or millions of documents. En este caso, solo un documento coincide con la consulta.In this case, only one document matches the query.

  4. Por último, escriba una cadena de búsqueda que limite la salida JSON a los campos de interés: search=river&$count=true&$select=hotelId, baseRate, description.Lastly, enter a search string that limits the JSON output to fields of interest: search=river&$count=true&$select=hotelId, baseRate, description.

    La respuesta de la consulta se reduce a los campos seleccionados, lo que da lugar a una salida más concisa.The query response is reduced to selected fields, resulting in more concise output.

Visualización de la configuración del indexadorView indexer configuration

Todos los indexadores, incluido el que acaba de crear mediante programación, se muestran en el portal.All indexers, including the one you just created programmatically, are listed in the portal. Puede abrir una definición de indexador y ver su origen de datos, o configurar una programación de actualización para seleccionar las filas nuevas y modificadas.You can open an indexer definition and view its data source, or configure a refresh schedule to pick up new and changed rows.

  1. Inicie sesión en Azure Portal y, en la página Información general del servicio de búsqueda, haga clic en los vínculos de Índices, Indexadores y Orígenes de datos.Sign in to the Azure portal, and in your search service Overview page, click the links for Indexes, Indexers, and Data Sources.

  2. Seleccione algún objeto individual para ver sus valores de configuración o modificarlos.Select individual objects to view or modify configuration settings.

    Iconos de indexador y origen de datos

Limpieza de recursosClean up resources

La manera más rápida de borrar el contenido después de un tutorial es eliminar el grupo de recursos que contiene el servicio Azure Search.The fastest way to clean up after a tutorial is by deleting the resource group containing the Azure Search service. Para eliminar de forma definitiva todo lo que contenga el grupo de recursos, elimine el grupo.You can delete the resource group now to permanently delete everything in it. En el portal, el nombre del grupo de recursos está en la página Información general de cada servicio Azure Search.In the portal, the resource group name is on the Overview page of Azure Search service.

Pasos siguientesNext steps

Puede asociar algoritmos de enriquecimiento por IA a una canalización del indexador.You can attach AI enrichment algorithms to an indexer pipeline. Como paso siguiente, continúe con el siguiente tutorial.As a next step, continue on with the following tutorial.