API'nizi sürüm denetimiyle geliştirme

Makale
06/23/2023

Azure Logic Apps, Microsoft Power Automate veya Microsoft Power Apps için özel bağlayıcılar bir OpenAPI belirtim dosyası sağlamalıdır. Bu OpenAPI belirtimi, işlemler olarak bilinen tek tek giriş noktalarını tanımlar. Her işlemin benzersiz bir operationId öğesi ile benzersiz bir urlPath ve HttpVerb birleşimi vardır.

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

Bu işlemler, özellikler eklendikçe veya genişletildikçe zamanla büyüyebilir ve değişebilir. Bazı değişiklikler yalnızca eklemelerdir ve istemcilerle sunucular arasındaki sözleşmeyi bozmayabilir. Yeni parametreler ekleme, daha fazla veri döndürme veya daha esnek girişlere izin verme bu kategoriye girebilir.

Ancak birçok değişiklik OpenAPI belirtiminde açıklanan sözleşmeyi gerçekten bozabilir. Parametreleri kaldırma, bazı girişleri artık desteklememe ya da bir girişin, çıkışın veya işlemin kendisinin anlamını ve davranışını değiştirme "hataya neden olan değişiklik" kategorisine girer.

API'yi güvenli bir şekilde geliştirmek için istemciler tarafından izlenebilecek bir desene uymak önemlidir. Geriye dönük uyumluluğu korumak, amacı iletmek ve sürüm oluşturma özniteliklerini tarif etmek API'nin sorumluluğundadır. Kullanım dışı bırakılan, süresi dolan veya daha yeni sürümleri sağlanmış olabilecek işlemleri göstermek ya da gizlemek istemcinin sorumluluğundadır. Bu şekilde işlemler onlara dayanan uygulamalarda uygunsuz bir kırılganlığına yol açmadan zaman içinde büyüyebilir ve gelişebilir.

API Ek Açıklaması

OpenAPI'nin işlem sürümü oluşturmaya yönelik iç desteği yoktur. Hedefimize ulaşmak için çalışmanın büyük bölümü hem genel bağlamda hem de işlem bağlamında uygulanan x-ms-api-annotation nesnesi aracılığıyla yapılır. Genel nesne bir bütün olarak API'ye uygulanan özellikler içerir:

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}

Özellik	Değerler	Varsayılan	Açıklama
durum	`"Preview"` `"Production"`	`"Preview"`	Bir bütün olarak API'nin durumu—Önizleme aşamasında başlar, kullanım ve kararlılık açısından gerekli olduğunda Üretim aşamasına ilerletilir

İşlem kapsamında bu nesne daha ayrıntılı özellikler içerir. Ayrıca nesnenin dışında kalan, sürüm geliştirme işlemine uygulanan ve katılan başka özellikler de vardır:

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}

Özellik	Değerler	Varsayılan	Açıklama
kullanım dışı	`null` `false` `true`	`false`	İşlemin kullanım dışı bırakılıp bırakılmadığını gösterir
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	Bu işlemin hedeflenen görünürlüğü ve belirginliği; burada `null` veya `""`, Normal durumu belirtir
durum	`"Preview"` `"Production"`	`"Production"`	İşlemin durumu—bu API'nin kendi durumundan farklı olabilir ama belirtilmezse üst düzey API durumundan devralınır
aile	{ortak işlem adı}	operationName	Bu işlemin her düzeltmesi için geçerli olan ad
düzeltme	sayısal (1,2,3...)	`1`	Belirtilen işlem ailesinin düzeltmesi
sona erme tarihi	ISO8601 tarihi	(hiçbiri)	Öngörülen destek sonu zamanını belirtmek için istemciye sağlanan isteğe bağlı ipucu

Kullanım Dışı, istemcilerin artık bu işlemi kullanması istenmediğinde true olarak ayarlanabilir. Bu özellik OpenAPI Sabit Alanları belirtiminde mevcuttur.

Görünürlük, işlemin amaçlanan göreli belirginlik düzeyini gösterir. "Important" belirginlik değeri işlemin listenin üst kısımlarında yer alması, belirgin bir şekilde gösterilmesi gerektiğini belirtir. Normal görünürlük (null veya boş "" dizesiyle gösterilir) varsayılan ayardır ve işlemin listede büyük olasılıkla Önemli işlemlerden sonra gösterileceği anlamına gelir. "Advanced" görünürlük değeri işlemin listenin alt kısımlarında yer alabileceğini ve hatta başlangıçta bir expando denetimi ardına gizlenebileceğini belirtir. Gelişmiş (Advanced) işlemlerin kullanılması zor, daha az popüler veya daha dar alanda uygulanabilir olabilir. "Internal" görünürlük değeri işlemin kullanıcıların kullanımına sunulmaması ve yalnızca dahili olarak kullanılması gerektiğini gösterir. Dahili işlemler programlama açısından yararlı ve değerli olabilir ancak son kullanıcılara yönelik değildir. Ayrıca dahili işlemler, kullanım dışı bırakma sürecinde bunları API'den fiili olarak kaldırmadan her türlü kullanıcı arabiriminden gizlemek amacıyla bu şekilde işaretlenebilir. Aksi takdirde bunlar hataya neden olan bir değişikliğe yol açabilir.

Durum API'nin veya işlemin kararlılığını gösterir. "Preview" işlemin veya API'nin yeni olduğunu ve kanıtlanmamış olabileceğini belirtir. Önizleme, üretim sistemlerinin bir bağımlılık belirtme konusunda ihtiyatlı olması gerektiğinin göstergesidir. İşlem veya API daha yerleşik hale geldiğinde ve güvenilirlik, başarı oranı ve ölçeklenebilirlik standartlarına uyduğu kanıtlandığında özellikle "Production" durumuna yükseltilebilir.

"Production" durumunu hedefleyen işlemlerde genel olarak aşağıdaki ölçüm gereksinimleri geçerlidir:

Üç haftalık bir süre boyunca %80 başarı oranı
- 2xx aralığında HTTP yanıt kodlarının yüzdesi olarak tanımlanır
Üç haftalık bir süre boyunca sürdürülen %99,9 güvenilirlik
- 5xx aralığı dışında HTTP yanıt kodlarının yüzdesi olarak tanımlanır (502, 504 ve 520 bu hesaplamanın dışında bırakılır)

Aile kavramsal olarak aynı işlem olan ancak aralarında potansiyel olarak hataya neden olabilecek değişiklikler içeren farklı düzeltmeler bulunan işlemler arasındaki ilişkiyi gösterir. Birbirinin düzeltmesi olarak kabul edilen ve benzersiz düzeltme numaralarıyla sıralanan birden çok işlem aynı aile adını paylaşır.

Düzeltme, işlem ailesi içindeki işlemin gelişim sırasını gösterir. Ailenin içindeki her işlemin, sırayı ortaya koyacak bir tam sayı dizini olan bir düzeltmesi bulunur. Boş bir düzeltme, düzeltme 1 olarak değerlendirilir. İşlemin daha yeni düzeltmeleri kullanıma sunulduğunda istemcilerin bunları daha belirgin olarak görüntülemesi ve daha kasıtlı önermesi gerekir. Ancak daha eski olabilecek ama henüz kullanım dışı bırakılmamış düzeltmelerin seçilmesine de izin vermelidir.

Sona erme tarihi isteğe bağlıdır ve işleme yönelik desteğin artık garanti edilmediği olası kullanım ömrü sonunu gösterir. Bu özellik yalnızca kullanım dışı bırakılan işlemler için ayarlanmalıdır ve şu anda hiçbir arabirimde yansıtılmamaktadır.

İşlem Yaşam Süresi

İşlemlerin örnekle gösterilebilen öngörülebilir bir yaşam süresi bulunur.

Başlangıç Noktası

Başlangıçta işlemlerin düzeltmeler hakkında herhangi bir bilgi göstermesi gerekmez. Bu işlemlere varsayılan değerler uygulanır ve bu nedenle operationId ile eşdeğer bir aile adında düzeltme 1 olarak kabul edilir.

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

Bu, daha belirgin bir tanımla eşdeğerdir:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

İşlem Başlatma

API'nin gelişmelerinin çoğu, bir işlem eklenmesinden oluşur. Örneğin, yeni yöntemler ve mevcut yöntemlerin yeni düzeltmeleri olabilir. Yeni düzeltmeyi güvenli bir şekilde başlatmak için OpenAPI belirtimi şu şekilde ayarlanır:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Önemli

GetItems V2'nin benzersiz bir operationId değeri olduğuna ve başlangıçta önizleme durumunda listelendiğine dikkat edin. Ayrıca GetItems v1'in artık gelişmiş görünürlüğü olduğuna, dolayısıyla belirgin olarak görüntülenmeyeceğine de dikkat edin.

İşlemin Kullanımdan Kaldırılması

Bazen mevcut V1 giriş noktaları değer sağlamaya devam ediyorsa ve bunları sona erdirmeye zorlayan bir neden yoksa, bunlar süresiz olarak kalır. Öte yandan birçok V2 giriş noktası kasten V1 giriş noktasının yerine geçer. Bunun güvenle yapılabilmesi için özgün işleme yönelik tüm trafiğin tam olarak sıfıra ulaşması gerekir. Telemetride bu durum onaylandıktan sonra aşağıdaki değişiklik yapılabilir:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

Önemli

GetItems V1'in artık kullanım dışı olarak işaretlendiğine dikkat edin. Bu, kullanımdan kaldırılan işlemler için son geçiştir. GetItems V2 artık tamamen GetItems V1'in yerini almıştır.

Bu neden önemlidir?

İşlem sürümü oluşturmaya bağlı kalmanın birçok nedeni vardır. En önemlisi bunu yapmak kullanıcılar bağlayıcı işlemlerini kendi veri akışlarıyla tümleştirdiklerinde Azure Logic Apps ve Power Automate gibi istemcilerin doğru çalışmaya devam etmesini sağlar. Aşağıdaki durumlarda işlemler için yukarıda açıklanan yöntemle sürüm oluşturulmalıdır:

İşlemin yeni bir düzeltmesi eklendiğinde
Mevcut işlem, parametreler eklediğinde veya kaldırdığında
Mevcut işlem girişte ve çıkışta önemli değişiklikler yaptığında

Kesin Konuşmak Gerekirse

Bazı durumlarda sürüm oluşturmaktan kaçınabilirsiniz ancak bunu yaparken kullanıcılarda beklenmedik hatalara yol açabilecek uç örnekleri göz ardı etmediğinizden emin olmak için dikkatli olmanız ve bol miktarda test yapmanız gerekir. Burada sürüm oluşturmaktan kaçınabileceğiniz durumların kısa bir listesi verilmiştir:

Yeni bir işlem eklenir.

Bu, özellikle mevcut istemcileri bozmaz.
Mevcut bir işleme yeni bir isteğe bağlı parametre eklendiğinde.

Bu mevcut çağrıları bozmaz ancak bu işlemin dikkatli bir şekilde yapılması gerekir.
Mevcut işlem örtülü bir şekilde davranışını değiştirdiğinde.

Değişikliğin doğasına ve kullanıcıların neye güvendiğine bağlı olarak bu durum mevcut çağrılarda hataya yol açmayabilir. En riskli olanı budur çünkü giriş kabulü, çıkış oluşturma, zamanlama veya işlemede önemli bir farklılık, işlemin davranışında değişikliğin getirdiği riski belirlemeyi zorlaştırabilecek bir etki yaratabilir.

Her zaman tedbiri elden bırakmamanız ve yaptığınız her önemli API değişikliğinde düzeltmeyi yinelemeniz önerilir.

Geri bildirimde bulunun

Bağlayıcı platformumuzla ilgili sorunlar veya yeni özellik fikirleri hakkındaki geri bildiriminiz bizim için çok önemlidir. Geri bildirimde bulunmak için Sorun gönderme veya bağlayıcılarla ilgili yardım alma bölümüne gidip geri bildirim türünü seçin.

Share via