Versioni API in Ricerca di AzureAPI versions in Azure Search

Il servizio Ricerca di Azure Search distribuisce regolarmente aggiornamenti delle funzionalità.Azure Search rolls out feature updates regularly. A volte, ma non sempre, questi aggiornamenti richiedono la pubblicazione di una nuova versione dell'API per mantenere la compatibilità con le versioni precedenti.Sometimes, but not always, these updates require us to publish a new version of our API to preserve backward compatibility. Questa pubblicazione consente di controllare come e quando integrare gli aggiornamenti del servizio di ricerca nel codice.Publishing a new version allows you to control when and how you integrate search service updates in your code.

Di norma, le nuove versioni vengono pubblicate solo se necessario, perché ciò può comportare alcune operazioni di aggiornamento del codice per l'utilizzo di una nuova versione dell'API.As a rule, we try to publish new versions only when necessary, since it can involve some effort to upgrade your code to use a new API version. Verrà pubblicata una nuova versione solo in caso di modifica di alcuni aspetti dell'API che interrompe la compatibilità con le versioni precedenti.We will only publish a new version if we need to change some aspect of the API in a way that breaks backward compatibility. Ciò può verificarsi in caso di correzioni alle funzionalità esistenti o di nuove funzionalità che modificano la superficie di attacco dell'API esistente.This can happen because of fixes to existing features, or because of new features that change existing API surface area.

Si applica la stessa regola per gli aggiornamenti all'SDK.We follow the same rule for SDK updates. Azure Search SDK segue le regole di versionamento semantico , ciò significa che la versione ha tre parti: principale, secondaria e numero di build (ad esempio, 1.1.0).The Azure Search SDK follows the semantic versioning rules, which means that its version has three parts: major, minor, and build number (for example, 1.1.0). Una nuova versione principale dell'SDK verrà rilasciata solo in caso di modifiche che interrompono la compatibilità con le versioni precedenti.We will release a new major version of the SDK only in case of changes that break backward compatibility. Per aggiornamenti di funzionalità senza interruzione di compatibilità verrà incrementata la versione secondaria e, in caso di correzione di bug, verrà incrementata solo la versione build.For non-breaking feature updates, we will increment the minor version, and for bug fixes we will only increase the build version.

Nota

L'istanza del servizio Ricerca di Azure supporta diverse versioni di API REST, inclusa quella più recente.Your Azure Search service instance supports several REST API versions, including the latest one. È possibile continuare a usare una versione anche se non è la più recente, ma si consiglia di migrare il codice per usare la versione più recente.You can continue to use a version when it is no longer the latest one, but we recommend that you migrate your code to use the newest version. Quando si usa l'API REST, è necessario specificare la versione dell'API in tutte le richieste tramite il parametro api-version.When using the REST API, you must specify the API version in every request via the api-version parameter. Quando si usa .NET SDK, la versione del componente SDK in uso determina la versione corrispondente dell'API REST.When using the .NET SDK, the version of the SDK you’re using determines the corresponding version of the REST API. Se si usa una versione del componente SDK precedente, è possibile continuare a eseguire il codice senza apportare modifiche, anche se il servizio viene aggiornato per supportare una versione API più recente.If you are using an older SDK, you can continue to run that code with no changes even if the service is upgraded to support a newer API version.

Panoramica delle versioni correntiSnapshot of current versions

Di seguito è illustrata una panoramica delle versioni correnti di tutte le interfacce di programmazione di Ricerca di Azure.Below is a snapshot of the current versions of all programming interfaces to Azure Search.

InterfacceInterfaces Versione principale più recenteMost recent major version StatoStatus
.NET SDK.NET SDK 3.03.0 Disponibile a livello generale, rilasciata a novembre 2016Generally Available, released November 2016
Anteprima di .NET SDK.NET SDK Preview 4.0.1-Preview4.0.1-preview Anteprima, rilasciata a maggio 2017Preview, released May 2017
API REST del servizioService REST API 2016-09-012016-09-01 Disponibile a livello generaleGenerally Available
Anteprima API REST del servizioService REST API Preview 2016-09-01-Preview2016-09-01-Preview PreviewPreview
.NET Management SDK.NET Management SDK 2015-08-192015-08-19 Disponibile a livello generaleGenerally Available
API REST di gestioneManagement REST API 2015-08-192015-08-19 Disponibile a livello generaleGenerally Available

Per le API REST, è necessario includere il parametro api-version a ogni chiamata.For the REST APIs, including the api-version on each call is required. Questo facilita l'identificazione di una versione specifica, ad esempio un'API di anteprima.This makes it easy to target a specific version, such as a preview API. L'esempio seguente illustra come viene specificato il parametro api-version :The following example illustrates how the api-version parameter is specified:

GET https://adventure-works.search.windows.net/indexes/bikes?api-version=2016-09-01

Nota

Benché ogni richiesta abbia un parametro api-version, è consigliabile usare la stessa versione per tutte le richieste API.Although each request has an api-version, we recommend that you use the same version for all API requests. Ciò vale soprattutto nel caso in cui nuove versioni API introducano attributi oppure operazioni non riconosciuti dalle versioni precedenti.This is especially true when new API versions introduce attributes or operations that are not recognized by previous versions. La combinazione di diverse versioni API può avere conseguenze impreviste e deve essere evitata.Mixing API versions can have unintended consequences and should be avoided.

L'API REST del servizio e l'API REST di gestione sono sottoposte al controllo delle versioni in modo indipendente tra loro.The Service REST API and Management REST API are versioned independently of each other. L'eventuale somiglianza del numero di versione è causale.Any similarity in version numbers is coincidental.

Le API disponibili a livello generale (o GA) possono essere utilizzate nell'ambiente di produzione e sono soggette a contratti di servizio di Azure.Generally available (or GA) APIs can be used in production and are subject to Azure service level agreements. Le versioni di anteprima offrono funzionalità sperimentali che non sempre vengono migrate a una versione GA.Preview versions have experimental features that are not always migrated to a GA version. È consigliabile evitare l'utilizzo delle API di anteprima in applicazioni di produzione.We strongly advise against using preview APIs in production applications.

Informazioni sull'anteprima e sulle versioni disponibili a livello generaleAbout Preview and Generally Available versions

Ricerca di Azure rilascia sempre in via preliminare funzionalità sperimentali tramite l'API REST, quindi tramite versioni non definitive di .NET SDK.Azure Search always pre-releases experimental features through the REST API first, then through prerelease versions of the .NET SDK.

La migrazione alla versione GA delle funzionalità di anteprima non è garantita.Preview features are not guaranteed to be migrated to a GA release. Mentre le funzionalità in una versione GA vengono considerate stabili e difficilmente modificabili, ad eccezione di piccoli miglioramenti e correzioni compatibili con le versioni precedenti, le funzionalità di anteprima sono disponibili per il testing e la sperimentazione, allo scopo di raccogliere commenti e suggerimenti sulla relativa progettazione e implementazione.Whereas features in a GA version are considered stable and unlikely to change with the exception of small backward-compatible fixes and enhancements, preview features are available for testing and experimentation, with the goal of gathering feedback on feature design and implementation.

Tuttavia, poiché le funzionalità di anteprima sono soggette a modifiche, è consigliabile evitare di scrivere codice di produzione dipendente dalle versioni di anteprima.However, because preview features are subject to change, we recommend against writing production code that takes a dependency on preview versions. Se si utilizza una versione di anteprima precedente, è consigliabile eseguire la migrazione alla versione disponibile a livello generale (GA).If you are using an older preview version, we recommend migrating to the generally available (GA) version.

Per .NET SDK: le linee guida per la migrazione del codice sono disponibili nell'articolo sull' aggiornamento di .NET SDK.For the .NET SDK: Guidance for code migration can be found at Upgrade the .NET SDK.

Con disponibilità a livello generale si intende che Ricerca di Azure è ora soggetta al contratto di servizio (SLA).General availability means that Azure Search is now under the service level agreement (SLA). Il contratto di servizio è reperibile in Contratto di Servizio per Ricerca.The SLA can be found at Azure Search Service Level Agreements.