Compartilhar via

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

  • Artigo

Se sua solução de pesquisa é criada no SDK do Azure para .NET, este artigo ajuda ao migrar o código de versões anteriores do Microsoft.Azure.Search para a versão 11, a nova biblioteca de clientes Azure.Search.Documents. A versão 11 é uma biblioteca de clientes totalmente recriada, lançada pela equipe de desenvolvimento de SDK do Azure (as versões anteriores foram produzidas pela equipe de desenvolvimento da IA do Azure 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 e SearchIndexerClient
  • Diferenças de nomenclatura em várias APIs e pequenas diferenças estruturais que simplificam algumas tarefas

O log de alterações da biblioteca de clientes tem uma lista discriminada de atualizações. Você pode examinar uma versão resumida neste artigo.

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

Por que atualizar?

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

  • Novos recursos são adicionados apenas na Azure.Search.Documents. Agora, a versão anterior, Microsoft.Azure.Search, é um cliente herdado. As atualizações para bibliotecas herdadas são limitadas apenas a correções de bugs de alta prioridade.

  • Consistência com outras bibliotecas de clientes do Azure. Azure.Search.Documents assume uma dependência em Azure.Core e em System.Text.Json e segue abordagens convencionais para tarefas comuns, como conexões de cliente autorização.

O Microsoft.Azure.Search foi desativado oficialmente. Se você estiver usando uma versão antiga, é recomendável atualizar para a próxima versão superior, repetindo o processo sucessivamente até chegar à versão 11 e ao Azure.Search.Documents. Uma estratégia de atualização incremental facilita a localização e a correção de problemas de bloqueio. Confira Documentos de versão anteriores para obter as diretrizes.

Comparação de pacotes

A versão 11 consolida e simplifica o gerenciamento de pacotes para que haja uma quantidade menor deles para gerenciar.

Versão 10 e versões anteriores Versão 11
Microsoft.Azure.Search
Microsoft.Azure.Search.Service
Microsoft.Azure.Search.Data
Microsoft.Azure.Search.Common		 Pacote do Azure.Search.Documents

Comparação de cliente

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)
Aborda as coleções de documentos de um índice (consultas e importação de dados) SearchIndexClient SearchClient
Aborda os objetos relacionados ao índice (índices, analisadores, mapas de sinônimos) SearchServiceClient SearchIndexClient
Aborda os objetos relacionados ao indexador (indexadores, fontes de dados, conjuntos de habilidades) SearchServiceClient SearchIndexerClient (novo)

Cuidado

Observe que o SearchIndexClient existe em ambas as versões, mas aborda operações diferentes. Na versão 10, o SearchIndexClient cria índices e outros objetos. Na versão 11, ele funciona com índices existentes a fim de abordar a coleção de documentos com APIs de consulta e ingestão de dados. Para evitar confusão ao atualizar o código, tenha em mente a ordem na qual as referências do cliente são atualizadas. Seguir a sequência em Etapas para atualizar deve ajudar a reduzir os problemas de substituição de cadeia de caracteres.

Nomenclatura e outras diferenças de API

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

Autenticação e criptografia

Versão 10 Equivalente à versão 11
SearchCredentials AzureKeyCredential
EncryptionKey (não documentado na referência da API. O suporte para esta API mudou para disponibilidade geral no v10, mas só estava disponível no SDK de pré-visualização) SearchResourceEncryptionKey

Índices, analisadores, mapas de sinônimos

Versão 10 Equivalente à versão 11
Index SearchIndex
Campo SearchField
DataType SearchFieldDataType
ItemError SearchIndexerError
Analisador LexicalAnalyzer (também AnalyzerName para LexicalAnalyzerName)
AnalyzeRequest AnalyzeTextOptions
StandardAnalyzer LuceneStandardAnalyzer
StandardTokenizer LuceneStandardTokenizer (também StandardTokenizerV2 para LuceneStandardTokenizerV2)
TokenInfo AnalyzedTokenInfo
Tokenizer LexicalTokenizer (também TokenizerName para LexicalTokenizerName )
SynonymMap.Format Nenhum. Remover referências a Format.

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

Indexadores, fontes de dados, conjuntos de habilidades

Versão 10 Equivalente à versão 11
Indexador SearchIndexer
DataSource SearchIndexerDataSourceConnection
Skill SearchIndexerSkill
Skillset SearchIndexerSkillset
DataSourceType SearchIndexerDataSourceType

Importação de dados

Versão 10 Equivalente à versão 11
IndexAction IndexDocumentsAction
IndexBatch IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry() SearchIndexingBufferedSender

Solicitações e respostas de consultas

Versão 10 Equivalente à versão 11
DocumentsOperationsExtensions.SearchAsync SearchClient.SearchAsync
DocumentSearchResult SearchResult ou SearchResults, dependendo de o resultado ser um único documento ou vários.
DocumentSuggestResult SuggestResults
SearchParameters SearchOptions
SuggestParameters SuggestOptions
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, contando com os recursos dessas APIs para manipular transformações de texto anteriormente implementadas por meio de uma classe nativa SerializePropertyNamesAsCamelCaseAttribute, sem uma contraparte na nova biblioteca.

Para serializar nomes de propriedades no formato minúsculasMaiúsculas, você pode usar o JsonPropertyNameAttribute (semelhante a este exemplo).

Como alternativa, você pode definir uma JsonNamingPolicy fornecida em JsonSerializerOptions. O exemplo de código System.Text.Json a seguir, extraído do Leiame do Microsoft.Azure.Core.Spatial, demonstra o uso do formato minúsculasMaiúsculas sem precisar definir atributos para 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.Jsem para serialização JSON, pode transmitir políticas de nomenclatura globais usando atributos semelhantes ou propriedades em JsonSerializerSettings. Para obter um exemplo equivalente ao anterior, consulte o Exemplo de desserialização de documentos no arquivo leiame do Newtonsoft.Jsno.

Sobre a v11

Cada versão de uma biblioteca de clientes do IA do Azure Search destina-se a uma versão correspondente da API REST. A API REST é considerada fundamental para o serviço, com SDKs individuais que encapsulam uma versão da API REST. Como desenvolvedor do .NET, pode ser útil consultar a documentação da API REST mais detalhada para uma abordagem mais profunda de objetos ou operações específicas. A versão 11 destina-se à especificação do serviço de pesquisa 2020-06-30.

A versão 11.0 oferece suporte total aos seguintes objetos e operações:

  • Criação e gerenciamento de índices
  • Criação e gerenciamento de mapas de sinônimos
  • Criação e gerenciamento de indexador
  • Criação e gerenciamento da fonte de dados de indexador
  • Criação e gerenciamento de conjunto de habilidades
  • Todos os tipos de consulta e sintaxe

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

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, consulte

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

  • Como usar o Azure.Search.Documents introduz as APIs mais usadas. Até mesmo usuários experientes da IA do Azure Search podem querer revisar essa introdução à nova biblioteca como um antecessor para a migração.

Etapas da atualização

As etapas a seguir ajudarão a começar a usar uma migração de código descrevendo o primeiro conjunto de tarefas necessárias, especialmente em relação a referências do cliente.

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

  2. Substitua usando diretivas para Microsoft.Azure.Search pelo seguinte usando instruções:

    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 de cliente para definir a chave de API (por exemplo, a propriedade SearchServiceClient.Credentials ). Na versão atual, use a classe AzureKeyCredential para transmitir a chave como credencial, para que, se preciso, você possa atualizar a chave de API sem criar novos objetos de cliente.

    As propriedades do cliente foram simplificadas para apenas Endpoint, ServiceName e IndexName (quando apropriado). O exemplo a seguir usa a classe Uri do sistema para fornecer o ponto de extremidade e a classe de Ambiente 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 de 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 do tipo somente leitura, para evitar problemas de downstream se a lista precisar conter valores nulos. A alteração do código é para adicionar itens a uma lista. Por exemplo, em vez de atribuir cadeias de caracteres a uma propriedade de Seleção, você as adicionaria desta forma:

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

    Selecionar, Facetas, SearchFields, SourceFields, ScoringParameters e OrderBy são listas que agora precisam ser reconstruídas.

  7. Atualize as referências de cliente para consultas e importação de dados. As instâncias de SearchIndexClient devem mudar para SearchClient. Para evitar a confusão de nomes, verifique se você capturou todas as instâncias antes de passar à próxima etapa.

  8. Atualize referências de cliente para objetos de índice, mapa de sinônimos e analisador. As instâncias de SearchServiceClient devem mudar para SearchIndexClient.

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

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

  10. Recrie a solução. Após corrigir todos os avisos ou erros de build, você poderá fazer alterações adicionais no aplicativo, para aproveitar a novas funcionalidade.

Alterações de quebra

Considerando as alterações de varredura 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 uma análise completa das diferenças, consulte o log de alterações para Azure.Search.Documents.

Em termos de atualizações de versão de serviço, nas quais as alterações de código na versão 11 relacionam-se à funcionalidade existente (e não apenas a uma refatoração de APIs), você observará as seguintes alterações de comportamento:

  • O algoritmo de classificação BM25 substitui o anterior por uma tecnologia mais nova. Serviços novos usam esse algoritmo automaticamente. Para os serviços existentes, defina os 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 asc e por último se a classificação for desc. Se você tiver escrito código para manipular a forma como valores nulos são classificados, deve verificar e, possivelmente, removê-lo, se ele não for mais necessário.

Devido a essas alterações de comportamento, pode ser que existam pequenas variações nos resultados classificados.

Próximas etapas