Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) üzerindeki XML mesajlarını hedef sistemlerin beklediği forma dönüştürerek entegrasyon uyumluluğu sağlar.
- XSLT tabanlı XML2XML dönüştürmelerle iş kurallarını mesaj katmanında uygulama imkânı sunar.
- XML2JSON moduyla XML tabanlı servisleri JSON tüketen istemcilere aracısız servis eder.
- Dönüşüm hatalarını standartlaştırılmış hata mesajları ve durum kodlarıyla yakalayıp izlenebilir hale getirir.
Ç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ü: XML Dönüşümü 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ı?
- XML Dönüşüm Kuralları: Koşullar sağlanıyorsa seçilen
transformationTypeiçin XSLT içeriği veya XML→JSON bayrakları yüklenir, gerekli doğrulamalar yapılır. - Karar Verme:
- Eşleşme Var: XML içerik seçilen moda göre dönüştürülür, sonuç gövdesi ve header değerleri yeni formata göre güncellenir.
- Eşleşme Yok: Orijinal mesaj Gateway üzerinden değiştirilmeden aktarılır.
- 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
- Çift Dönüşüm Modu: XML2XML (XSLT) ve XML2JSON seçenekleriyle farklı entegrasyon ihtiyaçlarını aynı politika altında yönetir.
- XSLT Editörü ve Önizleme: Gelişmiş kod editörü ve test aracıyla XSLT kurallarını kaydetmeden önce doğrulama olanağı verir.
- JSON Çıktı Optimizasyonu: XML→JSON dönüşümlerinde null, boş ve sayı alanlarını hedef formata göre esnek biçimde yönetir.
- 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
- Dönüşüm Test Laboratuvarı: Test Transformation Data bileşeni ile XML girdileri üzerinde gerçek zamanlı XSLT denemeleri yapılabilir.
- Çakışma Önleme Mekanizması: İsim benzersizliği kontrolüyle global ve local politikalar arasında çakışmaları proaktif olarak engeller.
- XML→JSON Dizi Eşlemesi: Array Path List parametresiyle belirli XPath ifadelerini JSON dizilerine dönüştürür.
- Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) 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ç |
|---|---|---|---|
| XSLT ile Şema Uyarlama | Üretici XML şeması tüketici beklentisiyle uyumsuz | transformationType=XML2XML, yeni XSLT ekle. | Hedef sisteme uygun XML şeması gönderilir. |
| XML’den JSON API’lere Köprü | Eski SOAP servisi REST istemcilerine açılacak | transformationType=XML2JSON, null/empty filtreleri aktive et. | REST istemcisi JSON yanıt alır. |
| XML Alanlarını Filtreleme | XML gövdesinde hassas etiketler çıkarılmalı | XML2XML, XSLT’de ilgili nodeları kaldır. | Hassas alanlar olmadan içerik aktarılır. |
| XML Sayı Formatlarını Normalize Etme | XML içindeki sayılar string olarak iletilmeli | XML2JSON, xmlToJsonNumbersAsStrings=true. | Tüm sayılar string tipine dönüştürülür. |
| Nil Değerlerini Null’a Çevirme | xsi:nil alanlarının JSON’da null olması isteniyor | XML2JSON, xmlToJsonUseNullForNil=true. | JSON çıktısında null değerleri görünür. |
| Dizi Yapılandırması | Tekil node’lar JSON dizisine dönüştürülmeli | XML2JSON, xmlToJsonArrayPathListe XPath ekle. | Belirtilen yollar JSON array’e dönüşür. |
| Koşullu Dönüşüm | Sadece belirli endpoint’lerde dönüşüm gerek | Query Builder’da endpoint koşulu tanımla. | Koşul tutmadığında dönüşüm uygulanmaz. |
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 XML Dönüşümü 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 → XML Dönüşümü 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_XMLTransform- 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: “SAP XML yanıtlarını JSON REST formatına dönüştürür” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Dönüşüm Tipini Seçme | transformationType alanından XML2XML veya XML2JSON seçin. Seçim, alt parametrelerin görünürlüğünü belirler. XML2XML seçildiğinde XSLT editörü açılır, XML2JSON seçildiğinde JSON seçenekleri aktif olur. |
| Adım 4: XSLT Kurallarını Yönetme (Varsa) | XML2XML modunda xsltValue editöründe dönüşüm şablonunu girin. Kod editörü syntax highlighting sağlar. Test Transformation butonuyla örnek XML üzerinde XSLT’yi doğrulayın. |
| Adım 5: XML→JSON Ayarlarını Yapılandırma (Varsa) | XML2JSON modunda xmlToJsonUnwrapElement, xmlToJsonIgnoreNull, xmlToJsonIgnoreEmpty, xmlToJsonNumbersAsStrings, xmlToJsonUseNullForNil bayraklarını ihtiyaca göre işaretleyin. xmlToJsonArrayPathList alanına JSON dizisine dönüşmesi gereken XPath ifadelerini ekleyin. |
| 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 XSLT veya XML→JSON 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 |
|---|---|
| Dinamik XSLT Dağıtımı | - Geliştirilen XSLT şablonunu editörde güncelleyin. - Kaydetmeden önce test panelinde örnek XML ile doğrulayın. - Deploy ederek tüm bağlı API Proxy (API Vekil Sunucusu) uçlarına dağıtın. |
| JSON Çıktı Şekillendirme | - XML2JSON modu aktifken gerekli bayrakları işaretleyin. - xmlToJsonArrayPathList ile dizilere dönüşecek XPath’leri tanımlayın.- View ekranında seçeneklerin doğru uygulandığını teyit edin. |
| Global-Local Senkronizasyonu | - Global politikayı localize ederek API bazlı kopya oluşturun. - Local kopyada paket bazlı değişiklikleri uygulayın. - Gerektiğinde global politikaya geri dönmek için Export/Import kullanın. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| XSLT Yönetimi | Kötü: Üretim XSLT’sini doğrudan kopyalamak. İyi: Değişiklikleri test politikası üzerinde denemek. En İyi: Versiyon kontrolünde saklayıp import/export ile dağıtmak. |
| JSON Yapılandırmaları | Kötü: Tüm bayrakları varsayılan bırakmak. İyi: Gereksiz null değerlerini ignore etmek. En İyi: İstemci ihtiyaçlarını dokümante edip array path listesini düzenli gözden geçirmek. |
| Koşul Tasarımı | Kötü: Koşul tanımlamadan tüm trafiğe uygulamak. İyi: Ortam bazlı ayrım yapmak. En İyi: Endpoint + Header kombinasyonlarıyla minimum kapsamlı koşul tanımları kullanmak. |
| Hata Mesajları | Kötü: Varsayılan mesajı değiştirmemek. İyi: İstemciye anlaşılır mesaj vermek. En İyi: Standardize edilmiş hata kodları ile destek ekiplerini bilgilendirmek. |
| Deploy Süreçleri | Kötü: Direkt canlıya yayınlamak. İyi: Test ortamında import edip doğrulamak. En İyi: Policy Group’lar üzerinden toplu deploy planı oluşturmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| İçerik Doğrulama | Hatalı XSLT, hassas verilerin sızmasına neden olabilir. Kaydetmeden önce test edin. |
| Yetkilendirme | Edit ve deploy işlemleri için rol bazlı yetkilendirme uygulayın, izinsiz değişiklikleri önleyin. |
| Hata Mesajı Sanitizasyonu | Üretimde hata mesajlarında sistem iç detaylarını paylaşmayın, genel açıklamalar kullanın. |
| Export/Import Güvenliği | ZIP dosyalarını sadece güvenilir depolarda saklayın, paylaşımdan önce şifreleyin. |
| Sürüm Yönetimi | XSLT değişikliklerinde eski sürümlere geri dönmek için export arşivlerini koruyun, bütünlüğü doğrulayın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Kontrolsüz XSLT | Neden kaçınılmalı: Performans ve güvenlik riskleri oluşturur. Alternatif: Test aracında limitler ve validasyonlar uygulayın. |
| Genel Koşullar | Neden kaçınılmalı: Gereksiz tüm trafik dönüşür, gecikme yaşanır. Alternatif: Query Builder ile hedeflenmiş koşullar tanımlayın. |
| Dokümansız Ayarlar | Neden kaçınılmalı: JSON bayraklarının etkisi izlenemez. Alternatif: Yapılan her değişikliği politika açıklamasına not edin. |
| Kontrolsüz Export Paylaşımı | Neden kaçınılmalı: Yetkisiz kişiler politikayı kopyalayabilir. Alternatif: Paylaşım öncesi şifreli kanal ve erişim kayıtları kullanın. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| XSLT Karmaşıklığı | Öneri: Şablonları modüler hale getirin. Etki: Dönüşüm süresi azalır. |
| Koşul Filtreleri | Öneri: Dönüşümü sadece gerekli endpoint’lerle sınırlayın. Etki: Gateway CPU kullanımı düşer. |
| XML Boyutu | Öneri: Büyük XML’lerde streaming destekli XSLT kuralları yazın. Etki: Bellek tüketimi dengeye gelir. |
| JSON Bayrakları | Öneri: Gereksiz bayrakları kapatın. Etki: Dönüşüm sonrası payload boyutu kontrol altında kalır. |
| Array Path Optimizasyonu | Öneri: XPath ifadelerini minimal tutun. Etki: XML→JSON dönüşüm süresi kısalır. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | XML2XML ve XML2JSON modları arasında hızlıca geçiş yapabilir miyim? | Dönüşüm tipi editör üzerinden tek tıklamayla değiştirilebilir, kaydettiğinizde yeni mod anında geçerli olur. |
| Genel | Politikayı birden çok API Proxy (API Vekil Sunucusu) ile nasıl paylaşırım? | Politikayı global olarak yapılandırıp Policy Group üzerinden ilgili API Proxy’lere atayabilirsiniz. |
| Teknik | XSLT kaydederken doğrulama hatası alırsam ne yapmalıyım? | Editördeki hata mesajını inceleyin, Test Transformation penceresinde örnek XML ile hatayı tekrarlayıp düzelttikten sonra yeniden kaydedin. |
| Teknik | XML2JSON dönüşümünde sayılar string’e dönüştürülmezse ne olur? | Varsayılan olarak sayılar JSON’da numeric kalır; istemci string bekliyorsa xmlToJsonNumbersAsStrings bayrağını açmalısınız. |
| Kullanım | Dönüşüm koşullarını nasıl sınırlayabilirim? | Condition sekmesinde header, path veya method tabanlı kural oluşturabilirsiniz; koşul sağlanmadığında dönüşüm çalışmaz. |
| Kullanım | Politika export dosyasıyla başka projeye aktarımda nelere dikkat etmeliyim? | ZIP formatını bozmadan import edin, isim çakışması varsa system uyarır; gerekirse yeni isimle içe aktarın. |