Azure Bilişsel Arama API sürümleriAPI versions in Azure Cognitive Search

Azure Bilişsel Arama, özellik güncelleştirmelerini düzenli olarak kaydeder.Azure Cognitive Search rolls out feature updates regularly. Bazen, her zaman olmasa da, geriye dönük uyumluluğu korumak için bu güncelleştirmeler API 'nin yeni bir sürümünü gerektirir.Sometimes, but not always, these updates require a new version of the API to preserve backward compatibility. Yeni bir sürümü yayımlamak, kodunuzda arama hizmeti güncelleştirmelerini ne zaman ve nasıl tümleştirmenizi denetlemenize olanak tanır.Publishing a new version allows you to control when and how you integrate search service updates in your code.

Bir kural olarak, Azure Bilişsel Arama ekibi, kodunuzu yeni bir API sürümü kullanacak şekilde yükseltmek için biraz çaba içerebileceği için, yalnızca gerektiğinde yeni sürümler yayımlar.As a rule, the Azure Cognitive Search team publishes new versions only when necessary, since it can involve some effort to upgrade your code to use a new API version. Yeni bir sürüm yalnızca API 'nin bazı yönlerinin geriye dönük uyumluluğu kesen bir şekilde değişmesi durumunda gereklidir.A new version is needed only if some aspect of the API has changed in a way that breaks backward compatibility. Bu tür değişiklikler, mevcut özelliklerle ilgili düzeltmeler veya var olan API yüzey alanını değiştiren yeni özelliklerden kaynaklanıyor olabilir.Such changes can happen because of fixes to existing features, or because of new features that change existing API surface area.

Aynı kural SDK güncelleştirmeleri için de geçerlidir.The same rule applies for SDK updates. Azure Bilişsel Arama SDK, anlam sürümü oluşturma kurallarını izler, yani sürümünün üç bölümü vardır: Ana, ikincil ve derleme numarası (örneğin, 1.1.0).The Azure Cognitive 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). SDK 'nın yeni bir ana sürümü yalnızca geriye dönük uyumluluğu kesen değişiklikler için serbest bırakılır.A new major version of the SDK is released only for changes that break backward compatibility. Önemli olmayan özellik güncelleştirmeleri ikincil sürümü artırır ve hata düzeltmeleri yalnızca derleme sürümünü artırır.Non-breaking feature updates will increment the minor version, and bug fixes will only increase the build version.

Not

Azure Bilişsel Arama hizmet örneğiniz, en son sürüm dahil olmak üzere birkaç REST API sürümü destekler.Your Azure Cognitive Search service instance supports several REST API versions, including the latest one. Artık en son bir sürüm olmadığında bir sürümü kullanmaya devam edebilirsiniz, ancak kodunuzu en yeni sürümü kullanmak için geçirmeniz önerilir.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. REST API kullanırken, API sürümü parametresi aracılığıyla her istekte API sürümünü belirtmeniz gerekir.When using the REST API, you must specify the API version in every request via the api-version parameter. .NET SDK kullanıldığında, kullanmakta olduğunuz SDK sürümü REST API ilgili sürümünü belirler.When using the .NET SDK, the version of the SDK you’re using determines the corresponding version of the REST API. Daha eski bir SDK kullanıyorsanız, hizmet daha yeni bir API sürümünü destekleyecek şekilde yükseltilse bile, bu kodu hiçbir değişiklik yapmadan çalıştırmaya devam edebilirsiniz.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.

Geçerli sürümlerin anlık görüntüsüSnapshot of current versions

Azure Bilişsel Arama tüm programlama arabirimlerinin geçerli sürümlerinin bir anlık görüntüsü aşağıda verilmiştir.Below is a snapshot of the current versions of all programming interfaces to Azure Cognitive Search.

ArabirimlerInterfaces En son ana sürümMost recent major version DurumStatus
.NET SDK.NET SDK 9.09.0 Genel kullanıma sunulan, 2019 MayısGenerally Available, released May 2019
.NET SDK önizlemesi.NET SDK Preview 8,0-Önizleme8.0-preview Önizleme, yayın 2019 NisanPreview, released April 2019
Hizmet REST API'siService REST API 2019-05-062019-05-06 Genel Kullanıma SunulduGenerally Available
Service REST API 2019-05-06-ÖnizlemeService REST API 2019-05-06-Preview 2019-05-06-Önizleme2019-05-06-Preview ÖnizlemePreview
.NET Yönetim SDK'sı.NET Management SDK 3.03.0 Genel Kullanıma SunulduGenerally Available
Yönetim REST API'siManagement REST API 2015-08-192015-08-19 Genel Kullanıma SunulduGenerally Available

REST API 'Leri için, her çağrıda api-version de dahil olmak üzere gereklidir.For the REST APIs, including the api-version on each call is required. api-version kullanmak, önizleme API 'SI gibi belirli bir sürümü hedeflemek kolaylaştırır.Using api-version makes it easy to target a specific version, such as a preview API. Aşağıdaki örnekte api-version parametresinin nasıl belirtildiği gösterilmektedir:The following example illustrates how the api-version parameter is specified:

GET https://my-demo-app.search.windows.net/indexes/hotels?api-version=2019-05-06

Not

Her isteğin bir api-versionolsa da, tüm API istekleri için aynı sürümü kullanmanızı öneririz.Although each request has an api-version, we recommend that you use the same version for all API requests. Bu, yeni API sürümleri önceki sürümler tarafından tanınmayan öznitelikler veya işlemler tanıtdığında özellikle doğrudur.This is especially true when new API versions introduce attributes or operations that are not recognized by previous versions. API sürümlerinin karışması istenmeyen sonuçlara sahip olabilir ve kaçınılmalıdır.Mixing API versions can have unintended consequences and should be avoided.

Hizmet REST API ve yönetim REST API birbirinden bağımsız olarak sürümlüdür.The Service REST API and Management REST API are versioned independently of each other. Sürüm numaralarında benzerlik varsa coarızdır.Any similarity in version numbers is coincidental.

Genel olarak kullanılabilir (veya GA) API 'Leri üretimde kullanılabilir ve Azure hizmet düzeyi sözleşmelerine tabidir.Generally available (or GA) APIs can be used in production and are subject to Azure service level agreements. Önizleme sürümleri, her zaman bir GA sürümüne geçirilmeyen deneysel özelliklere sahiptir.Preview versions have experimental features that are not always migrated to a GA version. Üretim uygulamalarında önizleme API 'Lerini kullanmaktan kaçınmak kesinlikle önerilir.You are strongly advised to avoid using preview APIs in production applications.

15 Ekim 2020 ' e kadar REST API en son sürümüne güncelleştirinUpdate to the latest version of the REST API by October 15, 2020

Azure Bilişsel Arama REST API aşağıdaki sürümleri kullanımdan kaldırılacak ve 15 Ekim 2020 itibariyle artık desteklenmeyecektir: 2014-07-31-Preview, 2014-10-20-Preview, 2015-02-28-Previewve 2015-02-28.The following versions of the Azure Cognitive Search REST API will be retired and no longer supported as of October 15, 2020: 2014-07-31-Preview, 2014-10-20-Preview, 2015-02-28-Preview, and 2015-02-28. Ayrıca, Azure Bilişsel Arama .NET SDK 'nın 3.0.0-RC ' den daha eski sürümleri de bu REST API sürümlerinden birini hedeflerse devre dışı bırakılacaktır.In addition, versions of the Azure Cognitive Search .Net SDK older than 3.0.0-rc will also be retired since they target one of these REST API versions. Bu tarihten sonra, kullanımdan kaldırılan REST API veya SDK sürümlerinden herhangi birini kullanan uygulamalar artık çalışmaz ve yükseltilmesi gerekir.After this date, applications that use any of the deprecated REST API or SDK versions will no longer work and must be upgraded. Bu türde herhangi bir değişiklik yaparken, 12 aylık bir bildirim sunuyoruz, bu nedenle ayarlamak için yeterli zaman vardır.As with any change of this type, we are giving 12 months' notice, so you have adequate time to adjust. Azure Bilişsel Arama 'yi kullanmaya devam etmek için lütfen REST API REST API hedefleyen mevcut kodu, 15 Ekim 2020 ' ye 2019-05-06 veya daha yeni bir sürümü veya .NET SDK 'sını 3,0 veya daha yeni bir sürüme geçirin.To continue using Azure Cognitive Search, please migrate existing code that targets the REST API to REST API version 2019-05-06 or newer or the .Net SDK to version 3.0 or newer by October 15, 2020. En son sürüme güncelleştirme hakkında sorularınız varsa, kodunuzu güncelleştirmek için yeterli zamana sahip olduğunuzdan emin olmak için lütfen 15 Mayıs 2020 ile azuresearch_contact@microsoft.com e-posta gönderin.If you have any questions about updating to the latest version, please send mail to azuresearch_contact@microsoft.com by May 15, 2020 to ensure you have enough time to update your code.

Önizleme ve genel kullanıma açık sürümler hakkındaAbout Preview and Generally Available versions

Azure Bilişsel Arama, önce REST API önce, sonra .NET SDK 'nin ön sürüm sürümlerini kullanarak deneysel özellikleri önceden yayınlar.Azure Cognitive Search always pre-releases experimental features through the REST API first, then through prerelease versions of the .NET SDK.

Önizleme özellikleri, test ve deneme için, özellik tasarımı ve uygulama hakkında geri bildirim toplama hedefi ile kullanılabilir.Preview features are available for testing and experimentation, with the goal of gathering feedback on feature design and implementation. Bu nedenle, Önizleme özellikleri zaman içinde değişebilir, belki de geriye doğru uyumluluğu kesen şekillerde değişiklik yapabilir.For this reason, preview features can change over time, possibly in ways that break backwards compatibility. Bu, bir GA sürümündeki özelliklerin aksine, bu durum, küçük ve geriye dönük olarak uyumlu düzeltmeler ve geliştirmeler dışında değişmez ve çok düşüktür.This is in contrast to features in a GA version, which are stable and unlikely to change with the exception of small backward-compatible fixes and enhancements. Ayrıca, Önizleme özellikleri her zaman bir GA sürümüne değildir.Also, preview features do not always make it into a GA release.

Bu nedenlerden dolayı, önizleme sürümlerine bağımlılığı alan üretim kodu yazmayı öneririz.For these reasons, we recommend against writing production code that takes a dependency on preview versions. Daha eski bir önizleme sürümü kullanıyorsanız, genel kullanıma açık (GA) sürüme geçiş yapmanızı öneririz.If you're using an older preview version, we recommend migrating to the generally available (GA) version.

.NET SDK için: .NET SDK yükseltmesırasında kod geçişi için rehberlik bulunabilir.For the .NET SDK: Guidance for code migration can be found at Upgrade the .NET SDK.

Genel kullanılabilirlik, Azure Bilişsel Arama artık hizmet düzeyi sözleşmesi (SLA) altında olduğu anlamına gelir.General availability means that Azure Cognitive Search is now under the service level agreement (SLA). SLA, Azure bilişsel arama hizmet düzeyi sözleşmeleri' nde bulunabilir.The SLA can be found at Azure Cognitive Search Service Level Agreements.