XML Dönüştürme

XML isteklerini XSLT veya JSON formatına dönüştürerek API trafiğini standart hale getirebilirsiniz

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

​

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

1. İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. XML Dönüşüm Kuralları: Koşullar sağlanıyorsa seçilen transformationType için XSLT içeriği veya XML→JSON bayrakları yüklenir, gerekli doğrulamalar yapılır.
4. 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.
5. 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: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: 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 5: 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 6: 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 7: 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 8: 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 9: 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.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

​

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.