Eseguire l'aggiornamento a .NET SDK di Ricerca intelligenza artificiale di Azure versione 11

Se la soluzione di ricerca è basata su Azure SDK per .NET, questo articolo consente di eseguire la migrazione del codice dalle versioni precedenti di Microsoft.Azure.Search alla versione 11, la nuova libreria client Azure.Search.Documents. La versione 11 è una libreria client completamente riprogettata, rilasciata dal team di sviluppo di Azure SDK (le versioni precedenti sono state prodotte dal team di sviluppo di Ricerca intelligenza artificiale di Azure).

Tutte le funzionalità della versione 10 vengono implementate nella versione 11. Le differenze principali includono:

• Un pacchetto (Azure.Search.Documents) anziché quattro
• Tre client invece di due: SearchClient, SearchIndexClient, SearchIndexerClient
• Differenze di denominazione in un'ampia gamma di API e piccole differenze strutturali che semplificano alcune attività

Il log delle modifiche della libreria client include un elenco di aggiornamenti con elementi. È possibile esaminare una versione riepilogata in questo articolo.

Tutti gli esempi di codice e i frammenti di codice C# nella documentazione del prodotto Ricerca intelligenza artificiale di Azure sono stati rivisti per usare 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. Aggiornamenti alle librerie deprecate sono limitate solo alle correzioni di bug ad alta priorità.

• Coerenza con altre librerie client di Azure. Azure.Search.Documents assume una dipendenza da Azure.Core e System.Text.Json e segue approcci convenzionali per 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 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 di 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 siano disponibili 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 client

Se applicabile, la tabella seguente esegue il mapping delle librerie client tra le 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
Destinazioni oggetti correlati all'indice (indici, analizzatori, mappe sinonimiche)	SearchServiceClient	SearchIndexClient
Destinazioni 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 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 Passaggi per l'aggiornamento , è consigliabile attenuare eventuali problemi di sostituzione delle stringhe.

Denominazione e altre differenze dell'API

Oltre alle differenze client (annotate in precedenza e quindi omesse qui), sono state rinominate più API e in alcuni casi riprogettate. Le differenze tra i nomi delle classi sono riepilogate nelle sezioni seguenti. Questo elenco non è esaustivo, ma raggruppa le modifiche api per attività, che può essere utile per le revisioni in blocchi di codice specifici. Per un elenco di aggiornamenti delle API con elementi, vedere il log delle modifiche per Azure.Search.Documents in GitHub.

Autenticazione e crittografia

Versione 10	Versione 11 equivalente
SearchCredentials	AzureKeyCredential
EncryptionKey (informazioni di riferimento sulle API non documentate. Il supporto per questa API è passato a 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, AnalyzerName a LexicalAnalyzerName)
AnalyzeRequest	AnalyzeTextOptions
StandardAnalyzer	LuceneStandardAnalyzer
StandardTokenizer	LuceneStandardTokenizer (anche a StandardTokenizerV2LuceneStandardTokenizerV2)
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 di campo.

Indicizzatori, origini dati, set di competenze

Versione 10	Versione 11 equivalente
Indicizzatore	SearchIndexer
Origine dati	SearchIndexerDataSource Connessione ion
Abilità	SearchIndexerSkill
Set di competenze	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ù.
DocumentSuggestResult	SuggestResults
SearchParameters	SearchOptions
SuggestParameters	SuggestOptions
SearchParameters.Filter	SearchFilter (nuova classe per la costruzione di espressioni di filtro OData)

Serializzazione JSON

Per impostazione predefinita, Azure SDK 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 un jsonNamingPolicy fornito in JsonSerializerOptions. L'esempio di codice System.Text.Json seguente, tratto dal readme Microsoft.Azure.Core.Spatial, illustra l'uso di camelCase senza dover attribuire 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 JsonSerializer Impostazioni. 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 Ricerca intelligenza artificiale di Azure è destinata a una versione corrispondente dell'API REST. L'API REST è considerata fondamentale per il servizio, con singoli SDK per il wrapping di una versione dell'API REST. Gli sviluppatori .NET possono essere utili per esaminare la documentazione più dettagliata dell'API REST per una copertura più approfondita di oggetti o operazioni specifici. 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 degli indici
• Creazione e gestione di mappe sinonimi
• Creazione e gestione dell'indicizzatore
• Creazione e gestione dell'origine dati dell'indicizzatore
• Creazione e gestione del set di competenze
• Tutti i tipi di query e la sintassi

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 di 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 da Microsoft.Spatial senza una dipendenza di assembly esplicita.

  È anche possibile continuare a dichiarare in modo esplicito una dipendenza da Microsoft.Spatial. 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 per usare il pacchetto Azure.Search.Documents. È consigliabile esaminare 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 Ricerca intelligenza artificiale di Azure potrebbero voler esaminare 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.

1. 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.

2. 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;
   

3. Per le classi che richiedono la serializzazione JSON, sostituire using Newtonsoft.Json con using System.Text.Json.Serialization.

4. Rivedere il codice di autenticazione client. Nelle versioni precedenti si userebbero 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, ServiceNamee IndexName (se 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);
   

5. 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.

6. Rivedere raccolte ed elenchi. Nel nuovo SDK tutti gli elenchi sono di sola lettura per evitare problemi 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.

7. 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 al passaggio successivo.

8. Aggiornare i riferimenti client per gli oggetti index, synonym map e analyzer. Le istanze di SearchServiceClient devono essere modificate in SearchIndexClient.

9. 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 è anche possibile esaminare 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 modo da poter migliorare la documentazione o analizzare il problema.

10. Ricompila la soluzione. Dopo aver risolto eventuali errori di compilazione o avvisi, è possibile apportare modifiche aggiuntive all'applicazione per sfruttare le nuove funzionalità.

Modifiche di rilievo

Dato che 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 le versioni precedenti 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, in cui le modifiche al codice nella versione 11 sono correlate alle funzionalità esistenti (e non solo a un refactoring delle API), sono disponibili le modifiche di comportamento seguenti:

• L'algoritmo di classificazione BM25 sostituisce l'algoritmo di classificazione precedente con una 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 l'ultimo 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.

Passaggi successivi

• Come usare Azure.Search.Documents in un'applicazione .NET C#
• Esercitazione: Aggiungere la ricerca alle app Web
• Pacchetto Azure.Search.Documents
• Esempi in GitHub
• Informazioni di riferimento sulle API Azure.Search.Document