Azure hizmetleri, SDK'lar ve CLI araçları için sürüm oluşturma ilkesi

Makale
12/13/2023

Azure hizmetlerinin çoğu REST API'leri ile kaynaklarını program aracılığıyla denetlemenize ve yönetmenize olanak sağlar. Hizmetler, api'lerinin yeni yayımlanan sürümleriyle yeni özellikler ekleyen ve/veya davranışlarını değiştiren farklı sözleşmelerle gelişir.

Bu makalede Azure hizmeti, SDK ve CLI ekiplerinin Azure REST API'lerini sürüm oluşturmak için kullandığı ilke özetlenir. Azure ekipleri bu ilkeye uymak için her çabayı gösterse de, bazen sapmalar oluşabilir.

Hizmet sürümü oluşturma

Bir API'nin yayımlanan her sürümü, biçiminde adı YYYY-MM-DD verilen api-versionbir tarih değeriyle tanımlanır. Daha yeni sürümlerin daha sonraki tarihleri vardır.

Tüm API işlemleri, istemcilerin URL'deki sorgu dizesi parametresi aracılığıyla api-version hizmet için geçerli bir API sürümü belirtmesini gerektirir. Örneğin: https://management.azure.com/subscriptions?api-version=2020-01-01. İstemci SDK'ları ve araçları bu değeri otomatik olarak içerir api-version . Diğer konular için bu makalenin devamında yer alan İstemci SDK'ları ve hizmet sürümleri bölümüne bakın.

Genellikle, yayımlanan hizmet sürümleri daha yeni sürümler kullanıma sunulduğunda bile uzun yıllar boyunca kullanılabilir ve desteklenir. Çoğu durumda, mevcut kodda yeni bir hizmet sürümünü benimsemeniz gereken tek zaman yeni özelliklerden yararlanmaktır.

Kararlı sürümler

Yayımlanan hizmet sürümlerinin çoğu kararlı sürümlerdir. Kararlı sürümler geriye dönük olarak uyumludur, yani bir hizmetin bir sürümünü kullanan yazdığınız tüm kodlar, doğruluğu veya mevcut işlevselliği korumak için herhangi bir kod değişikliğine gerek kalmadan daha yeni bir kararlı sürümü benimseyebilir.

Hataya neden olan değişiklik sürümleri

Bir hizmetin hataya neden olan değişiklik sürümü geriye dönük olarak uyumlu değildir. Mevcut istemci kodunda hataya neden olan bir değişiklik sürümünü benimsemek, istemcinin önceki sürümü hedeflerken olduğu gibi davrandığından emin olmak için kod değişiklikleri gerektirebilir.

Hataya neden olan değişiklik sürümleri nadirdir, belgeler aracılığıyla duyurulur ve genellikle bir önizleme sürümünün yayımlanması ile önlenir. Hataya neden olan bir değişiklik sürümünün yayımlanması, mevcut kararlı sürümlerin son kullanımdan kaldırılmasını isteyebilir. Bu sürüm, hataya neden olan değişiklik sürümünün yayımlanmasından sonra en az üç yıl boyunca kullanılabilir durumda kalır. Güvenlik veya uyumluluk sorunları nedeniyle yayımlanan hataya neden olan değişiklikler için, sorunun önem derecesine bağlı olarak mevcut kararlı hizmet sürümleri bir yıl veya daha az süreyle kullanılabilir durumda kalabilir.

Yapay zekadaki hızlı yenilikler ve geliştirmeler nedeniyle yapay zeka temelli hizmetler bir yıllık minimum kullanılabilirliğe sahip olabilir. Her hizmet, hataya neden olan değişiklik ilkesini yayımlar.

Microsoft dışı bir bileşene bağımlı olan tüm Azure hizmetleri, destek ilkesini bileşenin ilkesiyle eşleşecek şekilde küçültebilir. Bu durum nedeniyle herhangi bir hataya neden olan değişiklik, bileşenin artık desteklenmediği tarihi gösteren bileşen satıcısının ilkesine bağlanır.

Önizleme sürümleri

Bazen Microsoft, önerilen değişiklikler ve yeni özellikler hakkında geri bildirim toplamak için hizmetin önizleme sürümünü yayımlar. Önizleme hizmeti sürümleri, örneğin son ekleriyle -previewapi-version2022-07-07-previewtanımlanır.

Açıkça önceki kararlı sürümden hataya neden olacak bir değişiklik yapmak istenmediği sürece, yeni önizleme sürümleri en son kararlı sürümün tüm özelliklerini içerir ve yeni önizleme özellikleri ekler. Ancak, önizleme sürümleri arasında bir hizmet yeni eklenen önizleme özelliklerinden herhangi birini bozabilir.

Önizlemeler uzun süreli kullanım için tasarlanmamıştır. Bir hizmetin yeni kararlı veya önizleme sürümü kullanılabilir olduğunda, mevcut önizleme sürümleri yeni sürümün kullanıma sunulmasından itibaren 90 gün kadar erken bir süre içinde kullanılamaz duruma gelebilir. Önizleme sürümlerini yalnızca yeni hizmet özelliklerine karşı etkin bir şekilde geliştirdiğiniz ve kullanıma sunulduktan kısa süre sonra yeni, önizleme olmayan bir sürümü benimsemeye hazır olduğunuz durumlarda kullanın. Önizleme sürümündeki bazı özellikler yeni kararlı bir sürümde yayınlanırsa, önizleme aşamasında kalan özellikler genellikle yeni bir önizleme sürümünde yayımlanır.

İstemci SDK'ları ve hizmet sürümleri

Azure SDK'ları, kod yazarken sorun olarak hizmet sürümü oluşturmayı ortadan kaldırmayı hedefler. Her SDK, her hizmet için bir tane olmak üzere istemci kitaplıklarından oluşur ve her istemci kitaplığı sürümü, bağlı olduğu hizmetin tek bir sürümünü hedefler.

Azure hizmetine erişmek için SDK kullandığınızda, yeni sürümlerden ve özelliklerden yararlanmak için genellikle uygulama tarafından kullanılan istemci kitaplığı sürümünün yükseltilmesi gerekir. Hizmetlerin yeni kararlı sürümlerine istemci kitaplıklarının yeni nokta sürümleri eşlik eder. Yeni hataya neden olan değişiklik sürümleri için, yeni istemci kitaplıkları nokta sürümü sürümleri veya ana sürüm sürümleri olarak yayımlanır. Sürüm türü, hizmetin değişikliğinin niteliğine ve kitaplığın buna uyum sağlamasına bağlıdır. Yalnızca beta sürüm istemci kitaplıkları önizleme hizmeti sürümlerini kullanır.

SDK istemci kitaplıkları hizmet sürümünü el ile geçersiz kılmayı destekler. İstemci kitaplığının varsayılan hizmet sürümünü geçersiz kılma gelişmiş bir senaryodur ve beklenmeyen davranışlara yol açabilir. Bu özelliği kullanırsanız, istediğiniz gibi çalıştığından emin olmak için uygulamanızı kapsamlı bir şekilde test edin.

Azure komut satırı araçları

SDK'larda olduğu gibi, Azure komut satırı araçları (Azure CLI ve Azure PowerShell dahil) sürümlere bakılmaksızın Azure yönetim hizmetlerinin kullanımına izin verecek şekilde tasarlanmıştır. Yeni hizmet özelliklerine erişmek için genellikle aracın yeni bir sürümü gerekir. Geriye dönük uyumlu yeni araç sürümleri aylık olarak yayınlanıyor. Hataya neden olan değişiklikler içeren sürümler yılda yaklaşık iki kez veya kritik güvenlik sorunlarını düzeltmek için gerektiği şekilde yayınlanmaktadır.

Azure komut satırı araçları zaman zaman önizleme özelliklerini kullanıma sunabilir. Bu komutlar bir Preview etiketle işaretlenir ve gelecekteki araç sürümlerinde sınırlı desteği ve olası değişiklikleri belirten bir uyarı oluşturur.

Share via