biblioteca cliente de Azure Cognitive Search para Java: versión 11.5.12

  • Artículo

Esta es la biblioteca cliente de Java para Azure Cognitive Search. Azure Cognitive Search servicio es una solución en la nube de búsqueda como servicio que proporciona a los desarrolladores API y herramientas para agregar una experiencia de búsqueda enriquecida a través de contenido privado 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 de Azure Cognitive Search 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 | fuentePaquete (Maven) | Documentación | de referencia de APIDocumentación | del productoMuestras

Introducción

Inclusión del paquete

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-search-documents</artifactId>
    <version>11.5.12</version>
</dependency>

Requisitos previos

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

Para interactuar con el servicio Azure Cognitive Search, deberá crear una instancia de la clase Search Client. Para que esto sea posible, necesitará,

  1. Punto de conexión de dirección URL
  2. Clave de API

del 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>

Nota:

  • El fragmento de código de la CLI de Azure de ejemplo anterior recupera una clave de administrador. Esto permite un acceso más fácil al explorar las API, pero debe administrarse cuidadosamente.
  • 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.

El SDK proporciona tres clientes.

  • SearchIndexClient para las operaciones CRUD en índices y mapas de sinónimos.
  • SearchIndexerClient para las operaciones CRUD en indexadores, orígenes de fecha y conjuntos de aptitudes.
  • SearchClient para todas las operaciones de documento.

Creación de una clase SearchIndexClient

Para crear un SearchIndexClient/SearchIndexAsyncClient, necesitará los valores del punto de conexión de dirección URL de servicio de Azure Cognitive Search y la clave de administrador.

SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

o

SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

Creación de una clase SearchIndexerClient

Para crear un SearchIndexerClient/SearchIndexerAsyncClient, necesitará los valores del punto de conexión de dirección URL de servicio de Azure Cognitive Search y la clave de administrador.

SearchIndexerClient searchIndexerClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildClient();

o

SearchIndexerAsyncClient searchIndexerAsyncClient = new SearchIndexerClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(apiKey))
    .buildAsyncClient();

Creación de una clase SearchClient

Una vez que tenga los valores del punto de conexión de dirección URL del servicio Azure Cognitive Search y la clave de administrador, puede crear con SearchClient/SearchAsyncClient un nombre de índice existente:

SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildClient();

o

SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .credential(new AzureKeyCredential(adminKey))
    .indexName(indexName)
    .buildAsyncClient();

Envío de la primera consulta de búsqueda

Para ejecutarse con Azure Cognitive Search primero, cree un índice siguiendo esta guía. Con un índice creado, puede usar los ejemplos siguientes para empezar a usar el SDK.

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 azure-search-documents biblioteca cliente expone operaciones en estos recursos a través de dos tipos de cliente principales.

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.

Consultas

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.

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

SearchDocument es el tipo predeterminado que se devuelve de las consultas cuando no proporciona su propio. Aquí se realiza la búsqueda, se enumeran los resultados y se extraen datos mediante SearchDocumentel indizador de diccionario de .

for (SearchResult searchResult : searchClient.search("luxury")) {
    SearchDocument doc = searchResult.getDocument(SearchDocument.class);
    String id = (String) doc.get("hotelId");
    String name = (String) doc.get("hotelName");
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

Uso de la clase de modelo de Java para los resultados de búsqueda

Defina una clase Hotel.

public class Hotel {
    private String id;
    private String name;

    public String getId() {
        return id;
    }

    public Hotel setId(String id) {
        this.id = id;
        return this;
    }

    public String getName() {
        return name;
    }

    public Hotel setName(String name) {
        this.name = name;
        return this;
    }
}

Úselo en lugar de SearchDocument al realizar consultas.

for (SearchResult searchResult : searchClient.search("luxury")) {
    Hotel doc = searchResult.getDocument(Hotel.class);
    String id = doc.getId();
    String name = doc.getName();
    System.out.printf("This is hotelId %s, and this is hotel name %s.%n", id, name);
}

Se recomienda, cuando conozca el esquema del índice de búsqueda, para crear una clase de modelo de Java.

Opciones de búsqueda

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.

SearchOptions options = new SearchOptions()
    .setFilter("rating ge 4")
    .setOrderBy("rating desc")
    .setTop(5);
SearchPagedIterable searchResultsIterable = searchClient.search("luxury", options, Context.NONE);
// ...

Creación de un índice

Puede usar SearchIndexClient para crear un índice de búsqueda. Los índices también pueden definir proveedores de sugerencias, analizadores léxicos, etc.

Hay varias maneras de preparar los campos de búsqueda para un índice de búsqueda. Para las necesidades básicas, proporcionamos un método buildSearchFields auxiliar estático en y SearchIndexAsyncClient, que puede convertir la clase POJO de Java en SearchIndexClientList<SearchField>. Hay tres anotaciones SimpleFieldPropertySearchFieldProperty y FieldBuilderIgnore para configurar el campo de la clase de modelo.

List<SearchField> searchFields = SearchIndexClient.buildSearchFields(Hotel.class, null);
searchIndexClient.createIndex(new SearchIndex("index", searchFields));

En escenarios avanzados, podemos crear campos de búsqueda mediante SearchField directamente.

List<SearchField> searchFieldList = new ArrayList<>();
searchFieldList.add(new SearchField("hotelId", SearchFieldDataType.STRING)
    .setKey(true)
    .setFilterable(true)
    .setSortable(true));

searchFieldList.add(new SearchField("hotelName", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setFilterable(true)
    .setSortable(true));
searchFieldList.add(new SearchField("description", SearchFieldDataType.STRING)
    .setSearchable(true)
    .setAnalyzerName(LexicalAnalyzerName.EU_LUCENE));
searchFieldList.add(new SearchField("tags", SearchFieldDataType.collection(SearchFieldDataType.STRING))
    .setSearchable(true)
    .setFilterable(true)
    .setFacetable(true));
searchFieldList.add(new SearchField("address", SearchFieldDataType.COMPLEX)
    .setFields(new SearchField("streetAddress", SearchFieldDataType.STRING).setSearchable(true),
        new SearchField("city", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("stateProvince", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("country", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true),
        new SearchField("postalCode", SearchFieldDataType.STRING)
            .setSearchable(true)
            .setFilterable(true)
            .setFacetable(true)
            .setSortable(true)
    ));

// Prepare suggester.
SearchSuggester suggester = new SearchSuggester("sg", Collections.singletonList("hotelName"));
// Prepare SearchIndex with index name and search fields.
SearchIndex index = new SearchIndex("hotels").setFields(searchFieldList).setSuggesters(suggester);
// Create an index
searchIndexClient.createIndex(index);

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 hotel = searchClient.getDocument("1", Hotel.class);
System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());

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 = new IndexDocumentsBatch<>();
batch.addUploadActions(Collections.singletonList(new Hotel().setId("783").setName("Upload Inn")));
batch.addMergeActions(Collections.singletonList(new Hotel().setId("12").setName("Renovated Ranch")));
searchClient.indexDocuments(batch);

La solicitud se iniciará IndexBatchException de forma predeterminada si se produce un error en alguna de las acciones individuales y puede usar findFailedActionsToRetry para reintentar en documentos con errores. También hay una throwOnAnyError opción y puede establecerla en false para obtener una respuesta correcta con una IndexDocumentsResult para su inspección.

API asincrónicas

Los ejemplos hasta ahora han usado API sincrónicas, pero también proporcionamos compatibilidad completa con las API asincrónicas. Deberá usar SearchAsyncClient.

searchAsyncClient.search("luxury")
    .subscribe(result -> {
        Hotel hotel = result.getDocument(Hotel.class);
        System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.getId(), hotel.getName());
    });

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 audienceSearchClientBuilder, SearchIndexClientBuildero SearchIndexerClientBuilder
// Create a SearchClient that will authenticate through AAD in the China national cloud.
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(endpoint)
    .indexName(indexName)
    .credential(new DefaultAzureCredentialBuilder()
        .authorityHost(AzureAuthorityHosts.AZURE_CHINA)
        .build())
    .audience(SearchAudience.AZURE_CHINA)
    .buildClient();

Solución de problemas

General

Al interactuar con Azure Cognitive Search mediante esta biblioteca cliente de Java, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de LA API REST. Por ejemplo, el servicio devolverá un 404 error si intenta recuperar un documento que no existe en el índice.

Control de la respuesta de errores de búsqueda

Cualquier operación de Search API que produzca un error producirá una HttpResponseException excepción con útil Status codes. Muchos de estos errores son recuperables.

try {
    Iterable<SearchResult> results = searchClient.search("hotel");
} catch (HttpResponseException ex) {
    // The exception contains the HTTP status code and the detailed message
    // returned from the search service
    HttpResponse response = ex.getResponse();
    System.out.println("Status Code: " + response.getStatusCode());
    System.out.println("Message: " + ex.getMessage());
}

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

Habilitar el registro

Los SDK de Azure para Java proporcionan un artículo de registro coherente para ayudar a solucionar errores de aplicación y acelerar su resolución. Los registros generados capturarán el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz. Vea la wiki de registro para obtener instrucciones sobre cómo habilitar el registro.

Cliente HTTP predeterminado

De forma predeterminada, se usará un cliente HTTP basado en Netty. La wiki de clientes HTTP proporciona más información sobre cómo configurar o cambiar el cliente HTTP.

Pasos siguientes

Contribuciones

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.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

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