Eseguire l'aggiornamento all’SDK .NET di Azure AI Search versione 11

Articolo
12/10/2024

Se la soluzione di ricerca è basata sull’SDK Azure per .NET, questo articolo rappresenta una guida per migrazione del codice dalle versioni precedenti di Microsoft.Azure.Searchalla versione 11, la nuova libreria client Azure.Search.Documents. La versione 11 è una libreria client completamente riprogettata, rilasciata dal team di sviluppo di SDK di Azure (le versioni precedenti sono state prodotte dal team di sviluppo di Azure AI Search).

Tutte le funzionalità della versione 10 sono implementate nella versione 11. Tra le principali differenze ci sono:

Un pacchetto (Azure.Search.Documents) anziché quattro
Tre client invece di due: SearchClient, SearchIndexClient, SearchIndexerClient
Differenze di denominazione su una vasta serie di API e piccole differenze strutturali che semplificano alcune attività

Il log delle modifiche della libreria client include un elenco dettagliato degli aggiornamenti. È possibile esaminare una versione riassuntiva in questo articolo.

Tutti gli esempi di codice e i frammenti di codice C# nella documentazione di prodotto Azure AI Search sono stati rivisti in modo che usino la nuova libreria client Azure.Search.Documents.

Ragioni dell'aggiornamento

I vantaggi dell'aggiornamento sono riepilogati nel modo seguente:

Le nuove funzionalità vengono aggiunte solo ad Azure.Search.Documents. La versione precedente, Microsoft.Azure.Search, è ora ritirata. Gli aggiornamenti alle librerie deprecate sono limitati alle sole correzioni di bug ad alta priorità.
Coerenza con altre librerie client di Azure. Azure.Search.Documents ha una dipendenza da Azure.Core e System.Text.Json e segue approcci convenzionali per le attività comuni, ad esempio connessioni client e autorizzazione.

Microsoft.Azure.Search è ufficialmente ritirato. Se si usa una versione precedente, è consigliabile eseguire l'aggiornamento alla versione successiva, ripetendo il processo in successione fino a raggiungere la versione 11 e Azure.Search.Documents. Una strategia di aggiornamento incrementale semplifica l'individuazione e la risoluzione dei problemi che causano il blocco. Per indicazioni, vedere la documentazione sulla versione precedente.

Confronto dei pacchetti

La versione 11 consolida e semplifica la gestione dei pacchetti in modo che ce ne siano meno da gestire.

Versione 10 e precedenti	Versione 11
Microsoft.Azure.Search Microsoft.Azure.Search.Service Microsoft.Azure.Search.Data Microsoft.Azure.Search.Common	Pacchetto Azure.Search.Documents

Confronto tra i client

Dove applicabile, la tabella seguente mappa le librerie client delle due versioni.

Operazioni client	Microsoft.Azure.Search (v10)	Azure.Search.Documents (v11)
È destinata alla raccolta di documenti di un indice (query e importazione di dati)	SearchIndexClient	SearchClient
È destinata a oggetti correlati all'indice (indici, analizzatori, mappe sinonimiche)	SearchServiceClient	SearchIndexClient
È destinata a oggetti correlati all'indicizzatore (indicizzatori, origini dati, set di competenze)	SearchServiceClient	SearchIndexerClient (nuovo)

Attenzione

Si noti che SearchIndexClient esiste in entrambe le versioni, ma è destinato a operazioni diverse. Nella versione 10 SearchIndexClient crea indici e altri oggetti. Nella versione 11 SearchIndexClient funziona con gli indici esistenti, destinati alla raccolta di documenti con API di query e inserimento dati. Per evitare confusione durante l'aggiornamento del codice, tenere presente l'ordine in cui i riferimenti client vengono aggiornati. Seguendo la sequenza descritta in Procedura di aggiornamento, è consigliabile attenuare eventuali problemi di sostituzione delle stringhe.

Denominazione e altre differenze relative all’API

Oltre alle differenze client (riportate in precedenza e perciò qui omesse), alcune altre API sono state rinominate in alcuni casi riprogettate. Le differenze nel nome della classe sono riepilogate nelle sezioni seguenti. Questo elenco non è esaustivo, ma raggruppa le modifiche API per attività, il che può essere utile per le revisioni su blocchi di codice specifici. Per un elenco dettagliato degli aggiornamenti delle API, vedere il log delle modifiche di Azure.Search.Documents in GitHub.

Autenticazione e crittografia

Versione 10	Versione 11 equivalente
SearchCredentials	AzureKeyCredential
EncryptionKey (informazioni di riferimento API non documentate. Il supporto per questa API è diventato disponibile a livello generale nella versione 10, ma era disponibile solo nell'SDK di anteprima)	SearchResourceEncryptionKey

Indici, analizzatori, mappe sinonimiche

Versione 10	Versione 11 equivalente
Indice	SearchIndex
Campo	SearchField
DataType	SearchFieldDataType
ItemError	SearchIndexerError
Analizzatore	LexicalAnalyzer (anche da `AnalyzerName` a `LexicalAnalyzerName`)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (anche da `StandardTokenizerV2` a `LuceneStandardTokenizerV2`)
TokenInfo	AnalyzedTokenInfo
Tokenizer	LexicalTokenizer (anche da `TokenizerName` a `LexicalTokenizerName`)
SynonymMap.Format	Nessuno. Rimuovere i riferimenti a `Format`.

Le definizioni dei campi sono semplificate: SearchableField, SimpleField, ComplexField sono nuove API per la creazione di definizioni dei campi.

Indicizzatori, origini dati, set di competenze

Versione 10	Versione 11 equivalente
Indicizzatore	SearchIndexer
Origine dati	SearchIndexerDataSourceConnection
Skill	SearchIndexerSkill
Skillset	SearchIndexerSkillset
DataSourceType	SearchIndexerDataSourceType

Importazione dei dati

Versione 10	Versione 11 equivalente
IndexAction	IndexDocumentsAction
IndexBatch	IndexDocumentsBatch
IndexBatchException.FindFailedActionsToRetry()	SearchIndexingBufferedSender

Richieste di query e risposte

Versione 10	Versione 11 equivalente
DocumentsOperationsExtensions.SearchAsync	SearchClient.SearchAsync
DocumentSearchResult	SearchResult o SearchResults, a seconda che il risultato sia un singolo documento o più documenti.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (nuova classe per la costruzione di espressioni di filtro OData)

Serializzazione JSON

Per impostazione predefinita, l’SDK Azure usa System.Text.Json per la serializzazione JSON, basandosi sulle funzionalità di tali API per gestire le trasformazioni di testo implementate in precedenza tramite una classe SerializePropertyNamesAsCamelCaseAttribute nativa, che non ha alcuna controparte nella nuova libreria.

Per serializzare i nomi delle proprietà in camelCase, è possibile usare JsonPropertyNameAttribute (simile a questo esempio).

In alternativa, è possibile impostare una jsonNamingPolicy fornita in JsonSerializerOptions. L'esempio di codice System.Text.Json seguente, tratto dal readme Microsoft.Azure.Core.Spatial, illustra l'uso di camelCase senza dover fornire un attributo per ogni proprietà:

// 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 si usa Newtonsoft.Json per la serializzazione JSON, è possibile passare criteri di denominazione globali usando attributi simili o usando le proprietà in JsonSerializerSettings. Per un esempio equivalente a quello precedente, vedere l'esempio relativo alla deserializzazione dei documenti nel file readme Newtonsoft.Json.

All'interno della versione 11

Ogni versione di una libreria client di Azure AI Search è destinata a una versione corrispondente dell'API REST. L'API REST è considerata fondamentale per il servizio, e i singoli SDK racchiudono una versione dell'API REST. Per gli sviluppatori .NET può essere utile consultare la più dettagliata documentazione sull'API REST per avere una conoscenza più approfondita di oggetti o operazioni specifiche. La versione 11 è destinata alla specifica del servizio di ricerca 2020-06-30.

La versione 11.0 supporta completamente gli oggetti e le operazioni seguenti:

Creazione e gestione di indici
Creazione e gestione di mappe sinonimiche
Creazione e gestione di indicizzatori
Creazione e gestione dell’origine dati dell'indicizzatore
Creazione e gestione di set di competenze
Tutti i tipi e le sintassi di query

Aggiunte della versione 11.1 (dettagli del log delle modifiche):

FieldBuilder (aggiunto nella versione 11.1)
Proprietà serializzatore (aggiunta nella versione 11.1) per supportare la serializzazione personalizzata

Aggiunte della versione 11.2 (dettagli del log delle modifiche):

Proprietà EncryptionKey aggiunta a indicizzatori, origini dati e set di competenze
Supporto della proprietà IndexingParameters.IndexingParametersConfiguration
I tipi geospaziali sono supportati in modo nativo in FieldBuilder. SearchFilter può codificare tipi geometrici di Microsoft.Spatial senza una dipendenza di assembly esplicita.

È inoltre possibile continuare a dichiarare in modo esplicito una dipendenza da Microsoft.Spatial. Alcuni esempi di questa tecnica sono disponibili per System.Text.Json e Newtonsoft.Json.

Aggiunte della versione 11.3 (dettagli del log delle modifiche):

KnowledgeStore
Aggiunta del supporto per i tipi Azure.Core.GeoJson in SearchDocument, SearchFilter e FieldBuilder.
Aggiunta della registrazione basata su EventSource. Il nome dell'origine evento è Azure-Search-Documents. Il set corrente di eventi è incentrato sull'ottimizzazione delle dimensioni batch per SearchIndexingBufferedSender.
Aggiunta di CustomEntityLookupSkill e DocumentExtractionSkill. Aggiunta di DefaultCountryHint in LanguageDetectionSkill.

Prima dell'aggiornamento

Le guide introduttive, le esercitazioni e gli esempi C# sono stati aggiornati in modo che usino il pacchetto Azure.Search.Documents. È consigliabile consultare gli esempi e le procedure dettagliate per informazioni sulle nuove API prima di intraprendere un esercizio di migrazione.
Come usare Azure.Search.Documents introduce le API usate più di frequente. Anche gli utenti esperti di Azure AI Search possono consultare questa introduzione alla nuova libreria come precursore della migrazione.

Passaggi per eseguire l'aggiornamento

I passaggi seguenti consentono di iniziare a eseguire una migrazione del codice seguendo il primo set di attività necessarie, in particolare per quanto riguarda i riferimenti client.

Installare il pacchetto Azure.Search.Documents facendo clic con il pulsante destro del mouse sui riferimenti al progetto e scegliendo "Gestisci pacchetti NuGet..." in Visual Studio.

Sostituire le direttive using per Microsoft.Azure.Search con le istruzioni using seguenti:

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

Per le classi che richiedono la serializzazione JSON, sostituire using Newtonsoft.Json con using System.Text.Json.Serialization.
Rivedere il codice di autenticazione client. Nelle versioni precedenti si sarebbero usate proprietà nell'oggetto client per impostare la chiave API, ad esempio la proprietà SearchServiceClient.Credentials. Nella versione corrente usare la classe AzureKeyCredential per passare la chiave come credenziale, in modo che, se necessario, sia possibile aggiornare la chiave API senza creare nuovi oggetti client.

Le proprietà client sono state semplificate solo per Endpoint, ServiceName e IndexName (ove appropriato). Nell'esempio seguente viene usata la classe Uri di sistema per fornire l'endpoint e la classe Environment da leggere nel valore della chiave:
```
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
AzureKeyCredential credential = new AzureKeyCredential(
   Environment.GetEnvironmentVariable("SEARCH_API_KEY"));
SearchIndexClient indexClient = new SearchIndexClient(endpoint, credential);
```
Aggiungere nuovi riferimenti client per gli oggetti correlati all'indicizzatore. Se si usano indicizzatori, origini dati o set di competenze, modificare i riferimenti client a SearchIndexerClient. Questo client è nuovo nella versione 11 e non ha precedenti.
Rivedere raccolte ed elenchi. Nel nuovo SDK tutti gli elenchi sono di sola lettura per evitare problemi di downstream se l'elenco contiene valori Null. La modifica del codice consiste nell'aggiungere elementi a un elenco. Ad esempio, anziché assegnare stringhe a una proprietà Select, è necessario aggiungerle come segue:
```
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 sono tutti gli elenchi che devono essere ricostruiti.
Aggiornare i riferimenti client per le query e l'importazione dei dati. Le istanze di SearchIndexClient devono essere modificate in SearchClient. Per evitare confusione nei nomi, assicurarsi di intercettare tutte le istanze prima di procedere con il passaggio successivo.
Aggiornare i riferimenti client per gli oggetti indice, mappa sinonimica e analizzatore. Le istanze di SearchServiceClient devono essere modificate in SearchIndexClient.
Per il resto del codice, aggiornare classi, metodi e proprietà per usare le API della nuova libreria. La sezione differenze di denominazione è un punto di partenza, ma è possibile esaminare anche il log delle modifiche.

Se si verificano problemi durante la ricerca di API equivalenti, è consigliabile registrare un problema in https://github.com/MicrosoftDocs/azure-docs/issues in modo da poter migliorare la documentazione o analizzare il problema.
Ricompila la soluzione. Dopo avere corretto eventuali errori o avvisi di compilazione, è possibile apportare modifiche aggiuntive all'applicazione per sfruttare la nuova funzionalità.

Modifiche di rilievo

Date le modifiche apportate alle librerie e alle API, un aggiornamento alla versione 11 non è semplice e costituisce una modifica che causa un'interruzione nel senso che il codice non sarà più compatibile con la versione 10 e precedenti. Per una revisione approfondita delle differenze, vedere il log delle modifiche per Azure.Search.Documents.

In termini di aggiornamenti delle versioni del servizio, per i quali le modifiche al codice nella versione 11 sono correlate alle funzionalità esistenti (e non solo a un refactoring delle API), si riscontrano le modifiche di comportamento seguenti:

L'algoritmo di classificazione BM25 sostituisce l'algoritmo di classificazione precedente con la tecnologia più recente. I nuovi servizi usano automaticamente questo algoritmo. Per i servizi esistenti, è necessario impostare i parametri per l'uso del nuovo algoritmo.
I risultati ordinati per i valori Null sono stati modificati in questa versione, con valori Null visualizzati per primi se l'ordinamento è asc e per ultimi se l'ordinamento è desc. Se è stato scritto codice per gestire la modalità di ordinamento dei valori Null, è consigliabile esaminare e potenzialmente rimuovere tale codice se non è più necessario.

A causa di queste modifiche di comportamento, è probabile che vi siano lievi variazioni nei risultati classificati.

Condividi tramite