Azure API Management sürümleri

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) ile 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.

Ç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 yapabilecekleri:

• API'nizin birden çok sürümünü aynı anda yayımlayın.
• Sürümleri birbirinden ayırmak 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. Bu değer sayı, tarih veya ad olabilir.
• API sürümlerinizi geliştirici portalında birlikte gruplandırılmış olarak gösterin.
• Mevcut (sürümlenmemiş) bir API'yi alın ve mevcut istemcileri bozmadan yeni bir sürümünü oluşturun.

İzlenecek kılavuzu izleyerek 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 aynı products API'ye başvurabilir, ancak sırasıyla sürümlere v1 başvurabilir v2 .

Yol tabanlı sürüm oluşturma kullanılırken API istek URL'sinin biçimi: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Üst bilgi tabanlı sürüm oluşturma

Ü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, adlı Api-Versionözel bir üst bilgi oluşturabilirsiniz ve istemciler bu üst bilginin değerini veya v2 değerini belirtebilirv1.

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 kullanılırken API isteği URL'sinin biçimi: 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 aynı products API'ye başvurabilir, ancak sırasıyla sürümlere v1 başvurabilir v2 .

Not

OpenAPI belirtiminin özelliğinde servers 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. Sürüm, Original mevcut arayanların sürüm ekleme işlemiyle bozulmamasını sağlar. Başlangıçta sürümleri etkinleştirilmiş yeni bir API oluşturursanız, sürüm Original oluşturulmaz.

Sürümler nasıl temsil edilir?

Azure 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, sürümlenmiş API'nin görünen adını ve istekleri belirtilen sürümlere yönlendirmek için kullanılan sürüm oluşturma düzenini içerir.

Bir API'nin her sürümü kendi API kaynağı olarak tutulur ve bu kaynak 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 API'sini kullanarak sürüm kümelerini doğrudan görüntüleyebilir ve yönetebilirsiniz.

Not

Bir sürüm kümesindeki tüm sürümler, BIR API'ye ilk kez sürüm eklediğinizde kullanılan sürüm oluşturma şemasına göre aynı sürüm oluşturma düzenine sahiptir.

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 API sürümü olarak Original yapılandırılır. API, sürüm kümesine bağlıdır ancak belirtilmesi için bir sürüm tanımlayıcısı gerektirmez.
• Yeni sürüm yeni bir API olarak oluşturulur ve sürüm kümesine bağlanır. Bu yeni API'ye sürüm oluşturma düzeni ve tanımlayıcı kullanılarak erişilmelidir.

Sürümler ve düzeltmeler

Sürümler ve düzeltmeler ayrı özelliklerdir. Her sürüm, aynı sürüme sahip olmayan BIR API gibi birden çok düzeltmeye sahip olabilir. Sürümleri kullanmadan veya başka bir yolla düzeltmeleri kullanabilirsiniz. Normalde sürümler, API sürümlerini hataya neden olan değişikliklerle ayırmak için kullanılırken, düzeltmeler 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 isterseniz, düzeltmeden bir sürüm oluşturabilirsiniz. Azure portalını kullanarak, Düzeltmeler sekmesindeki düzeltme bağlam menüsünde 'Düzeltmeden Sürüm Oluştur'a tıklayın.

Geliştirici portalı

Geliştirici portalı, BIR API'nin her sürümünü ayrı olarak listeler.

Bir API'nin ayrıntıları, bu API'nin tüm sürümlerinin listesini de gösterir. Sürüm Original tanımlayıcısı olmadan bir sürüm görüntülenir.

İpucu

API sürümlerinin geliştirici portalında görünür hale gelmeden önce bir ürüne eklenmesi gerekir.