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

Artigo
10/19/2023

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

FieldBuilder (adicionado à versão 11.1)
Propriedade de serializador (adicionada à versão 11.1) para oferecer suporte à serialização personalizada

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

A propriedade EncryptionKey adicionou indexadores, fontes de dados e conjuntos de habilidades
Suporte à propriedade IndexingParameters.IndexingParametersConfiguration
Os tipos geoespaciais têm suporte nativo no FieldBuilder. SearchFilter pode codificar tipos geométricos de Microsoft.Spatial sem uma dependência de assembly explícita.

Você também pode continuar declarando explicitamente uma dependência em Microsoft.Spatial. Há exemplos dessa técnica disponíveis para System.Text.Json e Newtonsoft.Json.

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

KnowledgeStore
Adicionado suporte para os tipos Azure.Core.GeoJson em SearchDocument, SearchFilter e FieldBuilder.
Adicionado registro com base no EventSource. O nome da origem do evento é Azure-Search-Documents. O conjunto de eventos atual se concentra no ajuste dos tamanhos de lote para SearchIndexingBufferedSender.
Adicionados CustomEntityLookupSkill e DocumentExtractionSkill. Adicionado DefaultCountryHint em LanguageDetectionSkill.

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.

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.

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;

Para classes que exigem serialização JSON, substitua using Newtonsoft.Json por using System.Text.Json.Serialization.
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);
```
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.
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.
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.
Atualize referências de cliente para objetos de índice, mapa de sinônimos e analisador. As instâncias de SearchServiceClient devem mudar para SearchIndexClient.
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.
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.

Compartilhar via