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

UYGULANANLAR: Tüm API Management katmanları

Kuruluştaki API'lerin stratejik değeri sayesinde DevOps sürekli tümleştirme (CI) ve sürekli 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, bir API tanımı yazarak belirtim, ayarlar (günlük, tanılama ve arka uç ayarları gibi) ve API'ye uygulanacak ilkeler sağlar. 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 ayıklayıcı kullanarak bir API tanımı üretir ve ardından bir yayımcı tarafından bu tanım, hedef API Management hizmetine uygulanı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 90'dan fazla eklenti vardır. Yapıtları oluşturmak için kod oluşturucuları da kullanabilirsiniz. TypeSpec dili, bulut hizmeti API'lerini ve şekillerini tanımlamanıza olanak tanır ve REST, OpenAPI, gRPC ve diğer protokoller arasında ortak api şekillerini açıklayabilen temel öğelerle yüksek oranda genişletilebilir.

API onayı

API tanımı oluşturulduğunda, 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ıyorsanız, geliştirici çekme isteği aracılığıyla gönderebilir. "Pull" isteği, API tanımı için ö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 havuza 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ı yapılandırmanıza olanak sağlar. Onay işlem hatlarını aşağıdaki gibi araçları çalıştıracak şekilde yapılandırabilirsiniz:

• Kuruluşun gerektirdiği API standartlarına uygun tanımlar hazırlamak için Spectral gibi API belirtim kontrol araçlarını kullanın.
• openapi-diff gibi araçlar kullanarak kritik değişiklik tespiti.
• Güvenlik denetimi ve değerlendirme araçları. OWASP, güvenlik taraması için araçların listesini tutar.
• 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 uygulamak için bir Spectral yapılandırması bulunmaktadı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ıyorsanız, 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 ve bir kontrol tarafından tetiklenebilen komut satırı araçlarını çalıştıran herhangi bir CI/CD platformunu 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 durum aşağıdaki araç ve hizmetlerin bir bileşimi kullanılarak ele alınmıştır:

• 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.

Aşağıdaki uygulamaları kullanarak müşteri dağıtımlarında en büyük başarıyı gördük:

• 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 süreci, uyumsuz değişiklik algılama, linting 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.

Kaynaklar

• 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.