API'leri yayımlamak için DevOps ve CI/CD kullanma

UYGULANANLAR: Tüm API Management katmanları

Kuruluştaki API'lerin stratejik değeriyle DevOps sürekli tümleştirme (CI) ve dağıtım (CD) tekniklerini benimsemek API geliştirmenin önemli bir yönü haline gelmiştir. Bu makalede, API'lerin yönetimi için DevOps ilkelerini benimsemek için almanız gereken kararlar ele alınmaktadır.

API DevOps üç bölümden oluşur:

API DevOps işlem hattının her bölümü aşağıda ele alınmaktadır.

API tanımı

API geliştiricisi API'ye uygulanacak belirtim, ayarlar (günlük, tanılama ve arka uç ayarları gibi) ve ilkeler sağlayarak bir API tanımı yazar. API tanımı, Azure API Management hizmetinde API'yi sağlamak için gereken bilgileri sağlar. Belirtim, standartlara dayalı bir API belirtimini (WSDL, OpenAPI veya GraphQL gibi) temel alabilir veya Azure Resource Manager (ARM) API'leri (örneğin, API ve işlemleri açıklayan bir ARM şablonu) kullanılarak tanımlanabilir. API tanımı zaman içinde değişir ve "kaynak kod" olarak kabul edilmelidir. API tanımının kaynak kodu denetimi altında depolandığından ve benimsemeden önce uygun incelemeye sahip olduğundan emin olun.

API tanımının üretilmesine yardımcı olacak çeşitli araçlar vardır:

• Azure APIOps Araç Seti, git kaynak kodu denetim sisteminin (GitHub veya Azure Depoları gibi) üzerine kurulmuş bir iş akışı sağlar. Bir yayımcı tarafından hedef API Management hizmetine uygulanan bir API tanımı oluşturmak için ayıklayıcı kullanır. APIOps şu anda REST ve GraphQL API'lerini destekler.
• dotnet-apim aracı, iyi biçimlendirilmiş bir YAML tanımını daha sonra dağıtım için ARM şablonuna dönüştürür. Araç REST API'lerine odaklanmıştır.
• Terraform , Azure'daki kaynakları yapılandırmak için Azure Resource Manager'a bir alternatiftir. API'yi ARM şablonunun oluşturulduğu şekilde uygulamak için terraform yapılandırması (ilkelerle birlikte) oluşturabilirsiniz.

API'yi tanımlamak için gerekli yapıtları üretmek için Visual Studio Code gibi düzenleyiciler için IDE tabanlı araçları da kullanabilirsiniz. Örneğin, Visual Studio Code Market'te OpenAPI belirtim dosyalarını düzenlemek için 30'un üzerinde eklenti vardır. Yapıtları oluşturmak için kod oluşturucuları da kullanabilirsiniz. CADL dili, kolayca üst düzey yapı taşları oluşturmanıza ve bunları OpenAPI gibi standart bir API tanımı biçiminde derlemenize olanak tanır.

API onayı

API tanımı oluşturulduktan sonra geliştirici, API tanımını gözden geçirme ve onay için gönderir. Git tabanlı bir kaynak kodu denetim sistemi (GitHub veya Azure Repos gibi) kullanılıyorsa gönderme işlemi Çekme İsteği aracılığıyla gerçekleştirilebilir. Çekme isteği, API tanımına önerilen değişiklikleri diğer kişilere bildirir. Onay geçitleri onaylandıktan sonra onaylayan, API tanımının üretime dağıtılabildiğini doğrulamak için çekme isteğini ana depoyla birleştirir. Çekme isteği işlemi, geliştiricinin onay işlemi sırasında bulunan sorunları düzeltmesini sağlar.

Hem GitHub hem de Azure Repos, çekme isteği gönderildiğinde çalıştırılan onay işlem hatlarının yapılandırılmasına izin verir. Onay işlem hatlarını aşağıdaki gibi araçları çalıştıracak şekilde yapılandırabilirsiniz:

• Tanımın kuruluşun gerektirdiği API standartlarını karşıladığından emin olmak için Spectral gibi API belirtim lintleri.
• Openapi-diff gibi araçları kullanarak hataya neden olan değişiklik algılama.
• Güvenlik denetimi ve değerlendirme araçları. OWASP, güvenlik taraması için araçların listesini tutar.
• Postman koleksiyonları için bir test çalıştırıcısı olan Newman gibi otomatik API test çerçeveleri.

Not

Azure API'leri, kendi API yönergeleriniz için başlangıç noktası olarak kullanabileceğiniz katı bir yönergeler kümesine uymalıdır. Yönergeleri zorunlu kılmaya yönelik bir Spectral yapılandırması vardır.

Otomatikleştirilmiş araçlar çalıştırıldıktan sonra API tanımı insan gözü tarafından gözden geçirilir. Araçlar tüm sorunları yakalamaz. gözden geçiren bir insan, API tanımının güvenlik, gizlilik ve tutarlılık yönergeleri gibi API'ler için kuruluş ölçütlerini karşılamasını sağlar.

API yayını

API tanımı, yayın işlem hattı aracılığıyla bir API Management hizmetinde yayımlanır. API tanımını yayımlamak için kullanılan araçlar, API tanımını oluşturmak için kullanılan ara çubuğuna bağlıdır:

• Azure APIOps Araç Seti kullanılıyorsa araç seti, API tanımını hedef hizmete yazan bir yayımcı içerir.
• dotnet-apim kullanılıyorsa, API tanımı bir ARM şablonu olarak temsil edilir. Arm şablonu dağıtmak için Azure Pipelines ve GitHub Actions için görevler kullanılabilir.
• Terraform kullanılıyorsa, CLI araçları API tanımını hizmetinize dağıtır. Azure Pipelines ve GitHub Actions için kullanılabilir görevler vardır.

Diğer kaynak kodu denetimini ve CI/CD sistemlerini kullanabilir miyim?

Evet. Açıklanan işlem herhangi bir kaynak kodu denetim sistemiyle çalışır (APIOps, kaynak kod denetim sisteminin git tabanlı olmasını gerektirse de). Benzer şekilde, azure ile iletişim kuran bir iade ve komut satırı araçları tarafından tetiklenebildiği sürece herhangi bir CI/CD platformlarını kullanabilirsiniz.

En iyi yöntemler

API'leri yayımlamak için DevOps işlem hattı ayarlamak için endüstri standardı yoktur ve bahsedilen araçların hiçbiri her durumda çalışmaz. Ancak, çoğu durumun aşağıdaki araç ve hizmetlerin bir bileşimi kullanılarak ele alındığını görüyoruz:

• Azure Repos API tanımlarını bir git deposunda depolar.
• Azure Pipelines , otomatik API onayı ve API yayın işlemlerini çalıştırır.
• Azure APIOps Toolkit , API'leri yayımlamaya yönelik araçlar ve iş akışları sağlar.

Müşteri dağıtımlarında en büyük başarıyı gördük ve aşağıdaki uygulamaları öneririz:

• Kaynak kodu denetim sisteminiz için GitHub veya Azure Repos'ı ayarlayın. Bu seçim, işlem hattı çalıştırıcısı seçiminizi de belirler. GitHub Azure Pipelines veya GitHub Actions kullanabilirken Azure Repos'un Azure Pipelines kullanması gerekir.
• API hizmetiyle birlikte API tanımları geliştirebilmeleri için her API geliştiricisi için bir Azure API Management hizmeti ayarlayın. Hizmeti oluştururken tüketim veya geliştirici SKU'su kullanın.
• Geliştiricilerin her API için yazması gereken yeni ilkeyi azaltmak için ilke parçalarını kullanın.
• İlkelerin genel olduğundan ve herhangi bir API Management örneğine uygulanadığından emin olmak için adlandırılmış değerleri ve arka uçları kullanın.
• Geliştirici hizmetinden çalışan bir API tanımını ayıklamak için Azure APIOps Araç Seti'ni kullanın.
• Her çekme isteğinde çalışan bir API onay işlemi ayarlayın. API onay işlemi hataya neden olan değişiklik algılama, lint ve otomatik API testlerini içermelidir.
• API'yi üretim API Management hizmetinizde yayımlamak için Azure APIOps Toolkit yayımcısını kullanın.

APIOps ile CI/CD dağıtım işlem hattını yapılandırma ve çalıştırma hakkında daha fazla bilgi için Azure Mimari Merkezi'nde APIOps ile otomatik API dağıtımları bölümünü gözden geçirin.

Başvurular

• Azure DevOps Services, Azure Repos ve Azure Pipelines'ı içerir.
• Azure APIOps Toolkit , API Management DevOps için bir iş akışı sağlar.
• Spectral , OpenAPI belirtimleri için bir linter sağlar.
• openapi-diff , OpenAPI v3 tanımları için hataya neden olan bir değişiklik algılayıcısı sağlar.
• Newman, Postman koleksiyonları için otomatik bir test çalıştırıcısı sağlar.