Compartir a través de

biblioteca cliente de Azure Cognitive Search para .NET: versión 11.4.0

  • Artículo

Azure Cognitive Search es una solución en la nube de búsqueda como servicio que proporciona a los desarrolladores las API y las herramientas necesarias para agregar una completa experiencia de búsqueda de datos a través de contenido privado y heterogéneo en aplicaciones web, móviles y empresariales.

El servicio Azure Cognitive Search es adecuado para los siguientes escenarios de aplicación:

  • Consolide diversos tipos de contenido en un único índice en el que se pueden realizar búsquedas. Para rellenar un índice, puede insertar documentos JSON que contengan el contenido o, si los datos ya están en Azure, cree un indexador para extraer datos automáticamente.
  • Adjunte conjuntos de aptitudes a un indexador para crear contenido que se pueda buscar a partir de imágenes y documentos de texto grandes. Un conjunto de aptitudes aprovecha la inteligencia artificial de Cognitive Services para OCR integrado, reconocimiento de entidades, extracción de frases clave, detección de idioma, traducción de texto y análisis de opiniones. También puede agregar aptitudes personalizadas para integrar el procesamiento externo del contenido durante la ingesta de datos.
  • En una aplicación cliente de búsqueda, implemente la lógica de consulta y las experiencias de usuario similares a los motores de búsqueda web comerciales.

Use la biblioteca cliente Azure.Search.Documents para:

  • Envíe consultas para formularios de consulta simples y avanzados que incluyen búsqueda aproximada, búsqueda con caracteres comodín, expresiones regulares.
  • Implemente consultas filtradas para la navegación por facetas, la búsqueda geoespacial o para restringir los resultados en función de los criterios de filtro.
  • Cree y administre índices de búsqueda.
  • Cargue y actualice documentos en el índice de búsqueda.
  • Cree y administre indizadores que extraen datos de Azure en un índice.
  • Cree y administre conjuntos de aptitudes que agregan enriquecimiento con inteligencia artificial a la ingesta de datos.
  • Cree y administre analizadores para el análisis de texto avanzado o el contenido multilingüe.
  • Optimice los resultados mediante perfiles de puntuación para factorizar la lógica de negocios o la actualización.

Código | fuente Paquete (NuGet) | Documentación | de referencia de API Documentación | de la API RESTDocumentación | del producto Muestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Cognitive Search para .NET con NuGet:

dotnet add package Azure.Search.Documents

Requisitos previos

Necesita una suscripción de Azure y un servicio de búsqueda para usar este paquete.

Para crear un nuevo servicio de búsqueda, puede usar el Azure Portal, Azure PowerShell o la CLI de Azure. Este es un ejemplo de uso de la CLI de Azure para crear una instancia gratuita para empezar:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

Consulte Elección de un plan de tarifa para obtener más información sobre las opciones disponibles.

Autenticar el cliente

Todas las solicitudes que se realizan a un servicio de búsqueda necesitan una clave de API generada de forma específica para el servicio. La clave de API es el único mecanismo para autenticar el acceso al punto de conexión del servicio de búsqueda. Puede obtener la clave de API de la Azure Portal o a través de la CLI de Azure:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

Hay dos tipos de claves que se usan para acceder al servicio de búsqueda: admin(read-write) y query(read-only). Restringir el acceso y las operaciones en las aplicaciones cliente es esencial para proteger los activos de búsqueda en el servicio. Use siempre una clave de consulta en lugar de una clave de administración para cualquier consulta originada desde una aplicación cliente.

Nota: El fragmento de código de la CLI de Azure de ejemplo anterior recupera una clave de administrador para que sea más fácil empezar a explorar las API, pero debe administrarse cuidadosamente.

Podemos usar la clave de API para crear un nuevo SearchClient.

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

Para insertar SearchClient como una dependencia en una aplicación de ASP.NET Core, instale primero el paquete Microsoft.Extensions.Azure. A continuación, registre el cliente en el Startup.ConfigureServices método :

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });
  
    services.AddControllers();
}

Para usar el código anterior, agréguelo a la configuración:

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

También tendrá que proporcionar la clave de recurso para autenticar al cliente, pero no debe colocar esa información en la configuración. En su lugar, cuando se está en desarrollo, use User-Secrets. Agregue lo siguiente a secrets.json:

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

Cuando se ejecuta en producción, es preferible usar variables de entorno:

SEARCH__CREDENTIAL__KEY="..."

O use otras formas seguras de almacenar secretos como Azure Key Vault.

Para más información sobre la inserción de dependencias en ASP.NET Core aplicaciones, consulte Inserción de dependencias con el SDK de Azure para .NET.

Conceptos clave

Un servicio Azure Cognitive Search contiene uno o varios índices que proporcionan almacenamiento persistente de datos que se pueden buscar en forma de documentos JSON. (Si no está familiarizado con la búsqueda, puede hacer una analogía muy aproximada entre índices y tablas de base de datos). La biblioteca cliente Azure.Search.Documents expone operaciones en estos recursos a través de tres tipos de cliente principales.

La Azure.Search.Documents biblioteca cliente (v11) es una nueva oferta para desarrolladores de .NET que quieren usar la tecnología de búsqueda en sus aplicaciones. Hay una biblioteca cliente antigua y completa Microsoft.Azure.Search (v10) con muchas API similares, por lo que debe tener cuidado de evitar confusiones al explorar recursos en línea. Una buena regla general es comprobar el espacio de nombres using Azure.Search.Documents; cuando nos busca.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

En los ejemplos siguientes se usa un conjunto de datos hotel sencillo que se puede importar en su propio índice desde el Azure Portal. Estos son solo algunos de los conceptos básicos: consulte nuestros ejemplos para mucho más.

Autenticación avanzada

Consultas

Empecemos importando nuestros espacios de nombres.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;

A continuación, crearemos un SearchClient para acceder al índice de búsqueda de hoteles.

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

Hay dos maneras de interactuar con los datos devueltos desde una consulta de búsqueda. Vamos a explorarlos con una búsqueda de un hotel de lujo.

Uso de tipos de C# para los resultados de búsqueda

Podemos decorar nuestros propios tipos de C# con atributos de System.Text.Json:

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

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

A continuación, los usamos como parámetro de tipo al consultar para devolver resultados de búsqueda fuertemente tipados:

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

Si está trabajando con un índice de búsqueda y conoce el esquema, se recomienda crear tipos de C#.

Usar SearchDocument como un diccionario para los resultados de búsqueda

Si no tiene su propio tipo para los resultados de búsqueda, SearchDocument puede usarse en su lugar. Aquí se realiza la búsqueda, se enumeran los resultados y se extraen datos mediante SearchDocumentel indizador de diccionario de .

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine("{id}: {name}");
}

SearchOptions

SearchOptions Proporciona un control eficaz sobre el comportamiento de nuestras consultas. Vamos a buscar los 5 hoteles de lujo principales con una buena puntuación.

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

Creación de un índice

Puede usar SearchIndexClient para crear un índice de búsqueda. Los campos se pueden definir a partir de una clase de modelo mediante FieldBuilder. Los índices también pueden definir proveedores de sugerencias, analizadores léxicos, etc.

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

En escenarios en los que no se conoce el modelo o no se puede modificar, también puede crear campos explícitamente mediante clases cómodas SimpleField, SearchableFieldo ComplexField :

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "hotelName")
    }
};

client.CreateIndex(index);

Adición de documentos al índice

Puede Upload, Merge, MergeOrUploady Delete varios documentos de un índice en una única solicitud por lotes. Hay algunas reglas especiales para que la combinación tenga en cuenta.

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

La solicitud se realizará correctamente incluso si alguna de las acciones individuales produce un error y devuelve una IndexDocumentsResult para su inspección. También hay una ThrowOnAnyError opción si solo le importa el éxito o el error de todo el lote.

Recuperación de un documento específico del índice

Además de consultar documentos mediante palabras clave y filtros opcionales, puede recuperar un documento específico del índice si ya conoce la clave. Puede obtener la clave de una consulta, por ejemplo, y desea mostrar más información sobre ella o navegar por el cliente a ese documento.

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

API asincrónicas

Todos los ejemplos hasta ahora han estado usando API sincrónicas, pero también proporcionamos compatibilidad completa con las API asincrónicas. Por lo general, simplemente agregará un Async sufijo al nombre del método y await a él.

SearchResults<Hotel> response = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

Autenticación en una nube nacional

Para autenticarse en una nube nacional, deberá realizar las siguientes adiciones a la configuración del cliente:

  • Establecer en AuthorityHost las opciones de credenciales o a través de la variable de AZURE_AUTHORITY_HOST entorno
  • Establecer en AudienceSearchClientOptions
// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

Solución de problemas

Cualquier operación Azure.Search.Documents que produzca un error producirá un RequestFailedException con códigos útilesStatus. Muchos de estos errores son recuperables.

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

También puede habilitar el registro de la consola fácilmente si desea profundizar más en las solicitudes que realiza en el servicio.

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

Contribuir

Consulte nuestra CONTRIBUTING.md de búsqueda para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones