Genel Bakış
Amacı Nedir?
- İstek veya yanıt üzerindeki verileri aksiyon zinciriyle iş kurallarına göre dönüştürerek tutarlı hale getirmek.
- Farklı veri kaynaklarından gelen içerikleri normalize ederek API Proxy (API Vekil Sunucusu) akışında bütünlük sağlamak.
- Koşullara bağlı kural yürütme ile sadece belirli endpoint akışlarında iş mantığı uygulamak.
- Maskelenmesi veya çıkarılması gereken hassas alanları politika seviyesinde kontrol altında tutmak.
Ç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ü: İş Kuralı 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ı?
- Aksiyon Zinciri Çalıştırma: Aksiyon listesi sırasıyla değerlendirilir; her aksiyon seçilen veri tipine göre (numeric/string/temporal) operatörler uygular, gerekirse JWT claim çıkarır veya JSON/XML dönüşümü yapar.
- Karar Verme:
- Eşleşme Var: Tüm aksiyonlar uygulanır; isteğin payload’ı, header’ı veya değişkenleri güncellenir.
- Eşleşme Yok: Politika atlanır; istek mevcut haliyle akışta ilerler.
- 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
- Aksiyon Zinciri Yönetimi: Ekle, Değiştir, Sil, Durdur gibi aksiyon tipleriyle istekteki değişkenler üzerinde sıralı işlemler tanımlanır.
- Veri Tipi Bazlı Operatör Desteği: Numeric, String ve Temporal veri tipleri için farklı operatörler (ör. Alt Dize, Tarih Ekle, Çarpma) seçilebilir.
- Gelişmiş Dönüşüm Yeteneği: JSON↔XML dönüşümleri, XSLT/JOLT tabanlı manipülasyonlar ve URL encode/decode işlemleri aksiyon kapsamında yapılır.
- 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
- JWT Claim Çıkarma: JWT Header Claim Çıkarma ve JWT Body Claim Çıkarma operatörleri ile JWT içerikleri değişkenlere alınabilir.
- Değişken Yönetimi Entegrasyonu: Kaynak ve hedef olarak proje değişkenleri seçilebilir, ihtiyaç halinde diyalog ekranından güncellenebilir.
- Dönüşüm Profil Ayarları: JSON2XML/XML2JSON dönüşümlerinde null, boş ve array davranışları ince ayarla yönetilir.
- 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ç |
|---|---|---|---|
| JWT Claim Zenginleştirme | Kimlik doğrulaması sonrası kullanıcı rolü header’a taşınmak isteniyor. | Action List: sourceDataType=Metin, operator=JWT Body Claim Çıkarma, targetVar=X-User-Role. | Header’a role değeri eklenir, backend ek sorgu yapmaz. |
| Kredi Kartı Maskeleme | Loglara tam kart numarası düşüyor. | Action List: operator=Maskeleme, maskFrom=6, maskTo=12. | Kart numarası maskelenerek hassas veri korunur. |
| Tarih Normalizasyonu | Farklı formatlarda tarih alınan endpoint’ler var. | Action List: sourceDataType=Tarih/Zaman, operator=Tarih Ekle (0 gün), format=yyyy-MM-dd. | Tüm tarihler standart formata çevrilir. |
| XML → JSON Dönüşümü | Legacy servis XML döndürüyor, microservice JSON bekliyor. | Action List: operator=Dönüştür, transformationContentType=XML'den JSON'a, unwrapElement=true. | Yanıt JSON formatında yeniden yazılır |
| Değer Doğrulama ve Durdurma | Hatalı değerde isteğin devam etmemesi gerekiyor. | İlk aksiyon: şart kontrolü, ikinci aksiyon: actionType=Durdur, custom error message. | Kural ihlalinde akış durur ve özel hata döner. |
| Çoklu Değişken Birleştirme | Farklı header’lardan veri toplanıp yeni payload alanı oluşturulacak. | Action List: operator=Birleştir ile kaynak header değerleri toplanır, targetValSource=Değişken. | Yeni alan oluşturulur, downstream servis karmaşık işlem yapmaz. |
Politika Parametrelerini Yapılandırma
Bu bölümde yeni bir Business Rule politikası oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilirsiniz.Yeni İş Kuralı Politikası Oluşturma
| Eylem | Açıklama |
|---|---|
| Add | İstek/yanıta yeni değişken veya değer ekler. Injection Target (hedef değişken) zorunludur. |
| Modify | Mevcut bir değişkenin veya alanın değerini günceller (maskeleme, dönüşüm, JWT claim çıkarma vb.). |
| Delete | Belirtilen değişkeni veya alanı mesajdan kaldırır. |
| Stop | Akışı durdurur ve özel hata mesajı döndürür. |
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 → Business Rule 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_BusinessRule- 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: “Prod ortamında istek akışındaki değişkenleri iş kurallarına göre dönüştürür.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Aksiyon Zincirini Tanımlama | - Policy Definitions bölümünde Actions açılır menüsünden Add, Modify, Delete veya Stop seçin. - Açılan diyalogda Action Type, Source Data Type (Sayısal/Metin/Tarih-Zaman) ve operatörü (örn. Alt Dize, Tarih Ekle, JWT Body Claim Çıkarma) seçip parametrelerini doldurun. |
| Adım 4: Kaynak ve Hedef Seçimi (Varsa) | - Kaynak değer için Source Variable veya literal değer girin. - Hedefte Target Variable ya da Target Value kullanın. - Variable diyaloglarını açarak proje değişkenlerini oluşturup bağlayın. İş Kuralı aksiyon tipi eklerken değişken tipi seçimi ve oluşturma akışı kullanıcı deneyimi iyileştirmesi ile daha net ve akıcı hale getirilmiştir. |
| Adım 5: 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 6: Hata Mesajı Özelleştirme (İsteğe Bağlı) | - Error Message Customization sekmesine gidin. - Erişim reddedildiğinde veya Durdur aksiyonunda dönecek mesajı özelleştirin. - Şablon tabanlı (dinamik) hata mesajı kullanarak #{error.errorCode}, #{request.uri}, #{dateTime.formattedText}, #{message.correlationId} gibi yer tutucılarla istek ve hata bilgilerini mesaja dahil edebilirsiniz. Detay için Politika Nedir? – Şablon Tabanlı Hata Mesajları bölümüne bakın.Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" }Özel (şablon örneği): Hata Kodu: #{error.errorCode}, Zaman: #{dateTime.formattedText}, İstek ID: #{message.correlationId} |
| Adım 7: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: - Benzersiz isim - Zorunlu alanlar dolu - En az bir aksiyon 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 Kullanım Adımları |
|---|---|
| JWT Claim Çıkarma Zinciri | - Action Type olarak Değiştir seçin. - Source Data Type = Metin, Operator = JWT Body Claim Çıkarma belirleyin. - claimJsonPath alanına istenen claim’i girin, target variable seçin ve kaydedin. |
| XML2JSON Dönüşüm Profili | - Dönüştür operatörünü seçin ve transformationContentType=XML'den JSON'a yapın.- xmlToJsonIgnoreNull ve xmlToJsonIgnoreEmpty seçeneklerini ihtiyaca göre işaretleyin.- Sonuç JSON’un hedef değişkene aktarılacağını doğrulayın. |
| Koşullu Durdur Aksiyonu | - Query Builder’da istenen kural koşulunu tanımlayın. - Action List’e Durdur tipinde aksiyon ekleyin ve özel hata mesajı seçin. - Önceki aksiyonların koşulu sağladığında Durdur aksiyonunun devreye girdiğini test edin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Aksiyon Zinciri Tasarımı | Kötü: Tüm iş kurallarını tek aksiyonda toplamak. İyi: Her kuralı ayrı aksiyon olarak tanımlamak. En İyi: Mantıksal olarak gruplanmış aksiyonları sıraya koyup gerekirse Durdur aksiyonu ile bölmek. |
| Değişken Yönetimi | Kötü: Literal değerlerle çalışıp değişken kullanmamak. İyi: Ortak değerleri proje değişkenlerinden okumak. En İyi: Değişken diyaloğuyla versiyonlanan değişkenler oluşturup hedefleri standardize etmek. |
| Hata Mesajı Yapısı | Kötü: Genel hata mesajı bırakmak. İyi: Kullanıcıya yönlendirici mesaj yazmak. En İyi: Hata mesajını kod, mesaj ve debug-friendly context ile özelleştirmek. |
| Koşul Yönetimi | Kötü: Koşulları boş bırakarak her istekte politika çalıştırmak. İyi: Endpoint veya header bazlı filtrelemek. En İyi: Environment, kullanıcı segmenti ve metod bilgilerini kombine ederek Query Builder kullanmak. |
| Ortamlar Arası Taşıma | Kötü: Canlı Ortamda direkt düzenleme yapmak. İyi: Test ortamında düzenleyip export etmek. En İyi: ZIP export-import ile sürüm kontrolü yapıp değişiklikleri pipeline üzerinden deploy etmek. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| JWT Claim Yönetimi | Claim çıkarırken sadece ihtiyaç duyulan alanları alın, yetkili olmayan bilgileri maskeleyin. |
| Veri Maskeleme | Kişisel verileri Maskeleme veya Alt Dize ile kısaltın, loglara hassas veri düşmesini engelleyin. |
| Hata Mesajı Kontrolü | Üretimde hata mesajlarına iç sistem detaylarını koymayın. Genel ama yönlendirici mesaj yazın. |
| Global Politika Güncellemeleri | Global politikayı güncellemeden önce kullanım listesini inceleyin, gerekiyorsa localize edin. |
| Değişken Yetkilendirmesi | Target variable olarak sadece yetkili kullanıcıların eriştiği değişkenleri seçin, izinleri kontrol edin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Boş Aksiyon Listesi | Neden kaçınılmalı: Politika kaydedilse bile hiçbir işlem yapılmaz, beklenen iş akışı bozulur. Alternatif: En az bir aksiyon tanımlayıp doğrulama ikonunu kontrol edin. |
| Yanlış Veri Tipi Seçimi | Neden kaçınılmalı: Operatör hata verir veya beklenmedik sonuç doğar. Alternatif: Kaynak veriyi analiz edin, Sayısal/Metin/Tarih-Zaman tipini doğru seçin. |
| Kontrolsüz Durdur Kullanımı | Neden kaçınılmalı: Tüm istekler yanlışlıkla durdurulabilir, servis kesintisi yaşanır. Alternatif: Durdur aksiyonunu sadece koşul filtresi sonrası uygulayın. |
| Global Politikayı Direkt Silme | Neden kaçınılmalı: Birden fazla API korumasız kalabilir. Alternatif: Önce deactivate edin veya local politika ile değiştirip sonra silin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Aksiyon Sırası | Öneri: Sık kullanılan ve hafif aksiyonları başa alın. Etki: Gereksiz ağır işlemlerden önce akış sonlandırılabilir. |
| Dönüşüm Operatörleri | Öneri: Dönüştür operasyonlarını minimal kullanın, gerekiyorsa ayrı politika açın. Etki: CPU yükü azalır, gecikme düşer. |
| Koşul Filtreleri | Öneri: Query Builder ile dar kapsamlı koşullar yazın. Etki: Politika sadece gerektiğinde çalışır, throughput artar. |
| Değişken Paylaşımı | Öneri: Sık kullanılan değerleri proje değişkenlerine alın. Etki: Aksiyon içinde tekrar tekrar literal işlem yapılmaz. |
| JWT İşlemleri | Öneri: JWT claim çıkarmayı sadece ihtiyaç duyulan isteklerle sınırlayın. Etki: Gereksiz parsing maliyeti düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Bu politika hangi tip veriler üzerinde çalışır? | Sayısal, Metin ve Tarih/Zaman veri türleriyle çalışır; operatör seçimi veri tipine göre otomatik filtrelenir. |
| Genel | Global mi local mi oluşturmalıyım? | Birden fazla API Proxy’de aynı kural gerekiyorsa global, tek API için özelse local önerilir. |
| Teknik | Durdur aksiyonu ne yapar? | Aksiyon zinciri bu noktada durur, özelleştirilmiş hata mesajı döndürülür ve akış sonlanır. |
| Teknik | JWT claim çıkarırken hedef değer nasıl setlenir? | Operatör otomatik olarak target value kaynağını Değişken yapar; bir proje değişkeni seçmeniz gerekir. |
| Kullanım | Action List boş ise neden uyarı alıyorum? | Politikanın çalışması için en az bir aksiyon zorunludur; uyarı ikonu bunu bildirir. |
| Kullanım | XML’den JSON’a dönüşümünde array alanlarını nasıl kontrol ederim? | xmlToJsonArrayPathList alanına dizi olması gereken XPath’leri girerek dönüşümde doğru tip elde edersiniz. |