Azure Cognitive Search biblioteca de clientes para .NET – versão 11.4.0

  • Artigo

O Azure Cognitive Search é uma solução de pesquisa como serviço na nuvem que oferece aos desenvolvedores APIs e ferramentas para adicionar uma experiência de pesquisa sofisticada a um conteúdo particular 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 contêm 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 do Azure.Search.Documents 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 (NuGet) | Documentação | de referência da API Documentação | da API RESTDocumentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Azure Cognitive Search para .NET com o NuGet:

dotnet add package Azure.Search.Documents

Pré-requisitos

Você precisa de uma assinatura do Azure e um serviço de pesquisa para usar esse pacote.

Para criar um novo serviço de pesquisa, você pode usar o portal do Azure, Azure PowerShell ou a CLI do Azure. Aqui está um exemplo usando a CLI do Azure para criar uma instância gratuita para começar:

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

Todas as solicitações para um serviço de pesquisa precisam de uma chave de api gerada especificamente para o seu 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>

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.

Observação: o snippet de exemplo da CLI do Azure acima recupera uma chave de administrador para que seja mais fácil começar a explorar APIs, mas deve ser gerenciado com cuidado.

Podemos usar a chave de api para criar um novo 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 injetar SearchClient como uma dependência em um aplicativo ASP.NET Core, primeiro instale o pacote Microsoft.Extensions.Azure. Em seguida, registre o cliente no Startup.ConfigureServices método :

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

Para usar o código anterior, adicione isso à sua configuração:

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

Você também precisará fornecer sua chave de recurso para autenticar o cliente, mas não deve colocar essas informações na configuração. Em vez disso, quando estiver em desenvolvimento, use User-Secrets. Adicione o seguinte a secrets.json:

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

Ao executar em produção, é preferível usar variáveis de ambiente:

SEARCH__CREDENTIAL__KEY="..."

Ou use outras maneiras seguras de armazenar segredos, como o Azure Key Vault.

Para obter mais detalhes sobre a Injeção de Dependência em aplicativos ASP.NET Core, consulte Injeção de dependência com o SDK do Azure para .NET.

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ê for totalmente novo para pesquisar, poderá fazer uma analogia muito aproximada entre índices e tabelas de banco de dados.) A biblioteca de clientes do Azure.Search.Documents expõe operações nesses recursos por meio de três tipos de cliente main.

A Azure.Search.Documents biblioteca de clientes (v11) é uma nova oferta para desenvolvedores do .NET que desejam usar a tecnologia de pesquisa em seus aplicativos. Há uma biblioteca de clientes mais antiga e totalmente em Microsoft.Azure.Search destaque (v10) com muitas APIs semelhantes, portanto, tenha cuidado para evitar confusão ao explorar recursos online. Uma boa regra geral é marcar para o namespace using Azure.Search.Documents; quando você está procurando por nós.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | cliente Acessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

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.

Autenticação avançada

Consultas

Vamos começar importando nossos namespaces.

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

Em seguida, criaremos um SearchClient para acessar nosso índice de pesquisa de hotéis.

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

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 tipos C# para resultados da pesquisa

Podemos decorar nossos próprios tipos C# com 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; }
}

Em seguida, os usamos como o parâmetro de tipo ao consultar para retornar resultados de pesquisa fortemente tipado:

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

Se você estiver trabalhando com um índice de pesquisa e souber o esquema, é recomendável criar tipos C#.

Usar SearchDocument como um dicionário para resultados da pesquisa

Se você não tiver seu próprio tipo para resultados da pesquisa, SearchDocument poderá ser usado. Aqui, executamos a pesquisa, enumeramos sobre os resultados e extraímos dados usando SearchDocumento indexador de dicionário do .

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

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.

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

Criando um índice

Você pode usar o SearchIndexClient para criar um índice de pesquisa. Os campos podem ser definidos de uma classe de modelo usando FieldBuilder. Os índices também podem definir sugestores, analisadores léxicos e muito mais:

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

Em cenários em que o modelo não é conhecido ou não pode ser modificado, você também pode criar campos explicitamente usando classes convenientes SimpleField, SearchableFieldou 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);

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

A solicitação terá êxito mesmo se qualquer uma das ações individuais falhar e retornar um IndexDocumentsResult para inspeção. Também há uma ThrowOnAnyError opção se você se preocupa apenas com o sucesso ou a falha de todo o lote.

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 doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

APIs assíncronas

Todos os exemplos até agora têm usado APIs síncronas, mas também fornecemos suporte completo para APIs assíncronas. Geralmente, você apenas adicionará um Async sufixo ao nome do método e await a ele.

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

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

Solução de problemas

Qualquer operação do Azure.Search.Documents que falhar lançará um RequestFailedException com códigos úteisStatus. Muitos desses erros são recuperáveis.

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

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

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Próximas etapas

Participante

Consulte nosso CONTRIBUTING.md de Pesquisa para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

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. Para obter detalhes, visite cla.microsoft.com.

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