Genel Bakış
Amacı Nedir?
- Script Politikası, API Proxy (API Vekil Sunucusu) istek hattında özel iş kuralları ve veri dönüşümleri uygulayarak entegrasyon gereksinimlerini kod yazmadan çözmeyi hedefler.
- Script Politikası, yanıt hattında gelen verileri maskeleme, zenginleştirme veya hata mesajlarını uyarlama gibi işlemleri merkezi olarak yönetmeyi sağlar.
- Script Politikası, farklı ortamlar arasında tutarlı davranış için global/local paylaşımlı script kütüphanesi oluşturmayı mümkün kılar.
- Script Politikası, koşul motoru sayesinde yalnızca belirlenen endpoint veya header kombinasyonlarında devreye girerek performansı korur.
Ç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ü: Script Politikası 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ı?
- Script Motoru Yürütmesi: Seçilen executionType (SYNC/ASYNC) ve scriptLanguage (Groovy/Javascript) değerlerine göre script, belirlenen pipeline bölgesinde çalıştırılır; istek/yanıt body, header ve parametre haritaları güncellenebilir.
- Karar Verme:
- Eşleşme Var: Script sonucunda güncellenen mesaj bileşenleri pipeline’a geri yazılır, hata durumunda tanımlı statusCode ve mesaj döner.
- Eşleşme Yok: Script atlanır, istek/yanıt varsayılan akışına devam eder.
- 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
- ExecutionType Yönetimi (Sync/Async): Scriptin eşzamanlı mı yoksa arka planda mı yürütüleceğini belirler; asenkron mod uzun süren işlemlerde uç noktayı bloklamaz.
- Çift Script Dili Desteği: Groovy ve Javascript arasında seçim yaparak ekiplerin hâkim oldukları dili kullanmalarını sağlar.
- Bağlam Değişkeni Kütüphanesi: From Client, To Backend, From Backend ve To Client akışları için hazır değişken haritaları sunar; okunabilir/yazılabilir alanlar net olarak ayrılmıştı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
- Script Test Laboratuvarı: Entegre test penceresiyle farklı pipeline segmentleri için örnek header/param/body verileriyle script çalıştırma ve sonucu inceleme.
- Bağımlılık İzleme: Used Proxies/Policy Groups bölümleriyle politikanın hangi API Proxy veya gruplarda kullanıldığını görüp değişiklik etki analizi yapma.
- Dinamik Context Value Seçimi: EnumScriptContextValue üzerinden tarih, ortam veya proxy metadata bilgilerini script içerisinde kullanmak için otomatik kopyalama.
- 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ç |
|---|---|---|---|
| İstek Başlığı Enjeksiyonu | Dış sistem ek header talep ediyor | From Client → To Backend scriptinde requestHeaderMapToTargetAPI['X-Partner-Code']='ACME' yazılır. | Backend çağrısı gereken header ile yapılır. |
| Hassas Alan Maskesi | Yanıtta TC kimlik numarası bulunuyor | To Client scriptinde regex ile hassas alan **** ile değiştirilir. | İstemciye maskelemiş veri döner. |
| Dinamik Endpoint Yönlendirme | Bazı müşteriler farklı backend URL’sine yönlendirilmeli | Script customizedBackendResourceUrl alanını koşula göre set eder. | İstek uygun hedef servise yönlenir. |
| Koşullu Hata Dönüşü | Belirli API anahtarlarında erişim durdurulmalı | Script responseErrorMessageToClient ve statusCodeToClient=403 atar. | İstemci 403 ve özelleştirilmiş mesaj alır. |
| JWT Enrichment | JWT claim değerine dayalı context üretmek gerekiyor | Script claim’i okuyup customVariableMap['roleLevel']=... yazar. | Sonraki politikalar enriched değeri kullanır. |
| Header Bazlı Rate Flag | Belirli kaynağa doğru gelen başlıklarda throttling tetiklenmeli | Script header’ı analiz edip requestHeaderMapToTargetAPI['X-Throttle']='true' ekler. | Throttling politikaları bayrağı okuyarak hız kısıtlar. |
| Gelişmiş Loglama (opsiyonel) | Denetim amaçlı request/response logu hazırlamak gerekiyor | Script customVariableMap['auditPayload']=JSON.stringify(...) yazar. | Log alma politikası veriyi kullanır. |
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 Script 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 → Script 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_ScriptPolicy- 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: “İstek hattında kampanya header’ı ekler.” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: ExecutionType Seçimi | - Execution Type bölümünde Sync veya Async seçin.- Sync seçildiğinde script gateway pipeline’ında eşzamanlı yürür.- Async, uzun süren operasyonlarda istemciyi bekletmemek için uygun olup yan kanal tetikler. |
| Adım 4: Script Dili Yapılandırması | - Script Language altında Javascript veya Groovy seçin.- Seçim kod editörünün sözdizimini ve IntelliSense’i belirler. - Dili değiştirmek, mevcut script gövdesini etkilemez ancak çalıştırma modunu günceller. |
| Adım 5: Script Gövdesi ve Değişken Yönetimi | - Kod editörüne scriptinizi yazın veya yapıştırın. - Değişken etiketlerinden requestHeaderMapToTargetAPI, responseBodyTextToClient gibi alanları bir tıklamayla panoya kopyalayın.- customVariableMap üzerinden diğer politikalara veri aktarabilirsiniz.- Try It butonu ile test diyaloğunu açıp örnek girişlerle scripti çalıştırı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 script gövdesi satırı 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 |
|---|---|
| Script Test Diyaloğu | - Try It butonu ile açılır.- Request/Response region seçilerek örnek veri girilir. - Çalıştırma sonucu JSON olarak incelenip script iyileştirilir. |
| Context Value Kütüphanesi | - Context Values select bileşeninden kategori seçilir.- Seçim yapıldığında değer panoya kopyalanır. - Script içinde doğrudan kullanılarak ortam bilgisi alınır. |
| WebSocket/gRPC Uyarlaması | - Proxy türü WebSocket/gRPC ise değişken listeleri otomatik daraltılır. - Uygun mesaj akışı değişkenleri sunulur. - Script bu protokollerde hataları yönetebilir. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Script Yapılandırması | Kötü: Tüm mantığı tek fonksiyonda yazmak. İyi: Mantığı fonksiyonlara bölmek. En İyi: Ortak fonksiyonları paylaşılan modüllerde tutup scripti sade bırakmak. |
| Hata Yönetimi | Kötü: Hataları yutmak ve varsayılan 500 beklemek. İyi: Hata durumunda responseErrorMessageToClient set etmek.En İyi: Hem mesajı hem statusCodeToClient değerini iş senaryosuna göre ayarlamak. |
| Versiyonlama | Kötü: Scripti doğrudan prod ortamında değiştirmek. İyi: Değişiklik öncesi export almak. En İyi: Test ortamında yeni sürümü import edip deploy ettikten sonra canlıya taşımak. |
| Koşul Kullanımı | Kötü: Politikanın her istekte çalışmasına izin vermek. İyi: Temel path koşulu eklemek. En İyi: Header, yöntem ve ortam kombinasyonlarıyla koşulları spesifikleştirmek. |
| Performans İzleme | Kötü: Async scriptlerin tamamlanma süresini takip etmemek. İyi: Loglarda script sürelerini izlemek. En İyi: Gecikme artarsa scripti profil edip optimize etmek, gerekiyorsa cache kullanmak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Veri Maskeleme | Kişisel verileri yanıtta maskeleyin, scriptte regex doğrulaması yapın. |
| Girdi Doğrulama | Script içine alınan parametrelerde beklenen formatı kontrol edin, hatalıysa hata kodu döndürün. |
| Exception Yönetimi | Try/catch bloklarıyla beklenmeyen hataları yakalayın, loglayın, kullanıcıya sınırlı bilgi verin. |
| Harici Çağrılar | Script içinde dış sistem çağrısı yapacaksanız zaman aşımı ve retry sınırı koyun; async mod tercih edin. |
| Yetki Mantığı | Header veya JWT claim kontrollerini scriptte merkezi hale getirerek yetkisiz erişimi engelleyin. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Uzun Süreli İşlemler | Neden kaçınılmalı: Sync modda gateway thread’lerini bloklar. Alternatif: Async moda geçin veya arka plan servisine delegasyon yapın. |
| Hard-coded URL | Neden kaçınılmalı: Ortam değiştiğinde script kırılır. Alternatif: Context value veya environment değişkenlerini kullanın. |
| Global Scriptte Test Edilmemiş Kod | Neden kaçınılmalı: Tüm API Proxy trafiğini etkiler. Alternatif: Önce local script olarak test edin, sonra globalleştirin. |
| Hata Mesajını Boş Bırakma | Neden kaçınılmalı: İstemci belirsiz hata alır. Alternatif: Error Message Customization bölümünde açıklayıcı mesaj set edin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Script Kompleksliği | Öneri: Döngü ve parsing işlemlerini minimal tutun. Etki: Gateway gecikmesi azalır. |
| Veri Yapıları | Öneri: Büyük JSON dönüşümleri için hazır kütüphaneler yerine hafif map kullanın. Etki: Bellek kullanımını düşürür. |
| Koşul Motoru | Öneri: Gerekmediğinde koşul tanımlamayın; tanımlarsanız spesifik tutun. Etki: Politika değerlendirme süresi optimize olur. |
| Async Kullanımı | Öneri: Ağ çağrısı veya uzun IO içeren scriptlerde Async seçin. Etki: İstemci bekleme süresini azaltır, throughput artar. |
| Test ve İzleme | Öneri: Script Test modülünde süre metriğini takip edin, limit üstü durumları loglayın. Etki: Performans gerilemeleri erken tespit edilir. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Script Politikası ne zaman kullanılmalı? | Kural motoru veya hazır politikaların kapsamadığı veri dönüştürme ve iş mantığı ihtiyaçlarını gateway seviyesinde çözmek istediğinizde kullanmalısınız. |
| Genel | Groovy ile Javascript arasında nasıl karar vermeliyim? | Ekip uzmanlığına, mevcut kütüphanelere ve scriptin yapılacağı işlemlere göre seçim yapın; Java ekosistemine yakınsanız Groovy, frontend ekibi ile ortak çalışacaksanız Javascript seçebilirsiniz. |
| Teknik | Async modda script tamamlanmazsa ne olur? | Async süreç tamamlanana kadar default yanıt döner; sonuçlar loglarda izlenir, gerektiğinde retry mekanizması eklenebilir. |
| Teknik | Context Value nasıl çalışır? | EnumScriptContextValue değerleri seçildiğinde ilgili ortam/metadata bilgisi panoya kopyalanır; script içinde string olarak kullanarak runtime verilerine erişebilirsiniz. |
| Kullanım | Script test ekranı gerçek trafiği etkiler mi? | Hayır, test ekranı izole çalışır; girilen örnek veriler üzerinde scripti simüle eder. |
| Kullanım | Script politikası birden fazla API Proxy’de paylaşılabilir mi? | Global olarak oluşturulduğunda tüm API Proxy’lerde kullanılabilir; local kopyalar proxy bazında özelleştirme sunar. |