Azure Cognitive Search biblioteca de clientes para Java – versão 11.5.12

  • Artigo

Esta é a biblioteca de clientes Java para Azure Cognitive Search. Azure Cognitive Search serviço é uma solução de nuvem de pesquisa como serviço que oferece aos desenvolvedores APIs e ferramentas para adicionar uma experiência de pesquisa avançada sobre conteúdo privado e heterogêneo em aplicativos Web, móveis e empresariais.

O serviço Azure Cognitive Search é adequado para os seguintes cenários de aplicativo:

  • Consolide tipos de conteúdo variados em um único índice pesquisável. Para preencher um índice, você pode enviar por push documentos JSON que contenham seu conteúdo ou, se os dados já estiverem no Azure, crie um indexador para efetuar pull dos dados automaticamente.

  • Anexe conjuntos de habilidades a um indexador para criar conteúdo pesquisável a partir de imagens e documentos de texto grandes. Um conjunto de habilidades aproveita a IA dos Serviços Cognitivos para OCR interno, reconhecimento de entidade, extração de frases-chave, detecção de idioma, tradução de texto e análise de sentimento. Você também pode adicionar habilidades personalizadas para integrar o processamento externo do seu conteúdo durante a ingestão de dados.

  • Em um aplicativo cliente de pesquisa, implemente a lógica de consulta e as experiências do usuário semelhantes aos mecanismos de pesquisa da Web comerciais.

Use a biblioteca de clientes Azure Cognitive Search para:

  • Envie consultas para formulários de consulta simples e avançados que incluem pesquisa difusa, pesquisa curinga, expressões regulares.
  • Implemente consultas filtradas para navegação facetada, pesquisa geoespacial ou para restringir os resultados com base em critérios de filtro.
  • Criar e gerenciar índices de pesquisa.
  • Carregar e atualizar documentos no índice de pesquisa.
  • Crie e gerencie indexadores que efetuam pull de dados do Azure para um índice.
  • Crie e gerencie conjuntos de habilidades que adicionam enriquecimento de IA à ingestão de dados.
  • Crie e gerencie analisadores para análise de texto avançada ou conteúdo multilíngue.
  • Otimize os resultados por meio de perfis de pontuação para considerar a lógica de negócios ou a atualização.

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Incluir o pacote

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

Pré-requisitos

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

Consulte escolher um tipo de preço para obter mais informações sobre as opções disponíveis.

Autenticar o cliente

Para interagir com o serviço Azure Cognitive Search, você precisará criar uma instância da classe Pesquisar Cliente. Para tornar isso possível, você precisará,

  1. Ponto de extremidade de URL
  2. Chave de API

para o serviço. A chave de api é o único mecanismo para autenticar o acesso ao ponto de extremidade de serviço de pesquisa. Você pode obter sua chave de api do portal do Azure ou por meio da CLI do Azure:

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

Observação:

  • O snippet de exemplo da CLI do Azure acima recupera uma chave de administrador. Isso permite um acesso mais fácil ao explorar APIs, mas deve ser gerenciado com cuidado.
  • Há dois tipos de chaves usadas para acessar o serviço de pesquisa: admin(leitura-gravação) e chaves de consulta(somente leitura). Restringir o acesso e as operações em aplicativos cliente é essencial para proteger os ativos de pesquisa em seu serviço. Sempre use uma chave de consulta em vez de uma chave de administração para qualquer consulta proveniente de um aplicativo cliente.

O SDK fornece três clientes.

  • SearchIndexClient para operações CRUD em índices e mapas de sinônimos.
  • SearchIndexerClient para operações CRUD em indexadores, fontes de data e conjuntos de habilidades.
  • SearchClient para todas as operações de documento.

Criar um SearchIndexClient

Para criar um SearchIndexClient/SearchIndexAsyncClient, você precisará dos valores do ponto de extremidade da URL do serviço Azure Cognitive Search e da chave de administração.

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

ou

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

Criar um SearchIndexerClient

Para criar um SearchIndexerClient/SearchIndexerAsyncClient, você precisará dos valores do ponto de extremidade da URL do serviço Azure Cognitive Search e da chave de administração.

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

ou

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

Criar um SearchClient

Depois de ter os valores do ponto de extremidade e da chave de administração da URL do serviço Azure Cognitive Search, você poderá criar o SearchClient/SearchAsyncClient com um nome de índice existente:

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

ou

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

Enviar sua primeira consulta de pesquisa

Para começar a executar com Azure Cognitive Search primeiro crie um índice seguindo este guia. Com um índice criado, você pode usar os exemplos a seguir para começar a usar o SDK.

Principais conceitos

Um serviço Azure Cognitive Search contém um ou mais índices que fornecem armazenamento persistente de dados pesquisáveis na forma de documentos JSON. (Se você não estiver familiarizado com a pesquisa, poderá fazer uma analogia muito aproximada entre índices e tabelas de banco de dados.) A azure-search-documents biblioteca de clientes expõe operações nesses recursos por meio de dois tipos de cliente main.

Exemplos

Todos os exemplos a seguir usam um conjunto de dados hoteleiro simples que você pode importar para seu próprio índice do portal do Azure. Estes são apenas alguns dos conceitos básicos - por favor, marcar nossos Exemplos para muito mais.

Consultas

Há duas maneiras de interagir com os dados retornados de uma consulta de pesquisa.

Vamos explorá-los com uma busca por um hotel de "luxo".

Usar SearchDocument como um dicionário para resultados da pesquisa

SearchDocument é o tipo padrão retornado de consultas quando você não fornece o seu próprio. Aqui, executamos a pesquisa, enumeramos sobre os resultados e extraímos dados usando SearchDocumento indexador de dicionário do .

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);
}

Usar a classe de modelo Java para resultados da pesquisa

Definir um Hotel classe.

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;
    }
}

Use-o no lugar de SearchDocument ao consultar.

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);
}

É recomendável, quando você souber o esquema do índice de pesquisa, criar uma classe de modelo Java.

Opções de pesquisa

O SearchOptions fornece um controle poderoso sobre o comportamento de nossas consultas.

Vamos procurar os 5 melhores hotéis de luxo com uma boa classificação.

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

Criando um índice

Você pode usar o SearchIndexClient para criar um índice de pesquisa. Os índices também podem definir sugestores, analisadores léxicos e muito mais.

Há várias maneiras de preparar campos de pesquisa para um índice de pesquisa. Para necessidades básicas, fornecemos um método buildSearchFields auxiliar estático em SearchIndexClient e SearchIndexAsyncClient, que podem converter a classe JAVA POJO em List<SearchField>. Há três anotações SimpleFieldPropertySearchFieldProperty e FieldBuilderIgnore para configurar o campo da classe de modelo.

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

Para cenários avançados, podemos criar campos de pesquisa usando SearchField diretamente.

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);

Recuperando um documento específico do índice

Além de consultar documentos usando palavras-chave e filtros opcionais, você pode recuperar um documento específico do índice se já souber a chave. Você pode obter a chave de uma consulta, por exemplo, e deseja mostrar mais informações sobre ela ou navegar pelo cliente para esse 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());

Adicionando documentos ao índice

Você pode Upload, Merge, MergeOrUploade Delete vários documentos de um índice em uma única solicitação em lote. Há algumas regras especiais para mesclar para estar ciente.

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);

A solicitação será gerada IndexBatchException por padrão se qualquer uma das ações individuais falhar e você puder usar findFailedActionsToRetry para tentar novamente documentos com falha. Há também uma throwOnAnyError opção e você pode defini-la como false para obter uma resposta bem-sucedida com uma IndexDocumentsResult para inspeção.

APIs assíncronas

Os exemplos até agora têm usado APIs síncronas, mas também fornecemos suporte completo para APIs assíncronas. Você precisará 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());
    });

Autenticar em uma nuvem nacional

Para se autenticar em uma Nuvem Nacional, você precisará fazer as seguintes adições à configuração do cliente:

  • Defina o AuthorityHost nas opções de credencial ou por meio da AZURE_AUTHORITY_HOST variável de ambiente
  • Definir o audience em SearchClientBuilder, SearchIndexClientBuilderou 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();

Solução de problemas

Geral

Quando você interage com Azure Cognitive Search usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações da API REST. Por exemplo, o serviço retornará um 404 erro se você tentar recuperar um documento que não existe no índice.

Tratamento da resposta de erro de pesquisa

Qualquer operação de API de Pesquisa que falhar lançará um HttpResponseException com útil Status codes. Muitos desses erros são recuperáveis.

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());
}

Também é possível habilitar registro em log do console facilmente se quiser se aprofundar nas solicitações que está fazendo ao serviço.

Habilitando o registro em log

Os SDKs do Azure para Java fornecem uma história de registro em log consistente para ajudar a solucionar problemas de erros do aplicativo e agilizar sua resolução. Os logs produzidos capturam o fluxo de um aplicativo antes que acessem o estado do terminal para ajudar a localizar o problema raiz. Exiba o wiki de log para obter diretrizes sobre como habilitar o registro em log.

Cliente HTTP padrão

Por padrão, um cliente HTTP baseado em Netty será usado. O wiki de clientes HTTP fornece mais informações sobre como configurar ou alterar o cliente HTTP.

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões