Azure API Management'taki sürümler

UYGULANANLAR: Tüm API Management katmanları

Sürümler, ilgili API gruplarını geliştiricilerinize sunmanızı sağlar. API'nizdeki hataya neden olan değişiklikleri güvenli bir şekilde işlemek için sürümleri kullanabilirsiniz. İstemciler hazır olduklarında yeni API sürümünüzü kullanmayı seçebilirken, mevcut istemciler eski bir sürümü kullanmaya devam edebilir. Sürümler bir sürüm tanımlayıcısı (seçtiğiniz herhangi bir dize değeridir) aracılığıyla ayırt edilir ve sürüm oluşturma düzeni istemcilerin bir API'nin hangi sürümünü kullanmak istediklerini belirlemesine olanak tanır. Bu makalede API Management'ta sürümlerin nasıl kullanılacağı açıklanmaktadır.

Çoğu amaçla, her API sürümü kendi bağımsız API'si olarak kabul edilebilir. İki farklı API sürümünün farklı işlem kümeleri ve farklı ilkeleri olabilir.

Sürümlerle yapabilecekleriniz:

• API'nizin birden çok sürümünü aynı anda yayımlayın.
• Sürümleri ayırt etmek için yol, sorgu dizesi veya üst bilgi kullanın.
• Sürümünüzü tanımlamak istediğiniz herhangi bir dize değerini kullanın. Bir sayı, tarih veya ad olabilir.
• API sürümlerinizi geliştirici portalında birlikte gruplandırılmış olarak gösterin.
• Mevcut istemcileri etkilemeden var olan (sürümlenmemiş) bir API'nin yeni bir sürümünü oluşturun.

Adım adım kılavuzu tamamlayarak sürümleri kullanmaya başlayın.

Sürüm oluşturma düzenleri

Farklı API geliştiricilerinin sürüm oluşturma için farklı gereksinimleri vardır. Azure API Management, sürüm oluşturma için tek bir yaklaşım belirlemez, ancak bunun yerine çeşitli seçenekler sunar.

Yol tabanlı sürüm oluşturma

Yol sürüm oluşturma düzeni kullanıldığında, herhangi bir API isteği için sürüm tanımlayıcısının URL yoluna eklenmesi gerekir.

Örneğin, https://apis.contoso.com/products/v1 ve https://apis.contoso.com/products/v2, products ve v1 sürümlerine sahip aynı v2 API'ye atıfta bulunabilir.

Yol tabanlı sürüm oluşturma kullandığınızda API isteği URL'sinin biçimi şeklindedir https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Üst bilgi tabanlı sürümleme

Üst bilgi sürüm oluşturma düzeni kullanıldığında, tüm API istekleri için sürüm tanımlayıcısının bir HTTP isteği üst bilgisine eklenmesi gerekir. HTTP isteği üst bilgisinin adını belirtebilirsiniz.

Örneğin, Api-Versionadlı özel bir üst bilgi oluşturabilirsiniz ve istemciler bu üst bilginin değerinde v1 veya v2 belirtebilir.

Sorgu dizesi tabanlı sürüm oluşturma

Sorgu dizesi sürüm oluşturma düzeni kullanıldığında, tüm API istekleri için bir sorgu dizesi parametresine sürüm tanımlayıcısının eklenmesi gerekir. Sorgu dizesi parametresinin adını belirtebilirsiniz.

Sorgu dizesi tabanlı sürüm oluşturma kullandığınızda API isteği URL'sinin biçimi şeklindedir https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Örneğin, https://apis.contoso.com/products?api-version=v1 ve https://apis.contoso.com/products?api-version=v2, products ve v1 sürümlerine sahip aynı v2 API'ye atıfta bulunabilir.

Uyarı

OpenAPI belirtiminin servers özelliğinde sorgu parametrelerine izin verilmez. OpenAPI belirtimini BIR API sürümünden dışarı aktarırsanız, sunucu URL'sinde bir sorgu dizesi görünmez.

Özgün sürümler

Sürüm olmayan bir API'ye sürüm eklerseniz, Original bir sürüm otomatik olarak oluşturulur ve sürüm tanımlayıcısı belirtilmeden varsayılan URL'de yanıt verir. Original sürümü, mevcut arayanların sürüm ekleme sürecinden etkilenmemesini sağlar. Başlangıçta sürümleri etkinleştirilmiş yeni bir API oluşturursanız, Original sürümü oluşturulmaz.

Sürümler nasıl temsil edilir?

API Management, tek bir mantıksal API için bir sürüm kümesini temsil eden sürüm kümesi adlı bir kaynak tutar. Sürüm kümesi, istekleri belirtilen sürümlere yönlendirmek için kullanılan sürüm oluşturma düzenini ve sürüm oluşturma API'sinin görünen adını içerir.

Bir API'nin her sürümü kendi API kaynağı olarak tutulur ve bir sürüm kümesiyle ilişkilendirilir. Sürüm kümesi, farklı işlemlere veya ilkelere sahip API'ler içerebilir. Bir kümedeki sürümler arasında önemli değişiklikler yapabilirsiniz.

Azure portalı sizin için sürüm kümeleri oluşturur. Azure portalında bir sürüm kümesinin adını ve açıklamasını değiştirebilirsiniz.

Son sürüm silindiğinde bir sürüm kümesi otomatik olarak silinir.

Azure CLI, Azure PowerShell, Resource Manager şablonlarıveya Azure Resource Manager APIkullanarak sürüm kümelerini doğrudan görüntüleyebilir ve yönetebilirsiniz.

Uyarı

Sürüm kümesindeki tüm sürümler aynı sürüm oluşturma düzenine sahiptir. Api'ye ilk sürüm eklediğinizde kullanılan sürüm oluşturma düzenini temel alır.

Sürümlenmemiş BIR API'yi sürümlenmiş API'ye geçirme

Mevcut bir API'de sürüm oluşturmayı etkinleştirmek için Azure portalını kullandığınızda, API Management kaynaklarınızda aşağıdaki değişiklikler yapılır:

• Yeni bir sürüm kümesi oluşturulur.
• Mevcut sürüm korunur ve Original API sürümü olarak yapılandırılır. API sürüm kümesine bağlıdır, ancak bir sürüm tanımlayıcısının belirtilmesi gerekmez.
• Yeni sürüm, yeni bir API olarak oluşturulur ve sürüm kümesine bağlanır. Yeni API'ye erişmek için bir sürüm oluşturma düzeni ve tanımlayıcı kullanılmalıdır.

Sürümler ve düzeltmeler

Sürümler ve düzeltmeler ayrı özelliklerdir. Her sürüm, sürüm numarası olmayan bir API gibi birden fazla gözden geçirmeye sahip olabilir. Sürümleri kullanmadan veya başka bir yolla düzeltmeleri kullanabilirsiniz. Sürümler genellikle, hataya neden olan değişiklikler içeren API sürümlerini ayırmak için kullanılır ve düzeltmeler bir API'de küçük ve hataya neden olmayan değişiklikler için kullanılabilir.

Düzeltmenizde hataya neden olan değişiklikler olduğunu fark ederseniz veya düzeltmenizi resmi olarak beta/test sürümüne dönüştürmek istiyorsanız, düzeltmeden bir sürüm oluşturabilirsiniz. Azure portalında, Düzeltmeler sekmesindeki düzeltme bağlam menüsünde (...) Bu Düzeltmeden Sürüm Oluştur'u seçin.

Geliştirici portalı

Geliştirici portalı bir API'nin her sürümünü ayrı olarak listeler:

BIR API'nin ayrıntılarında, API'nin tüm sürümlerinin listesini de görebilirsiniz. Bir versiyon, versiyon tanımlayıcısı olmadan görüntülenir:

İpucu

Api sürümlerini geliştirici portalında görünür hale getirmek için bir ürüne eklemeniz gerekir.