Atualizar para o SDK do Azure AI Search .NET versão 11

  • Artigo

Se sua solução de pesquisa for criada no SDK do Azure para .NET, este artigo ajudará você a migrar seu código de versões anteriores do Microsoft.Azure.Search para a versão 11, a nova biblioteca de cliente Azure.Search.Documents. A versão 11 é uma biblioteca de cliente totalmente redesenhada, lançada pela equipe de desenvolvimento do SDK do Azure (as versões anteriores foram produzidas pela equipe de desenvolvimento do Azure AI Search).

Todos os recursos da versão 10 são implementados na versão 11. As principais diferenças incluem:

  • Um pacote (Azure.Search.Documents) em vez de quatro
  • Três clientes em vez de dois: SearchClient, SearchIndexClient, SearchIndexerClient
  • Nomeando diferenças em uma variedade de APIs e pequenas diferenças estruturais que simplificam algumas tarefas

O Log de Alterações da biblioteca do cliente tem uma lista detalhada de atualizações. Você pode revisar uma versão resumida neste artigo.

Todos os exemplos de código C# e trechos na documentação do produto Azure AI Search foram revisados para usar a nova biblioteca de cliente Azure.Search.Documents .

Porquê atualizar?

Os benefícios da atualização são resumidos da seguinte forma:

Microsoft.Azure.Search foi oficialmente desativado. Se você estiver usando uma versão antiga, recomendamos atualizar para a próxima versão superior, repetindo o processo sucessivamente até chegar à versão 11 e Azure.Search.Documents. Uma estratégia de atualização incremental torna mais fácil encontrar e corrigir problemas de bloqueio. Consulte Documentos da versão anterior para obter orientações.

Comparação de pacotes

A versão 11 consolida e simplifica o gerenciamento de pacotes para que haja menos para gerenciar.

Versão 10 e anterior Versão 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common

 Pacote Azure.Search.Documents

Comparação de clientes

Quando aplicável, a tabela a seguir mapeia as bibliotecas de cliente entre as duas versões.

Operações do cliente Microsoft.Azure.Search (v10) Azure.Search.Documents (v11)
Destina-se à coleção de documentos de um índice (consultas e importação de dados) SearchIndexClient SearchClient
Destina-se a objetos relacionados a índices (índices, analisadores, mapas de sinônimos) SearchServiceClient SearchIndexClient
Destina-se a objetos relacionados ao indexador (indexadores, fontes de dados, conjuntos de habilidades) SearchServiceClient SearchIndexerClient (novo)

Atenção

Observe que SearchIndexClient existe em ambas as versões, mas tem como alvo operações diferentes. Na versão 10, SearchIndexClient cria índices e outros objetos. Na versão 11, o SearchIndexClient trabalha com índices existentes, direcionando a coleção de documentos com APIs de consulta e ingestão de dados. Para evitar confusão ao atualizar o código, esteja atento à ordem em que as referências do cliente são atualizadas. Seguir a sequência em Etapas para atualizar deve ajudar a mitigar quaisquer problemas de substituição de cadeia de caracteres.

Diferenças de nomenclatura e outras APIs

Além das diferenças de cliente (notadas anteriormente e, portanto, omitidas aqui), várias outras APIs foram renomeadas e, em alguns casos, redesenhadas. As diferenças de nome de classe são resumidas nas seções a seguir. Esta lista não é exaustiva, mas agrupa alterações de API por tarefa, o que pode ser útil para revisões em blocos de código específicos. Para obter uma lista detalhada de atualizações de API, consulte o log de alterações no Azure.Search.Documents GitHub.

Autenticação e encriptação

Versão 10 Versão 11 equivalente
SearchCredentials AzureKeyCredential
EncryptionKey (Não documentado na referência da API. O suporte para esta API passou para geralmente disponível na v10, mas só estava disponível no SDK de visualização) SearchResourceEncryptionKey

Índices, analisadores, mapas de sinónimos

Versão 10 Versão 11 equivalente
Índice Índice de pesquisa
Campo Campo de Pesquisa
Tipo de dados SearchFieldDataType
ItemError SearchIndexerError
Analisador LexicalAnalyzer (também, AnalyzerName para LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
Analisador padrão LuceneStandardAnalyzer
Tokenizador padrão LuceneStandardTokenizer (também, StandardTokenizerV2 para LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Tokenizador LexicalTokenizer (também, TokenizerName para LexicalTokenizerName)
SinónimoMap.Format Nenhum. Remover referências a Format.

As definições de campo são simplificadas: SearchableField, SimpleField, ComplexField são novas APIs para criar definições de campo.

Indexadores, fontes de dados, conjuntos de habilidades

Versão 10 Versão 11 equivalente
Indexador Indexador de pesquisa
DataSource SearchIndexerDataSourceConnection
Competência SearchIndexerSkill
Conjunto de competências SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Importação de dados

Versão 10 Versão 11 equivalente
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Pedidos de consulta e respostas

Versão 10 Versão 11 equivalente
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult ou SearchResults, dependendo se o resultado é um único documento ou vários.
DocumentSuggestResult SugestãoResultados
Parâmetros de pesquisa Opções de pesquisa
SuggestParameters SugestãoOpções
SearchParameters.Filter SearchFilter (uma nova classe para construir expressões de filtro OData)

Serialização JSON

Por padrão, o SDK do Azure usa System.Text.Json para serialização JSON, confiando nos recursos dessas APIs para lidar com transformações de texto implementadas anteriormente por meio de uma classe nativa SerializePropertyNamesAsCamelCaseAttribute , que não tem contrapartida na nova biblioteca.

Para serializar nomes de propriedade em camelCase, você pode usar o JsonPropertyNameAttribute (semelhante a este exemplo).

Como alternativa, você pode definir um JsonNamingPolicy fornecido em JsonSerializerOptions. O exemplo de código System.Text.Json a seguir, retirado do readme Microsoft.Azure.Core.Spatial demonstra o uso de camelCase sem ter que atribuir todas as propriedades:

// Get the Azure AI Search service endpoint and read-only API key.
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(Environment.GetEnvironmentVariable("SEARCH_API_KEY"));

// Create serializer options with our converter to deserialize geographic points.
JsonSerializerOptions serializerOptions = new JsonSerializerOptions
{
    Converters =
    {
        new MicrosoftSpatialGeoJsonConverter()
    },
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

SearchClientOptions clientOptions = new SearchClientOptions
{
    Serializer = new JsonObjectSerializer(serializerOptions)
};

SearchClient client = new SearchClient(endpoint, "mountains", credential, clientOptions);
Response<SearchResults<Mountain>> results = client.Search<Mountain>("Rainier");

Se você estiver usando Newtonsoft.Json para serialização JSON, poderá passar políticas de nomenclatura global usando atributos semelhantes ou usando propriedades em JsonSerializerSettings. Para obter um exemplo equivalente ao anterior, consulte o exemplo Deserializing documents no readme Newtonsoft.Json.

Interior v11

Cada versão de uma biblioteca de cliente do Azure AI Search tem como alvo uma versão correspondente da API REST. A API REST é considerada fundamental para o serviço, com SDKs individuais encapsulando uma versão da API REST. Como desenvolvedor .NET, pode ser útil revisar a documentação mais detalhada da API REST para obter uma cobertura mais detalhada de objetos ou operações específicos. A versão 11 visa a especificação do serviço de pesquisa 2020-06-30.

A versão 11.0 suporta totalmente os seguintes objetos e operações:

  • Criação e gestão de índices
  • Criação e gestão de mapas de sinónimos
  • Criação e gestão de indexadores
  • Criação e gerenciamento de fonte de dados do indexador
  • Criação e gestão de competências
  • Todos os tipos de consulta e sintaxe

Adições da versão 11.1 (detalhes do log de alterações):

  • FieldBuilder (adicionado em 11.1)
  • Propriedade Serializer (adicionada em 11.1) para dar suporte à serialização personalizada

Adições da versão 11.2 (detalhes do log de alterações):

Adições da versão 11.3 (detalhes do log de alterações):

Antes de atualizar

  • Inícios rápidos, tutoriais e exemplos de C# foram atualizados para usar o pacote Azure.Search.Documents. Recomendamos revisar os exemplos e instruções passo a passo para saber mais sobre as novas APIs antes de iniciar um exercício de migração.

  • Como usar Azure.Search.Documents apresenta as APIs mais comumente usadas. Mesmo os utilizadores experientes do Azure AI Search podem querer rever esta introdução à nova biblioteca como um precursor da migração.

Etapas para atualizar

As etapas a seguir ajudam você a começar a migração de código percorrendo o primeiro conjunto de tarefas necessárias, especialmente em relação às referências de clientes.

  1. Instale o pacote Azure.Search.Documents clicando com o botão direito do mouse nas referências do projeto e selecionando "Gerenciar pacotes NuGet..." no Visual Studio.

  2. Substitua usando diretivas para Microsoft.Azure.Search pelas seguintes instruções using:

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

  3. Para classes que exigem serialização JSON, substitua using Newtonsoft.Json por using System.Text.Json.Serialization.

  4. Revise o código de autenticação do cliente. Em versões anteriores, você usaria propriedades no objeto cliente para definir a chave de API (por exemplo, a propriedade SearchServiceClient.Credentials ). Na versão atual, use a classe AzureKeyCredential para passar a chave como uma credencial, para que, se necessário, você possa atualizar a chave da API sem criar novos objetos de cliente.

    As propriedades do cliente foram simplificadas para apenas Endpoint, ServiceNamee IndexName (quando apropriado). O exemplo a seguir usa a classe Uri do sistema para fornecer o ponto de extremidade e a classe Environment para ler o valor da chave:

    Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);

  5. Adicione novas referências de cliente para objetos relacionados ao indexador. Se você estiver usando indexadores, fontes de dados ou conjuntos de habilidades, altere as referências do cliente para SearchIndexerClient. Este cliente é novo na versão 11 e não tem antecedentes.

  6. Revise coleções e listas. No novo SDK, todas as listas são somente leitura para evitar problemas downstream se a lista contiver valores nulos. A alteração de código é adicionar itens a uma lista. Por exemplo, em vez de atribuir cadeias de caracteres a uma propriedade Select, você as adicionaria da seguinte maneira:

    var options = new SearchOptions
 {
    SearchMode = SearchMode.All,
    IncludeTotalCount = true
 };

 // Select fields to return in results.
 options.Select.Add("HotelName");
 options.Select.Add("Description");
 options.Select.Add("Tags");
 options.Select.Add("Rooms");
 options.Select.Add("Rating");
 options.Select.Add("LastRenovationDate");

    Select, Facets, SearchFields, SourceFields, ScoringParameters e OrderBy são todas as listas que agora precisam ser reconstruídas.

  7. Atualize as referências do cliente para consultas e importação de dados. As instâncias de SearchIndexClient devem ser alteradas para SearchClient. Para evitar confusão de nomes, certifique-se de capturar todas as instâncias antes de prosseguir para a próxima etapa.

  8. Atualize as referências do cliente para objetos de índice, mapa de sinônimo e analisador. As instâncias de SearchServiceClient devem ser alteradas para SearchIndexClient.

  9. Para o restante do código, atualize classes, métodos e propriedades para usar as APIs da nova biblioteca. A seção de diferenças de nomenclatura é um lugar para começar, mas você também pode revisar o log de alterações.

    Se você tiver problemas para encontrar APIs equivalentes, sugerimos registrar um problema para https://github.com/MicrosoftDocs/azure-docs/issues que possamos melhorar a documentação ou investigar o problema.

  10. Reconstrua a solução. Depois de corrigir quaisquer erros de compilação ou avisos, você pode fazer alterações adicionais em seu aplicativo para aproveitar a nova funcionalidade.

Alterações interruptivas

Dadas as mudanças radicais em bibliotecas e APIs, uma atualização para a versão 11 não é trivial e constitui uma alteração significativa no sentido de que seu código não será mais compatível com a versão 10 e anteriores. Para obter uma revisão completa das diferenças, consulte o log de alterações do Azure.Search.Documents.

Em termos de atualizações de versão de serviço, onde as alterações de código na versão 11 estão relacionadas à funcionalidade existente (e não apenas a uma refatoração das APIs), você encontrará as seguintes alterações de comportamento:

  • O algoritmo de classificação BM25 substitui o algoritmo de classificação anterior por uma tecnologia mais recente. Os novos serviços utilizam este algoritmo automaticamente. Para serviços existentes, você deve definir parâmetros para usar o novo algoritmo.

  • Os resultados ordenados para valores nulos foram alterados nesta versão, com valores nulos aparecendo primeiro se a classificação for e por último se a classificação for ascdesc. Se você escreveu código para lidar com como os valores nulos são classificados, você deve revisar e potencialmente remover esse código se não for mais necessário.

Devido a essas mudanças de comportamento, é provável que haja pequenas variações nos resultados classificados.

Próximos passos