Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) ile entegrasyonda gelen JSON gövdelerini hedef mikroservisin beklediği şemaya dönüştürerek uyumluluk sağlar.
- Aynı politikayla birden fazla istemcinin üretip gönderdiği JSON formatlarını tek tip hale getirerek bakım maliyetini azaltır.
- JSON içeriklerini XML çıktısına dönüştürerek sadece XML kabul eden legacy Endpoint sistemleriyle köprü kurar.
- Koşullara göre çalıştırılarak belirli tenant, versiyon veya payload içeriğine göre dönüşüm senaryolarını dinamikleştirir.
Çalışma Prensibi
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- Politika Kontrolü: JSON Dönüştürme politikası aktif ise, sistem aşağıdaki sırayla kontrol yapar:
- Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
- Politika aktif mi (active=true)?
- Variable kullanılıyor mu yoksa Apinizer default mı?
- JSON Dönüşüm Kontrolü:
transformationTypealanı incelenir. JSON2JSON seçilmişse JOLT tanımı parse edilip istek gövdesi yeni JSON şemasına map edilir. JSON2XML seçilmişse ilgili bayraklar uygulanarak JSON içeriği XML’e çevrilir. - Karar Verme:
- Eşleşme Var: Dönüştürülen gövde request pipeline’ına geri yazılır, hedef Endpoint’e güncel içerik gönderilir ve log kaydına dönüşüm tipi işlenir.
- Eşleşme Yok: İstek orijinal yüküyle API Proxy (API Vekil Sunucusu) tarafından yönlendirilir; politika sayaçları güncellenmez.
- Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.
Özellikler ve Yetenekler
Temel Özellikler
- JSON2JSON Dönüşüm Motoru: JOLT spesifikasyonu ile alan yeniden adlandırma, hiyerarşi değiştirme ve veri zenginleştirme işlemlerini gerçekleştirir.
- JSON2XML Konfigürasyonu: Legacy sistemlere entegrasyon için JSON içeriklerini XML’e çevirirken null/boş alan yönetimi ve element paketleme seçenekleri sunar.
- Dönüşüm Test Laboratuvarı: Test Transformation Data modülü üzerinden JOLT şablonlarını canlı veriyle doğrulayıp çıktı farklarını inceleme imkânı verir.
- Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
- Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint’lere veya header değerlerine göre).
İleri Düzey Özellikler
- Global Politika Yayılım Kontrolü: Global politikalar güncellenirken kullanımda olan API Proxy ve Proxy Group listeleri otomatik kontrol edilip onay sürecine yönlendirir.
- Otomatik İsim Benzersizliği: Politika isimlerinin proje bazında çakışmaması için gerçek zamanlı doğrulama ve kullanıcıya görsel geri bildirim sağlar.
- Politika Akışı Entegrasyonu: Policy Flow modunda seçili politikayı diğer politikalarla zincirleyerek yeniden kullanım senaryolarına olanak tanır.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, Test, Canlı Ortam) import etme. Versiyon kontrolü ve yedekleme imkanı.
- Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group’lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
- Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy’lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.
Kullanım Senaryoları
| Senaryo | Durum | Çözüm (Politika Uygulaması) | Beklenen Davranış / Sonuç |
|---|---|---|---|
| Mikroservis Şema Uyumluluğu | Yeni versiyon Api Gateway’e gelen JSON alan isimleri farklı | transformationType=JSON2JSON, JOLT ile alan yeniden adlandırma | İstek gövdesi hedef şemaya uyar, backend kodu değiştirilmez. |
| Legacy XML Servisine Geçiş | Arka uç sadece XML kabul ediyor | transformationType=JSON2XML, unwrapElement=false, ignoreEmpty=true | JSON payload XML’e çevrilir, SOAP benzeri Endpoint sorunsuz cevaplar. |
| Çoklu Tenant Normalizasyonu | Tenant bazlı ekstra alanlar geliyor | JSON2JSON, joltValue ile gereksiz alanları kaldırma | Tenant farklarından bağımsız tekil JSON yapısı elde edilir. |
| Opsiyonel Alan Temizliği | Boş/null alanlar backend doğrulamasını bozuyor | JSON2XML, ignoreNull=true, ignoreEmpty=true | XML çıktısında gereksiz boş elemanlar oluşmaz, doğrulama geçer. |
| Gerçek Zamanlı Veri Zenginleştirme | Ek alan türetilmesi gerekiyor | JSON2JSON, JOLT’de defaultValue fonksiyonları | Çıktıya türetilmiş alan eklenir, servis tarafında hesaplama yapılmaz. |
| Dış Servis Entegrasyon Testi | JOLT değişiklikleri yayına alınmadan test edilmeli | JSON2JSON, test modülüyle örnek veri çalıştırma | Dönüşüm önceden doğrulanır, canlıda hata riski azalır. |
| Bölgesel Format Uyarlaması (opsiyonel) | Farklı bölgelerde tarih formatı bekleniyor | JSON2JSON, koşul ile header=Region kontrolü, JOLT format dönüşümü | Bölge bazlı JSON çıktıları tutarlı üretilir. |
Politika Parametrelerini Yapılandırma
Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP’lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.Yeni JSON Dönüştürme Politikası Oluşturma
Yapılandırma Adımları
| Adım | Açıklama / İşlem |
|---|---|
| Adım 1: Oluşturma Sayfasına Gitme | - Sol menüden Development → Global Settings → Global Policies → JSON Dönüştürme Politikası bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın. |
| Adım 2: Temel Bilgileri Girme | Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Production_JSONTransform- Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: “Sipariş JSON alanlarını normalize eder.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Dönüşüm Tipini Seçme | transformationType alanından JSON2JSON veya JSON2XML seçin. JSON2JSON seçildiğinde JOLT editörü açılır, JSON2XML seçildiğinde dönüştürme seçenekleri görünür. |
| Adım 4: JOLT Spesifikasyonunu Tanımlama (Varsa) | JSON2JSON için code editor üzerinde JOLT JSON yapısını girin, Test Transformation Data penceresinden çıktı doğrulaması yapın. Şablon kaydedilmeden önce sözdizimi hatalarını giderin. |
| Adım 5: JSON to XML Parametreleri (Varsa) | JSON2XML seçildiğinde ignoreNull, ignoreEmpty, useNullForNil, unwrapElement seçeneklerini işaretleyin. Legacy Endpoint ihtiyacına göre element paketleme veya boş alan davranışını ayarlayın. |
| Adım 6: Koşul Tanımlama (İsteğe Bağlı) | - Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Ortam bazlı: Header = X-Environment, Operator = Equals, Value = production- API Key bazlı: Header = X-API-Key, Starts With = PROD-- Endpoint bazlı: Path = /api/admin/*Koşul tanımlamazsa politika her zaman aktif Detaylar için bakabilirsiniz: Koşullar (Conditions) |
| Adım 7: Hata Mesajı Özelleştirme (İsteğe Bağlı) | - Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" }Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" } |
| Adım 8: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir dönüşüm yapılandırması mevcut Sonuç: - Politika listeye eklenir. - API’lere bağlanabilir. - Global politikaysa otomatik uygulanır. |
Politikayı Silme
Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.Politikayı Dışa/İçe Aktarma
Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına bakabilirsiniz.Politikayı API’ye Bağlama
Bu politikanın API’lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API’ye Bağlama bölümüne bakabilirsiniz.İleri Düzey Özellikler
| Özellik | Açıklama ve Adımlar |
|---|---|
| JOLT Şablon Yönetimi | - Yeni JOLT tanımlarını JSON editörde versiyonlayın. - Test Transformation Data ekranında örnek veri çalıştırın. - Hata aldığınızda joltValue alanını düzenleyip tekrar deneyin. |
| Global Politika Güncelleme Onayı | - Kaydetmeden önce kullanımda olan API Proxy listesini görüntüleyin. - Gerekirse removeCurrentProxy ile etkilenmeyecek Proxy’leri geçici dışlayın.- Onay sonrası otomatik broadcast ile bağlı ekranlar güncellenir. |
| Policy Flow Seçimi | - Policy Flow modunda setPolicyFlowMode(true) ile çalışma modunu açın.- selectEvent sayesinde başka politikalarla zincir oluşturun.- Flow tamamlandığında INSERT_UPDATE_POLICY eventiyle orkestrasyonu kaydedin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Şema Eşleştirme | Kötü: JOLT şablonunu production verisi üzerinde denemeden yayınlamak. İyi: Test dataset ile manuel kontrol yapmak. En İyi: CI pipeline’da otomatik JOLT doğrulama çalıştırmak. |
| XML Entegrasyonu | Kötü: Tüm seçenekleri varsayılan bırakıp XML çıktısını incelememek. İyi: ignoreNull/ignoreEmpty parametrelerini gereksinime göre ayarlamak.En İyi: XSD şemasına karşı XML validasyonu yaparak sonuçları doğrulamak. |
| Koşul Yönetimi | Kötü: Politikanın her istekte çalışmasına izin vermek. İyi: Query Builder’da ortam veya header bazlı temel koşullar tanımlamak. En İyi: Çoklu kriterli koşullar kurarak gereksiz dönüşümleri azaltmak. |
| Hata Mesajları | Kötü: Varsayılan hata kodunu değiştirmeden bırakmak. İyi: JOLT hataları için spesifik mesaj ve kod tanımlamak. En İyi: Hata mesajında izleme ID’si ve destek yönlendirmesi sağlamak. |
| Versiyonlama | Kötü: Eski JOLT tanımlarını silmek. İyi: Export ile yedek alıp saklamak. En İyi: Kaynak kontrolünde branch bazlı JOLT sürümleri tutmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Payload Doğrulama | JOLT ile gelen veride beklenmeyen alanların kaldırılamaması halinde zararlı içerik hedef servise ulaşabilir. Koşulları ve şema kontrollerini etkin tutun. |
| Hata Mesajı Hijyeni | Özelleştirilmiş hata mesajlarında iç sistem detaylarını paylaşmayın; yalnızca hata kodu ve genel açıklama verin. |
| Global Politika Yayılımı | Global politikalar güncellendiğinde kullanılan API Proxy listesini inceleyin, kritik servisler için değişiklik penceresi planlayın. |
| Audit Log İzleme | Dönüşüm politikalarını zorunlu olay olarak loglayın; beklenmeyen dönüşümleri erken tespit edin. |
| Yetkilendirme | Politika düzenleme yetkilerini minimum kullanıcıya verin; ROLE_DEPLOY_UNDEPLOY_PROXIES gerekli değilse kapatın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Geçersiz JOLT Dağıtımı | Neden kaçınılmalı: Sözdizimi hatalı JOLT, gateway’de 500 hatasına yol açar. Alternatif: Yayın öncesi Test Transformation Data ile doğrulayın. |
| Koşulsuz XML Dönüşümü | Neden kaçınılmalı: JSON2XML’in tüm isteklere uygulanması istemci beklentilerini bozar. Alternatif: Header/path koşulu tanımlayarak sadece gerekli çağrılarda kullanın. |
| İsim Çakışması | Neden kaçınılmalı: Aynı isimli politika import/export sırasında üzerine yazılabilir. Alternatif: Benzersiz prefix kullanın, isim doğrulama uyarılarını dikkate alın. |
| Global Güncelleme Onaysızlığı | Neden kaçınılmalı: Global politikayı kullanımda iken güncellemek tüm API Proxy trafiğini etkiler. Alternatif: Önce local kopya üzerinde test edip ardından onaylı dağıtım yapın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| JOLT Karmaşıklığı | Öneri: Şablonu küçük parçalara bölün, nested operatörleri minimize edin. Etki: Dönüşüm süresi kısalır, CPU tüketimi düşer. |
| Koşul Ön Eleme | Öneri: Query Builder’da spesifik header/path filtreleri kullanın. Etki: Gereksiz dönüşüm çalıştırmaları engellenir. |
| XML Çıktı Boyutu | Öneri: ignoreEmpty ve ignoreNull seçeneklerini aktif kullanın.Etki: Daha küçük XML çıktı, ağ gecikmesi azalır. |
| Önbellek Kullanımı | Öneri: Sık kullanılan JOLT şablonlarını politika içindeki joltValue’da saklayın, runtime’da yeniden oluşturmayın. Etki: Serialization maliyetleri düşer. |
| Monitoring | Öneri: Politikaya özel metrikler (başarı/başarısız) için Gateway izleme panellerini yapılandırın. Etki: Performans sorunları hızlı tespit edilir. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | JSON Dönüştürme Politikası hangi aşamada çalışır? | API Gateway içinde request pipeline’da, routing gerçekleşmeden önce çalışır ve güncel gövde hedef Endpoint’e iletilir. |
| Genel | Aynı anda kaç politika uygulanabilir? | Policy Group üzerinden birden fazla politika zincirlenebilir; her biri sırayla gövdeyi işleyecek şekilde yürütülür. |
| Teknik | JOLT şablonu hatalıysa ne olur? | Sistem hata mesajı sekmesinde tanımlı HTTP kodu ve mesajı döndürür; request backend’e ulaşmaz. |
| Teknik | JSON2XML dönüşümünde namespace yönetimi yapılabilir mi? | Mevcut bileşen temel JSON→XML dönüşümü sağlar; namespace ihtiyacı varsa JOLT ile ön hazırlık yapılmalıdır. |
| Kullanım | Politika local kopyaya nasıl alınır? | Detay sayfasındaki Localize butonu ile global politika local kopyaya çevrilir ve sadece seçili API’de kullanılır. |
| Kullanım | Değişiklikleri nasıl test edebilirim? | Test Transformation Data bileşeninde örnek JSON yükleyip yeni şablonun çıktısını canlı ön izleme ile karşılaştırabilirsiniz. |