Script

ipucu

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?

• 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

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. Politika Kontrolü: Script 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. 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.
4. 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.
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

• 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ı: Dene düğmesiyle Script'i Test Etme penceresini açma. Seçtiğiniz hat için script'i örnek verilerle çalıştırma. Pencere script'in neyi değiştirdiğini gösterir. Test, backend'i çağırmaz.
• Editör Desteği: Değişkenler bandı, kod tamamlama, editör kontrolleri, derleme kontrolü ve yan panel ile script yazmayı hızlandırma.
• 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: Bağlam kutusundan tarih, ortam veya proxy metadata değerlerini arayıp seçme. Seçilen değer panoya kopyalanır; düğmeyle imlece eklenir.
• 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 ile header eklenir	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 maskelenir	İstemciye maskelenmiş veri döner
Dinamik Endpoint Yönlendirme	Bazı müşteriler farklı backend URL'sine yönlendirilmeli	Script requestBackendUrlToTargetAPI 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'e yazar	Sonraki politikalar enriched değeri 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.

Yeni Script Politikası Oluşturma

Yapılandırma Adımları

Adım 1: Oluşturma Sayfasına Gitme

Sol menüden Development → Global Settings → Global Policies → Script Politikası bölümüne gidin ve 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: Benzersiz isim girin (örnek: Production_ScriptPolicy). Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir, Kırmızı çarpı: mevcut isim.

Description (Açıklama): Politikanın amacını açıklayın (Maks. 1000 karakter). Örnek: "İstek hattında kampanya header'ı ekler."

Adım 3: Variable Kullanımı

• Sayfanın üst kısmındaki işlem butonları alanında [<> Değişken] düğmesine tıklayın ve dinamik değer seçin. Menüde iki seçenek vardır: Global Variable ve Context Variable.
• Global Variable seçeneği Ortam Değişkeni Seç penceresini açar. Bir değişken seçin; pencere değişkeni kopyalar. Script politikası ekranında pencere değişkeni environmentVariableMap.get("ad") biçiminde kopyalar. Bu ifadeyi script'e yapıştırın.
• Groovy'de metin içindeki ${ad}, Groovy'nin kendi metin yerleştirmesidir. İfade script değişkenini okur; ortam değişkenini okumaz. Bunun yerine environmentVariableMap.get("ad") kullanın.
• Script, #{...} bağlam değişkenlerini çözmez. Context Variable seçeneği #{...} ifadelerini listeler. Script içinde bağlam değeri okumak için editörün üstündeki Bağlam kutusunu kullanın. Ayrıntılar için Adım 6'ya bakın.
• Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.

Adım 4: 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 5: Script Dili Yapılandırması

uyarı

Java sınıfları yalnızca Groovy'de kullanılabilir. Worker'daki JavaScript script'leri Java sınıfı yükleyemez. Java.type kullanılamaz; çalışma zamanında ReferenceError hatası oluşur. Editör, JavaScript script'inde Java.type görürse sizi uyarır. Sınıflar sekmesi ve sınıf tamamlama yalnızca Groovy'de açıktır. Java sınıfı gerekiyorsa Groovy seçin.

Script Language altında Javascript veya Groovy seçin.

Seçim şunları belirler:

• Kod editörünün dili
• Kod tamamlama önerileri
• Editör kontrolleri
• Kontrol et ve Dene düğmelerinin kullandığı motor

Motorlar, Worker'daki çalışma motorlarıdır: Groovy 3.0.25 ve GraalJS üzerinde JavaScript.

Adım 6: Script Gövdesi ve Değişken Yönetimi

Kod editörüne script'inizi yazın veya yapıştırın. Editörün üstündeki bant ve araç çubuğu ile yandaki panel yazmayı hızlandırır.

Değişkenler bandı

Değişkenler bandı editörün üstünde yer alır. Bant, değişkenleri veri akışının yönüne göre dört şeritte gösterir:

Şerit	Erişim
İstemci → Gateway	okunur
Gateway → Backend	istekte yazılır
Backend → Gateway	yanıtta okunur
Gateway → İstemci	yanıtta yazılır

Ortak satırı şu değişkenleri içerir: customVariableMap, environmentVariableMap, credentialMap, cache, stopFlowAsSuccess ve flowResultType.

Her değişken bir çip olarak görünür:

• Çipe tıklayın. Çip, değişkenin adını panoya kopyalar ve Kopyalandı ! mesajı görünür.
• Çipin ▾ okuna tıklayın. Menü, İmlece ekle seçeneğini ve hazır kod işlemlerini sunar. Örnekler: Değer oku, Değer yaz, Anahtar var mı kontrol et, Anahtarı sil, Tümünü dolaş.
• Menüdeki Adını kopyala seçeneği, adı panoya kopyalar.

Çiplerin görünümü şu anlamlara gelir:

• Mavi kenarlık: Değişken yazılabilir.
• Kesikli kenarlık: Değişken ekranda yeni.
• Soluk görünüm: Değişken bu hatta boş.

Gizle düğmesi bandı daraltır. Göster düğmesi bandı yeniden açar.

Bant, Bağlam kutusunu da içerir:

• Kutuya yazın. Kutu, bağlam değerlerini etikete veya ada göre arar.
• Listeden bir değer seçin. Seçilen değer panoya kopyalanır.
• Kutunun yanındaki İmlece ekle düğmesine tıklayın. Düğme, değeri imlecin olduğu yere ekler.
• Tümünde ara düğmesine tıklayın. Yan panelin Değişkenler sekmesi açılır.

Araç çubuğu

Araç çubuğu şu öğeleri içerir:

• Motor etiketi: Groovy 3.0.25 veya JavaScript (GraalJS). Etiket, seçili dilin çalışma motorunu gösterir.
• Öner: Kod tamamlama listesini açar. Kısayollar: Ctrl+Space, Alt+Space ve Ctrl+.
• Kontrol et: Script'i Worker'da çalışma motoruyla derler. Hiçbir şey çalıştırılmaz.
• Dene: Script'i Test Etme penceresini açar. Pencere hiçbir şeyi kaydetmez ve backend'i çağırmaz. Ayrıntılar için bu sayfadaki İleri Düzey Özellikler tablosuna bakın.
• Katalog ve sınıflar ve Paneli gizle: Yan paneli açar ve kapatır.

Kod tamamlama

Kod tamamlama listesi şu önerileri sunar:

• Değişkenler (en çok kullanılandan başlayarak)
• Bağlam değerleri
• Bilinen tiplerin üyeleri
• Başlık haritasında get veya put çağrısından sonra, tırnak içinde başlık adları
• environmentVariableMap.get(" ifadesinden sonra ortam değişkeni adları
• credentialMap.get(" ifadesinden sonra credential adları
• customVariableMap.put ile daha önce yazdığınız anahtarlar
• Groovy sınıfları (import satırı otomatik eklenir)
• Katalogdaki kod parçacıkları

Sorun çubuğu ve editör kontrolleri

Editörün altındaki çubuk Sorun yok, N hata veya N uyarı yazar. Her sorun satırı konumu Satır L:C biçiminde gösterir. Bir satıra tıklayın; imleç o satıra gider.

Editör, yazarken şu durumlar için uyarı verir:

• Salt-okunur bir değişkene değer atama.
• Bu hatta boş olan veya etkisi olmayan bir değişkenin kullanımı.
• println ve console.log çağrıları. Bu çağrılar Worker konsoluna yazar; trafik kaydına yazmaz.
• Groovy'de "${name}" ifadesi. Bu ifade, script içinde ortam değişkenini çözmez. Hızlı düzeltme, ifadeyi environmentVariableMap.get("name") ile değiştirir.
• flowResultType değişkenine SUCCESS, BLOCKED veya ERROR dışında bir değer atanması.
• Tek başına stopFlowAsSuccess kullanımı. Bu değişken akışı kesmez. requestErrorMessageToTargetAPI veya responseErrorMessageToClient değişkenini de doldurun.
• Bilinen bir değişkene benzeyen bilinmeyen değişken. Editör bir düzeltme önerir.
• JavaScript script'inde Java.type kullanımı.

JavaScript sözdizimi hataları, yazarken görünür. Groovy derleme hataları Kontrol et düğmesinden sonra görünür; satır ve sütun bilgisiyle gösterilir.

Kontrol et düğmesi, projenin yayınlanmış bir ortamını gerektirir. Eski bir Worker sürümünde veya yayınlanmış ortam yoksa yalnızca editör kontrolleri çalışır. Kontrol, [Save] düğmesini hiçbir zaman engellemez. Durum satırı şu mesajlardan birini gösterir:

• Hatasız derlendi (N ms).
• Derleme hatası var.
• Son kontrolden sonra kod değişti.
• Derleme kontrolü için yayınlanmış ortam gerekir. Yalnız editör kontrolleri çalıştı.
• Derleme kontrolü şu an yapılamıyor. Yalnız editör kontrolleri çalıştı.

Yan panel

Katalog ve sınıflar düğmesi yan paneli açar. Panelde üç sekme vardır:

• Değişkenler: Değişken arayın. Bir satıra tıklayın; ad panoya kopyalanır. ⋮ menüsü, imlece ekleme ve hazır kod işlemlerini sunar.
• Katalog: Seçili hat için hazır kodları listeler. İmlece ekle düğmesi kodu imlece ekler. Kopyala düğmesi kodu panoya kopyalar. Import satırları dosyanın başına eklenir. Bazı kayıtlar yalnızca Groovy'de görünür.
• Sınıflar: Yalnızca Groovy'de açıktır. Sınıf arayın. Bir sınıf eklediğinizde import satırı da eklenir. Statik bir üyeye tıklayın; üye imlece eklenir.

customVariableMap üzerinden diğer politikalara veri aktarabilirsiniz.

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 olur.

Detaylar için bakabilirsiniz: Koşullar (Conditions)

Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)

Error Message Customization sekmesine gidin ve 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.

Kaydetme işlemi script'i de kontrol eder. Script hata içeriyorsa Script hata içeriyor penceresi açılır. Script'i olduğu gibi kaydetmek için Yine de kaydet düğmesine tıklayın. Editöre dönmek için Geri dön düğmesine tıklayın. Kontrol, kaydetme işlemini hiçbir zaman engellemez.

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

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.

Flow Variables (Akış Değişkenleri)

Script Politikası içerisinde kullanabileceğiniz akış değişkenleri ve özellikleri aşağıdaki tablolarda detaylı olarak açıklanmıştır.

İstek Değişkenleri (Client → Apinizer)

Değişken Adı	Pipeline	Yön	Tip	Erişim	Açıklama	Örnek Kullanım
requestHeaderMapFromClient	İstek	Client → Apinizer	Map<String, String>	Okuma	İstemciden gelen istek Apinizer'a ulaştığı andaki orijinal halinin başlık(header) değerlerine erişmek için kullanılır.	String value= requestHeaderMapFromClient.get("Content-Type");
requestUrlParamMapFromClient	İstek	Client → Apinizer	Map<String, String>	Okuma	İstemciden gelen istek Apinizer'a ulaştığı andaki orijinal halinin sorgu(query) parametre değerlerine erişmek için kullanılır.	String value= requestUrlParamMapFromClient.get("param");
requestBodyTextFromClient	İstek	Client → Apinizer	String	Okuma	İstemciden gelen istek Apinizer'a ulaştığı andaki orijinal halinin gövde değerine erişmek için kullanılır.	String value= requestBodyTextFromClient;
requestUrlFromClient	İstek	Client → Apinizer	String	Okuma	İstemciden gelen isteğin karşılandığı endpoint yolunu içerir (örn. /pet/findByStatus). SOAP tipi API Proxy'lerde bu değişkenin değeri SOAP metodunun adıdır.	String value= requestUrlFromClient;
requestFormUrlEncodedListFromClient	İstek	Client → Apinizer	List<BasicNameValuePair>	Okuma	İstemciden gelen istek Apinizer'a ulaştığı andaki orijinal halinin "Form-URL-Encoded" parametrelerine erişmek için kullanılır.	Detaylı örnek için Form URL-Encoded Kullanımı bölümüne bakınız.
requestFormDataListFromClient	İstek	Client → Apinizer	List<ApinizerRequestBodyPart>	Okuma	İstemciden gelen istek Apinizer'a ulaştığı andaki orijinal halinin "Form-Data" parametrelerine erişmek için kullanılır.	Detaylı örnek için Form Data Kullanımı bölümüne bakınız.

İstek Değişkenleri (Apinizer → Backend API)

Değişken Adı	Pipeline	Yön	Tip	Erişim	Açıklama	Örnek Kullanım
requestHeaderMapToTargetAPI	İstek	Apinizer → Backend API	Map<String, String>	Okuma, Yazma	Apinizer'dan Backend API'ye giden isteğin başlık(header) değerlerine erişmek için kullanılır. Bu alandaki değerler istek hattındaki yapılan değişikleri içerir ve değerleri Apinizer'e gelen orijinal istekten farklılaşabilir.	String value= requestHeaderMapToTargetAPI.get("Content-Type"); requestHeaderMapToTargetAPI.put("Content-Type","application/json");
requestUrlParamMapToTargetAPI	İstek	Apinizer → Backend API	Map<String, String>	Okuma, Yazma	Apinizer'dan Backend API'ye giden isteğin sorgu(query) parametresindeki değerlerine erişmek için kullanılır. Bu alandaki değerler istek hattındaki yapılan değişikleri içerir ve değerleri Apinizer'e gelen orijinal istekten farklılaşabilir.	String value= requestUrlParamMapToTargetAPI.get("param"); requestHeaderMapToTargetAPI.put("param","value");
requestBodyTextToTargetAPI	İstek	Apinizer → Backend API	String	Okuma, Yazma	Apinizer'dan Backend API'ye giden isteğin gövde değerine erişmek için kullanılır. Bu alandaki değer istek hattındaki yapılan değişikleri içerir ve değeri Apinizer'e gelen orijinal istekten farklılaşabilir.	String value= requestBodyTextToTargetAPI; requestBodyTextToTargetAPI= "<body>";
requestFormUrlEncodedListToTargetAPI	İstek	Apinizer → Backend API	List<BasicNameValuePair>	Okuma, Yazma	Apinizer'dan Backend API'ye giden isteğin "Form-Url Encoded" parametrelerindeki değerlerine erişmek için kullanılır. Bu alandaki değerler istek hattındaki yapılan değişikleri içerir ve değerleri Apinizer'e gelen orijinal istekten farklılaşabilir.	Detaylı örnek için Form URL-Encoded Kullanımı bölümüne bakınız.
requestFormDataListToTargetAPI	İstek	Apinizer → Backend AP	List<ApinizerRequestBodyPart>	Okuma, Yazma	Apinizer'dan Backend API'ye giden isteğin "Form-Data" parametrelerindeki değerlerine erişmek için kullanılır. Bu alandaki değerler istek hattındaki yapılan değişikleri içerir ve değerleri Apinizer'e gelen orijinal istekten farklılaşabilir.	Detaylı örnek için Form Data Kullanımı bölümüne bakınız.
requestErrorMessageToTargetAPI	İstek	Apinizer → Backend API	String	Yazma	İstek hattında akış kesilerek istemciye mesaj dönülmek isteniyorsa, dönülecek olan mesaj bu değişkene girilir. Script'in işletilmesi sonucu bu mesajın dolu olması halinde akış kesilerek istemciye bu değer döndürülür.	requestErrorMessageToTargetAPI= "<body>";
statusCodeToTargetAPI	İstek	Apinizer → Backend API	Integer	Yazma	İstek hattında akış kesilerek istemciye mesaj dönülmek isteniyorsa, dönülecek olan durum kodu bu değişkene girilir. Tek başına bu değerin girilmesi akışın durdurulması için yeterli değildir, akışın durdurulması için requestErrorMessageToTargetAPI değerinin dolu olması gerekir.	statusCodeToTargetAPI=500;
requestBackendUrlToTargetAPI	İstek	Apinizer → Backend API	String	Yazma	Backend API URL'sinin bağlam yolu değiştirilmek istenirse bu alan kullanılabilir. Bu değişkenin varsayılan değeri boştur ve bu değişkene bir değer ayarlanırsa hedef bağlam yolu bu değerle değiştirilir. requestBackendUrlToTargetAPI değerinin boş olabilmesi için #EMPTY# değeri girilmelidir. Bu değer kullanıldığında, istek herhangi bir path veya query eklenmeden doğrudan routing adresine yönlendirilmesi sağlandı.	Detaylı örnekler için Backend URL Değiştirme bölümüne bakınız.

Yanıt Değişkenleri (Backend API → Apinizer)

Değişken Adı	Pipeline	Yön	Tip	Erişim	Açıklama	Örnek Kullanım
responseHeaderMapFromTargetAPI	Yanıt	Backend API → Apinizer	Map<String, String>	Okuma	Backend API'den dönen sonuç Apinizer'a ulaştığı andaki orijinal halinin başlık(header) değerlerine erişmek için kullanılır.	String value= responseHeaderMapFromTargetAPI.get("Content-Type");
responseBodyTextFromTargetAPI	Yanıt	Backend API → Apinizer	String	Okuma	Backend API'den dönen sonuç Apinizer'a ulaştığı andaki orijinal halinin gövde değerine erişmek için kullanılır.	String value= responseBodyTextFromTargetAPI;
statusCodeFromTargetAPI	Yanıt	Backend API → Apinizer	Integer	Okuma	Backend API'den dönen sonuç Apinizer'a ulaştığı andaki orijinal halinin durum kodu değerine erişmek için kullanılır.	int value=statusCodeFromTargetAPI;

Yanıt Değişkenleri (Apinizer → Client)

Değişken Adı	Pipeline	Yön	Tip	Erişim	Açıklama	Örnek Kullanım
responseHeaderMapToClient	Yanıt	Apinizer → Client	Map<String, String>	Okuma, Yazma	Apinizer'dan İstemciye dönen yanıtın başlık(header) değerlerine erişmek için kullanılır. Bu alandaki değerler yanıt hattındaki yapılan değişikleri içerir ve değerleri Apinizer'e dönen orijinal yanıttan farklılaşabilir.	String value= responseHeaderMapToClient.get("Content-Type"); responseHeaderMapToClient.put("Content-Type","application/json");
responseBodyTextToClient	Yanıt	Apinizer → Client	String	Okuma, Yazma	Apinizer'dan İstemciye dönen yanıtın gövde değerine erişmek için kullanılır. Bu alandaki değer yanıt hattındaki yapılan değişikleri içerir ve değeri Apinizer'e dönen orijinal yanıttan farklılaşabilir.	String value= responseBodyTextToClient; responseBodyTextToClient= "<body>";
responseErrorMessageToClient	Yanıt	Apinizer → Client	String	Okuma, Yazma	Yanıt hattında akış kesilerek istemciye mesaj dönülmek isteniyorsa, dönülecek olan mesaj bu değişkene girilir. Script'in işletilmesi sonucu bu mesajın dolu olması halinde akış kesilerek istemciye bu değer döndürülür.	responseErrorMessageToClient= "<body>";
statusCodeToClient	Yanıt	Apinizer → Client	Integer	Okuma, Yazma	Yanıt hattında akış kesilerek istemciye mesaj dönülmek isteniyorsa, dönülecek olan durum kodu bu değişkene girilir. Tek başına bu değerin girilmesi akışın durdurulması için yeterli değildir, akışın durdurulması için responseErrorMessageToClient değerinin dolu olması gerekir.	int value=statusCodeToClient; statusCodeToClient=401;
stopFlowAsSuccess	İstek / Yanıt	Script → Apinizer	boolean	Yazma	Akış kesilerek istemciye mesaj dönüldüğünde, sonucun başarılı olarak işaretlenmesini sağlar. Değeri true yapılırsa istek trafik loglarında resultType=SUCCESS olarak görünür, analitik raporlarda hata/bloke sayılmaz ve durum kodu yazılmadıysa HTTP 200 döner (varsayılan davranışta 401 dönerdi). Durum kodu istisnası: yanıt hattında arka uç servis 4xx/5xx döndürmüşse o durum kodu korunur, 200'e çevrilmez — yalnızca sonuç tipi SUCCESS olur. Arka ucun hata kodunu da maskelemek istiyorsanız statusCodeToClient değişkenine dönmek istediğiniz kodu açıkça yazın; script'in yazdığı durum kodu her zaman önceliklidir. Bu değişken tek başına akışı kesmez — akışın kesilmesi için yine responseErrorMessageToClient (yanıt hattı) veya requestErrorMessageToTargetAPI (istek hattı) değerinin dolu olması gerekir. Yazılmadığında davranış değişmez, sonuç BLOCKED olarak işaretlenir.	responseErrorMessageToClient= "{\"status\":\"ok\"}"; stopFlowAsSuccess= true;
flowResultType	İstek / Yanıt / Hata	Script ↔ Apinizer	String	Okuma, Yazma	İsteğin trafik logundaki sonuç tipini belirler: SUCCESS, BLOCKED veya ERROR. Bkz. Akış Sonuç Tipi.	flowResultType = "ERROR"

Akış Sonuç Tipi

flowResultType, trafik logunun istek için gösterdiği sonuç tipini belirler. Groovy ve JavaScript'te, istek, yanıt ve hata hatlarında çalışır.

• Değerler: SUCCESS, BLOCKED, ERROR. Büyük/küçük harf fark etmez. Apinizer boşlukları temizler. Başka bir değer yok sayılır ve hata verilmez.
• Başlangıç değeri: Mevcut istekte daha önce bir script'in yaptığı seçimdir. Hiçbir script seçim yapmadıysa null olur. Değişkeni okuyabilir ve yazabilirsiniz.
• Async script'ler: Async script sonucu değiştiremez.

Script akışı durdurursa

Script requestErrorMessageToTargetAPI veya responseErrorMessageToClient değişkenini de doldurursa akış bu sonuç tipiyle durur:

• SUCCESS için "kullanıcı akışı başarı olarak durdurdu" hata tipi kullanılır. Varsayılan HTTP durumu 200'dür (ERR-297).
• BLOCKED ve ERROR için "kullanıcı akışı durdurdu" hata tipi kullanılır. Varsayılan HTTP durumu 401'dir (ERR-057).
• Script statusCodeToClient veya statusCodeToTargetAPI değerini yazarsa bu durum kodu kullanılır.

flowResultType değişkenini yazan script, değişkeni yalnızca kendi durdurması için kullanır. Değişkeni yazmadan akışı durduran script eski kuralı korur: stopFlowAsSuccess = true ise SUCCESS, aksi halde BLOCKED.

Akış devam ederse

• İstek bu seçimi taşır. İstek başarıyla biterse trafik logu sonucu bu değer olur.
• Sonraki bir politika veya arka uç isteği hatayla bitirir ya da bloke ederse o hata sonucu kalır.
• Sonraki bir script değeri değiştirebilir. null veya boş değer seçimi temizler.

Aynı kural HTTP, gRPC ve WebSocket trafik loglarında geçerlidir. Script-2-API uç noktalarında ve Dene penceresinde de çalışır. Dene değeri Trafik logu sonucu olarak gösterir.

Örnek: akışı ERROR sonucuyla durdurma

requestErrorMessageToTargetAPI = '{"error":"invalid"}'
flowResultType = "ERROR"

Örnek: akışı sürdürüp çağrıyı loglarda ERROR olarak işaretleme

İstemci arka ucun yanıtını almaya devam eder.

flowResultType = "ERROR"

Detaylı Kullanım Örnekleri

Form URL-Encoded Kullanımı

import org.apache.http.message.BasicNameValuePair

String selectedValue;
for (BasicNameValuePair nameValuePair : requestFormUrlEncodedListFromClient) {
   if("test".equals(nameValuePair.getName())){
       selectedValue=nameValuePair.getValue();
   }
}

Form Data Kullanımı

import com.apinizer.common.global.apinizerrequest.*;

for (ApinizerRequestBodyPart bodyPart : requestFormDataListFromClient) {
    if(bodyPart.getBodyPartType().isText()){
        ApinizerRequestTextBody textBodyPart = ((ApinizerRequestTextBody)bodyPart));
        String text=textBodyPart.getText();
        //do some logic
    }else{//bodyPart.getBodyPartType().isBinary()
        ApinizerRequestBinaryBody binaryBodyPart = ((ApinizerRequestBinaryBody)bodyPart));
        byte[] byteArr=binaryBodyPart.getContent();
        String fileName=binaryBodyPart.getFileName();
        //do some logic
    }
}

Backend URL Değiştirme

Örnek Senaryo:

Mevcut routing adresi: "https://apinizer.com/api" olsun,

Gelen istek kapsam yolu: "/findByStatus?param=value" olsun.

Bu durumda istek şu adrese gider: "https://apinizer.com/api/findByStatus?param=value"

Aşağıdaki kod yazıldığında:

requestBackendUrlToTargetAPI="/new/path/value?p=v";

İstek şu adrese gider: "https://apinizer.com/api/new/path/value?p=v"

Aşağıdaki kod yazıldığında:

requestBackendUrlToTargetAPI="#EMPTY#"

İstek şu adrese gider: "https://apinizer.com/api"

Ortam Değişkenlerine Erişim

Script gövdesi içinde ${değişken} ifadesi çözülmez (Groovy'de GString olarak algılanır, JavaScript'te şablon değişmezi olarak yorumlanır). Ortam değişkenlerine script içinden erişmek için environmentVariableMap kullanılır.

String dbHost = environmentVariableMap.get("dbHost");
String apiKey = environmentVariableMap.get("apiKey");

if (environmentVariableMap.containsKey("featureFlag")) {
    // değişken tanımlı, kullan
}

not

Davranış:

• Map salt-okunurdur; put, remove, clear çağrıları UnsupportedOperationException fırlatır.
• Iteration desteklenir: keySet(), values(), entrySet() çağrılarak aktif ortamdaki tüm değişken isimleri/değerleri keşfedilebilir.
• Aktif ortam üzerinden çalışır; her script çalıştırılışında o anki aktif ortamın değerleri okunur.
• Gizli (Secret) olarak işaretlenmiş değerler çözülmüş plain değer olarak döner.
• Dene düğmesiyle açılan pencerede Secret değerler ****** olarak okunur. Ayrıntılar için Script Test Diyaloğu satırına bakın.
• Büyük/küçük harf duyarsız: get("dbHost"), get("DBHOST"), get("dbhost") aynı değeri döner.

// Discovery örneği — aktif ortamdaki değişken ADLARINI listeler (değerleri yazmaz; gizli değer içerebilir).
// Try It sonucunda "X-Env-Var-Names" başlığında görünür. Script'te log fonksiyonu yoktur; println Worker konsoluna yazar.
requestHeaderMapToTargetAPI.put("X-Env-Var-Names", environmentVariableMap.keySet().join(","));

Credential Bilgilerine Erişim

Mevcut credential_* değişkenleri yalnızca isteğin doğrulanmış credential'ını verir. Başka bir credential'a kullanıcı adı veya istemci kimliği ile erişmek için credentialMap kullanılır.

Örnek 1 — Basic Auth başlığı oluşturma (çözülmüş parola)

def cred = credentialMap.get("acme-app");
if (cred != null) {
    String token = cred.getUsername() + ":" + cred.getResolvedPassword();
    String header = "Basic " + Base64.getEncoder().encodeToString(token.getBytes());
    requestHeaderMapToTargetAPI.put("Authorization", header);
}

Örnek 2 — JWT imzalama (private key)

def cred = credentialMap.get("jwt-signer");
java.security.PrivateKey privateKey = cred?.getPrivateKey();
// privateKey ile JWT imzala...

Örnek 3 — mTLS için keystore yükleme

def cred = credentialMap.get("backend-mtls");
java.security.KeyStore ks = cred?.getKeyStore();
// ks'i SSLContext'e bağla...

Örnek 4 — JWE şifre çözme için JWK

def cred = credentialMap.get("jwe-recipient");
def jwk = cred?.getJwkForDecryptionAndEncryption();
// jwk ile şifre çöz...

Örnek 5 — Doğrulanmış kullanıcının credential'ı

def me = credentialMap.get(request_usernameOrKey);
String myEmail = me?.getEmail();
String myOrg = me?.getOrganizationName();

Örnek 6 — Özel metadata okuma

def cred = credentialMap.get("acme-app");
Map<String, String> meta = cred?.getMetadata();
String tenantId = meta?.get("tenant_id");
String department = meta?.get("department");

not

Erişilebilen alanlar (credentialMap.get(...) dönen nesnesi üzerinden):

• Temel: getUsername(), getEmail(), getFullName(), getDescription()
• Parola: getResolvedPassword() (şifresi çözülmüş; parola değerinde ${değişken} ifadesi varsa yerine geçer), getEnvironmentPassword("ortam-id") (ortam-bazlı çözülmüş parola)
• Kimlik metadata: getOrganizationId(), getOrganizationName(), getProjectId(), getProjectName(), getAppId(), getAppName()
• Yetki ve durum: getRoleNameList(), getEnabled(), isExternal(), getExpireDate(), getGrantType()
• Anahtar materyali: getSecretKey(), getCertificate(), getPublicKey(), getPrivateKey(), getKeyStore(), getTrustStore(), getJwkForValidationAndSign(), getJwkForDecryptionAndEncryption()
• Anahtar kimlikleri: getSecretKeyId(), getCertificateId(), getPublicKeyId(), getPrivateKeyId(), getKeyStoreId(), getTrustStoreId()
• Özel metadata (credential ve organizasyonu üzerinde tanımlı anahtar/değer çiftleri): getMetadata() (organizasyon + credential girdileri birleşik, anahtar çakışmasında credential öncelikli; değerler çözülür ve şifresi açılır), getCredentialMetadata() (yalnızca credential seviyesi), getOrganizationMetadata() (yalnızca organizasyon seviyesi) — her biri salt-okunur Map<String, String> döner

uyarı

Null kontrolü: credentialMap.get("...") çağrısı, credential bulunamazsa null döner. Null değer üzerinde getter çağrısı hata oluşturur — Groovy'de ?. operatörü veya açık if (cred != null) kontrolü kullanılmalıdır.

Anahtar listesi çıkarma engellidir: credentialMap.keySet(), values(), entrySet() çağrıları hata fırlatır. Yalnızca bilinen bir kullanıcı adı / istemci kimliği ile lookup desteklenir.

Güvenlik: Script politikasını oluşturma yetkisi, bu yöntem ile tüm credential'ların çözülmüş parolasına ve anahtar materyaline erişim yetkisi anlamına gelir. Bu yetkiyi atarken, kullanıcının ilgili credential'ları görüntüleme yetkisine sahip olduğundan emin olun.

Dene: Script'i Test Etme penceresinde credentialMap yalnız projenin credential'larını döner. Credential'ın parolası ve diğer gizli alanları ****** olarak okunur.

Önemli Notlar

not

Script tipi Groovy ise:

• Mesaj gövdesi JSON olan durumda JsonSlurper,
• Mesaj gövdesi XML olan durumda XMLSlurper

kullanılması, mesaj işleme işlemini oldukça kolaylaştırır.

uyarı

Hata mesajı değişkenleri ile istek bloke olduğunda istemciye, hata mesajı olarak Hata Yanıt Şablonu (Error Message Template) yerine bu değişkenin değerine ne yazıldıysa o dönmektedir.

Message Variables (Mesaj Değişkenleri)

Script Politikası içerisinde kullanabileceğiniz mesaj değişkenleri ve özellikleri aşağıdaki tablolarda detaylı olarak açıklanmıştır.

İstek Hattı Değişkenleri

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
request_remoteAddress	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Remote Address" değerine erişmek için kullanılır.	String value= request_remoteAddress; request_remoteAddress= "<new value>";
request_httpMethod	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "HTTP Method" değerine erişmek için kullanılır.	String value= request_httpMethod; request_httpMethod= "<new value>";
request_contentType	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Content Type" değerine erişmek için kullanılır.	String value= request_contentType; request_contentType= "<new value>";
request_pathInfo	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Path Info" değerine erişmek için kullanılır.	String value=request_pathInfo ; request_pathInfo= "<new value>";
request_contextPath	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Context Path" değerine erişmek için kullanılır.	String value= request_contextPath; request_contextPath= "<new value>";
request_queryString	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Query String" değerine erişmek için kullanılır.	String value= request_queryString; request_queryString= "<new value>";
request_remoteUser	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Remote User" değerine erişmek için kullanılır.	String value= request_remoteUser; request_remoteUser= "<new value>";
request_usernameOrKey	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Username veya API Key" değerine erişmek için kullanılır. Bu değer Apinizer üzerindeki bir güvenlik politikası ile doğrulanmış ise Apinizer tarafından bu değer atanır, veya veri manipülasyon politikaları ile de manuel olarak değer atanabilir.	String value= request_usernameOrKey; request_usernameOrKey= "<new value>";
request_requestedSessionId	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Requested Session Id" değerine erişmek için kullanılır.	String value= request_requestedSessionId; request_requestedSessionId= "<new value>";
request_requestURI	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Request URI" değerine erişmek için kullanılır.	String value= request_requestURI; request_requestURI= "<new value>";
request_characterEncoding	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Character Encoding" değerine erişmek için kullanılır.	String value= request_characterEncoding; request_characterEncoding= "<new value>";
request_charset	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Charset" değerine erişmek için kullanılır.	String value= request_charset; request_charset= "<new value>";
request_contentLength	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Content Length" değerine erişmek için kullanılır.	String value= request_contentLength; request_contentLength= "<new value>";
request_protocol	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Protocol" değerine erişmek için kullanılır.	String value= request_protocol; request_protocol= "<new value>";
request_scheme	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Scheme" değerine erişmek için kullanılır.	String value= request_scheme; request_scheme= "<new value>";
request_serverName	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Server Name" değerine erişmek için kullanılır.	String value= request_serverName; request_serverName= "<new value>";
request_serverPort	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Server Port" değerine erişmek için kullanılır.	String value= request_serverPort; request_serverPort= "<new value>";
request_remoteHost	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Remote Host" değerine erişmek için kullanılır.	String value= request_remoteHost; request_remoteHost = "<new value>";
request_remotePort	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Remote Port" değerine erişmek için kullanılır.	String value= request_remotePort; request_remotePort= "<new value>";
request_localName	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Local Name" değerine erişmek için kullanılır.	String value= request_localName; request_localName= "<new value>";
request_localAddr	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Local Address" değerine erişmek için kullanılır.	String value= request_localAddr; request_localAddr= "<new value>";
request_localPort	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "Local Port" değerine erişmek için kullanılır.	String value= request_localPort; request_localPort= "<new value>";
request_xForwardedFor	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istekteki "X-Forwarded-For" değerine erişmek için kullanılır.	String value= request_xForwardedFor; request_xForwardedFor= "<new value>";
request_isSoapToRest	Client → Apinizer	boolean	Okuma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin SoapToRest dönüşümü yapılan bir API Proxy'e gelip gelmediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_isSoapToRest;
request_isApiProxy	Client → Apinizer	boolean	Okuma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin API Proxy'e gelip gelmediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_isApiProxy;
request_isApiProxyGroup	Client → Apinizer	boolean	Okuma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin API Proxy Group'a gelip gelmediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_isApiProxyGroup;
request_data_isXwwwFormUrlEncoded	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin application/x-www-form-urlencoded başlığı içerip içermediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_data_isXwwwFormUrlEncoded; request_data_isXwwwFormUrlEncoded= true/false;
request_data_isFormData	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin "form data" verisi içerip içermediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_data_isFormData; request_data_isFormData= true/false;
request_data_isByteArray	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin "byte array" verisi içerip içermediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_data_isByteArray; request_data_isByteArray= true/false;
request_data_hasAttachment	Client → Apinizer	boolean	Okuma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin "attachment" verisi içerip içermediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value=request_data_hasAttachment ;
request_encoding_gzip	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "gzip" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_encoding_gzip; request_encoding_gzip= true/false;
request_encoding_deflate	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "deflate" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= request_encoding_deflate; request_encoding_deflate= true/false;
request_encoding_br	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "br" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value = request_encoding_br; request_encoding_br = true/false;
request_encoding_zstd	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "zstd" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value = request_encoding_zstd; request_encoding_zstd = true/false;
request_encoding_identity	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "identity" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value = request_encoding_identity request_encoding_identity= true/false;
request_encoding_compress	Client → Apinizer	boolean	Okuma, Yazma	İstemciden gelen istek Apinizer'da yorumlandıktan sonra isteğin veri formatının "compress" olup olmadığı bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value = request_encoding_compress request_encoding_compress= true/false;
request_estimatedTokenCount	Client → Apinizer	int	Okuma	İstek gövdesinin tahmini token sayısına erişmek için kullanılır (backend'e giden gövde; yoksa istemciden gelen gövde). Değer bir tahmindir. Yalnızca okunur: bu değişkene yazmanın etkisi yoktur.	int value= request_estimatedTokenCount;
request_httpServlet	Client → Apinizer	jakarta.servlet.http.HttpServletRequest	Okuma	İsteğin alt seviye servlet nesnesine erişim sağlar. Yalnızca standart değişkenlerle çözülemeyen ileri düzey senaryolarda kullanılmalıdır; yanlış kullanımı istek akışını bozabilir.	def req= request_httpServlet;

Yanıt Hattı Değişkenleri

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
response_data_isByteArray	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın "byte array" verisi içerip içermediği bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir.	boolean value= response_data_isByteArray; response_data_isByteArray= true/false;
response_encoding_gzip	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "gzip" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri gzip yapılarak dönülür.	boolean value= response_encoding_gzip; response_encoding_gzip= true/false;
response_encoding_deflate	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "deflate" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri deflate yapılarak dönülür.	boolean value= response_encoding_deflate; response_encoding_deflate= true/false;
response_encoding_br	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "br" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri br yapılarak dönülür.	boolean value= response_encoding_br; response_encoding_br= true/false;
response_encoding_compress	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "compress" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri compress yapılarak dönülür.	boolean value= response_encoding_compress; response_encoding_compress= true/false;
response_encoding_zstd	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "zstd" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri zstd yapılarak dönülür.	boolean value= response_encoding_zstd; response_encoding_zstd= true/false;
response_encoding_identity	Backend API → Apinizer	boolean	Okuma, Yazma	Backend API'den dönen yanıt Apinizer'da yorumlandıktan sonra yanıtın veri formatının "identity" olup olmadığının bilgisidir. Bu değişkenin değeri "true" ya da "false" olabilir. Eğer değeri false ise ve script içinde true olarak ayarlanırsa istemciye dönen veri identity yapılarak dönülür.	boolean value= response_encoding_identity; response_encoding_identity= true/false;
response_charset	Backend API → Apinizer	String	Okuma, Yazma	Backend API'den dönen yanıtın karakter kümesi (charset) değerine erişmek ve bu değeri değiştirmek için kullanılır.	String value= response_charset; response_charset= "UTF-8";
response_backendContentEncoding	Backend API → Apinizer	String	Okuma, Yazma	Backend API'den dönen yanıtın orijinal Content-Encoding başlık değerine erişmek ve bu değeri değiştirmek için kullanılır.	String value= response_backendContentEncoding; response_backendContentEncoding= "gzip";
response_statusCode	Backend API → Apinizer	Integer	Okuma, Yazma	Backend API'den dönen yanıtın durum kodu değerini içerir.	Integer value= response_statusCode; response_statusCode= 400;
response_httpServlet	Backend API → Apinizer	jakarta.servlet.http.HttpServletResponse	Okuma	Yanıtın alt seviye servlet nesnesine erişim sağlar. Yalnızca standart değişkenlerle çözülemeyen ileri düzey senaryolarda kullanılmalıdır; yanlış kullanımı yanıt akışını bozabilir.	def resp= response_httpServlet;

Hata Hattı Değişkenleri (Error Pipeline)

API Proxy'nin Error Pipeline hattına eklenen bir Script politikası, oluşan hatanın türüne göre dallanma yapabilsin diye hata bilgisine salt-okunur değişkenlerle erişebilir. Bu değişkenler yalnızca hata hattındaki Script politikalarında doludur; istek veya yanıt hattında bir hata oluşmadıysa değerleri boştur (null).

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
error_category	Hata Hattı → Script	String	Okuma	Hatanın kaba sınıfıdır ve dallanma için temel anahtardır. Olası değerler: ROUTING_ERROR (backend yönlendirme hatası), POLICY_BLOCK (bir politikanın isteği bloke etmesi), POLICY_ERROR (bir politika çalışırken oluşan hata), GATEWAY_ERROR (gateway/iç hata).	if (error_category == "ROUTING_ERROR") { ... }
error_type	Hata Hattı → Script	String	Okuma	Hatanın ayrıntılı türüdür; error_category'den daha ince dallanma gerektiğinde kullanılır.	String value= error_type;
error_parent	Hata Hattı → Script	String	Okuma	Hatanın ait olduğu üst grup bilgisidir.	String value= error_parent;
error_resultType	Hata Hattı → Script	String	Okuma	Sonuç tipidir: BLOCKED (istek bloke edildi) veya ERROR (hata oluştu).	String value= error_resultType;
error_message	Hata Hattı → Script	String	Okuma	Hatanın açıklama/detay mesajıdır.	String value= error_message;
error_code	Hata Hattı → Script	String	Okuma	Hatanın kodudur.	String value= error_code;
error_httpCode	Hata Hattı → Script	Integer	Okuma	Hataya karşılık gelen HTTP durum kodudur.	Integer value= error_httpCode;

not

Hata hattı değişkenleri salt-okunurdur; sistem hatayı yakaladığında atanır ve Script bunları yalnızca okur. Bu değişkenlere değer atamak sistemin hata yanıtını değiştirmez. Hata yanıtının gövdesini, başlığını veya durum kodunu değiştirmek için yanıt hattı değişkenlerini (responseBodyTextToClient, responseHeaderMapToClient, statusCodeToClient) kullanın.

Örnek — hata türüne göre yanıt dönüştürme:

import groovy.json.JsonOutput

if (error_category == "ROUTING_ERROR") {
    // Backend'e ulaşılamadığında istemciye sade ve tutarlı bir mesaj dön
    responseBodyTextToClient = JsonOutput.toJson([
        status : "unavailable",
        reason : error_type,
        code   : error_code,
        detail : error_message
    ])
    statusCodeToClient = 503
} else {
    // POLICY_BLOCK / POLICY_ERROR / GATEWAY_ERROR: yanıta dokunulmaz, hata olduğu gibi döner
}

Kodlama Değişkenlerinin Davranışı ve Yönlendirme Ayarları

Script politikasında istek veya yanıt hattındaki veri formatı (gzip, deflate, br, zstd, compress, identity) değişkenleri yazılabilir. Bu değişkenler, yönlendirme ayarlarındaki veri formatı geçersizlik (encoding override) ayarları ile birlikte çalışır ve aralarındaki öncelik sırası önemlidir.

Çalışma Sırası

Bir isteğin veri akışı aşağıdaki adımlardan geçer:

1. İstemciden gelen başlıklar okunur — İstemcinin gönderdiği veri formatı başlığı değerlendirilir.
2. Yönlendirme geçersizlik ayarları uygulanır — API Proxy veya Yönlendirme tanımındaki veri formatı geçersizlik değerleri, istemciden gelen başlığı ezer.
3. Gövde açılır — Ayarlara göre sıkıştırılmış istek gövdesi açılır.
4. Backend yönünde sıkıştırma geçersizliği uygulanır — Backend'e gönderilirken kullanılacak format belirlenir.
5. İstek hattı politikaları çalışır — Script politikası bu aşamada devreye girer. Script içinde veri formatı değişkeni yazılırsa önceki tüm ayarları ezer.
6. Gövde backend'e gönderilir — Script'in bıraktığı son değere göre sıkıştırma uygulanır.

Yanıt hattı da aynı mantıkla çalışır; backend'ten gelen yanıt için yönlendirme ayarları önce uygulanır, yanıt hattı script politikası en son söz sahibidir.

uyarı

Script içinde veri formatı değişkeni yazıldığında, yönlendirme ayarlarında tanımlanan geçersizlik değerleri sessizce ezilir. Script politikası ile yönlendirme ayarları aynı API Proxy'de birlikte kullanılıyorsa, hangi değerin öncelikli olacağı bilinçli planlanmalıdır.

Tek Seferde Tek Format

Bir istek veya yanıt için aynı anda yalnızca tek bir veri formatı aktif olmalıdır. Script içinde bir formatı true yapıyorsanız, diğer tüm format değişkenlerini açıkça false olarak ayarlamak gerekir. Aksi halde birden fazla format aynı anda aktif kalabilir ve backend ya da istemci tarafında beklenmeyen sonuçlar oluşur.

Önerilen kullanım:

// İsteği backend'e gzip formatında göndermek istiyoruz
request_encoding_gzip = true
request_encoding_deflate = false
request_encoding_br = false
request_encoding_zstd = false
request_encoding_compress = false
request_encoding_identity = false

Başlık Tutarlılığı

Veri formatı değişkeni değiştirildiğinde, istek veya yanıt başlıklarındaki Content-Encoding değeri de aynı değere getirilmelidir. Format değişkeni ile başlık değeri arasında uyuşmazlık olması, istemcinin veya backend'in gövdeyi açmakta sorun yaşamasına neden olur.

request_encoding_gzip = true
request_headers["Content-Encoding"] = "gzip"

Ne Zaman Script, Ne Zaman Yönlendirme Ayarı

• Yönlendirme ayarı (geçersizlik): Tüm istekler için sabit bir kural uygulanacaksa (örn. her istek mutlaka gzip olarak backend'e gitsin). Daha güvenli ve hataya açık olmayan seçenektir.
• Script: Karar çalışma zamanında dinamik olarak alınacaksa (örn. istemcinin IP adresine veya başlık değerine göre farklı format kullanılsın). Script içinde tüm format değişkenleri ve ilgili başlıklar birlikte yönetilmelidir.

İki yöntem aynı anda kullanılıyorsa script son söz sahibidir.

Mesaj Değişkenleri

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
message_correlationId	Client → Apinizer	String	Okuma, Yazma	İstemciden gelen istek Apinizer'a düştüğü anda Apinizer tarafından isteği benzersiz bir ID verilir ve bu ID yanıta da eklenir. Bu değişken ile bu benzersiz ID değerine erişilebilir.	String value= message_correlationId; message_correlationId= "<new value>";
message_cacheHit	Çalışma Zamanı	boolean	Okuma, Yazma	İsteğin cache'ten karşılanıp karşılanmadığı bilgisidir. Trafik loglarındaki "Cache Hit" alanına bu değer yazılır. Script içinde true ya da false atanarak bu değer değiştirilebilir; böylece kendi cache mantığını script ile kuran senaryolarda istek cache'ten karşılanmış olarak raporlanabilir. Yazma yalnızca HTTP hattında geçerlidir.	boolean value= message_cacheHit; message_cacheHit= true;
environment_id	Client → Apinizer	String	Okuma	API Trafiğin karşılandığı ve cevaplandığı Ortamın ID bilgisidir.	String value= environment_id;
environment_name	Client → Apinizer	String	Okuma	API Trafiğin karşılandığı ve cevaplandığı Ortamın İsim bilgisidir.	String value= environment_name;

Ortam Değişkenleri

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
apiProxyGroup_id	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Grup tarafından karşılanmış ise karşılanan API Proxy Grup'un ID bilgisine erişmek için kullanılır.	String value= apiProxyGroup_id;
apiProxyGroup_name	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Grup tarafından karşılanmış ise karşılanan API Proxy Grup'un isim bilgisine erişmek için kullanılır.	String value= apiProxyGroup_name;
apiProxy_id	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy tarafından karşılanmış ise karşılanan API Proxy'nin ID bilgisine erişmek için kullanılır.	String value= apiProxy_id;
apiProxy_name	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy tarafından karşılanmış ise karşılanan API Proxy'nin isim bilgisine erişmek için kullanılır.	String value= apiProxy_name;
apiProxy_relativePath	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy tarafından karşılanmış ise karşılanan API Proxy'nin yayınlandığı göreli yol (relative path) bilgisine erişmek için kullanılır.	String value= apiProxy_relativePath;
apiMethod_id	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Metodu tarafından karşılanmış ise karşılanan API Proxy Metodunun ID bilgisine erişmek için kullanılır.	String value= apiMethod_id;
apiMethod_name	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Metodu tarafından karşılanmış ise karşılanan API Proxy Metodunun isim bilgisine erişmek için kullanılır.	String value= apiMethod_name;
apiMethod_soapAction	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Metodu tarafından karşılanmış ise karşılanan API Proxy Metodunun "Soap Action" değerine erişmek için kullanılır. SOAP tipi API Proxylerde geçerlidir.	String value= apiMethod_soapAction;
apiMethod_httpMethod	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Endpoint'i tarafından karşılanmış ise karşılanan API Proxy Endpoint'in "Http Metod" değerine erişmek için kullanılır.	String value= apiMethod_httpMethod;
apiMethod_endpoint	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Endpoint'i tarafından karşılanmış ise karşılanan API Proxy Endpoint'in değerine erişmek için kullanılır.	String value= apiMethod_endpoint;
apiMethod_backend_httpMethod	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Endpoint'i tarafından karşılanmış ise karşılanan API Proxy Endpoint'in Backend API'de hangi "Http Metod" değerine gideceğini tutan değere erişmek için kullanılır.	String value= apiMethod_backend_httpMethod;
apiMethod_backend_endpoint	Client → Apinizer	String	Okuma	İstemciden gelen istek API Proxy Endpoint'i tarafından karşılanmış ise karşılanan API Proxy Endpoint'in Backend API'de hangi "Endpoint" değerine gideceğini tutan değere erişmek için kullanılır.	String value= apiMethod_backend_endpoint;
dateTime_year	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki yıl bilgisine erişmek için kullanılır.	Integer value= dateTime_year;
dateTime_month	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki ay bilgisine erişmek için kullanılır.	Integer value= dateTime_month;
dateTime_dayOfWeek	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki haftanın gün bilgisine erişmek için kullanılır. 1 (Pazartesi) ve 7 (Pazar) arasında değer alır.	Integer value= dateTime_dayOfWeek;
dateTime_dayOfMonth	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki ayın gün bilgisine erişmek için kullanılır. 1 ve 31 arasında değer alır.	Integer value= dateTime_dayOfMonth;
dateTime_hour	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki günün saat bilgisine erişmek için kullanılır. 0 ve 23 arasında değer alır.	Integer value= dateTime_hour;
dateTime_minute	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki UTC zamanındaki saatin dakika bilgisine erişmek için kullanılır. 0 ve 59 arasında değer alır.	Integer value= dateTime_minute;
dateTime_second	Çalışma Zamanı	Integer	Okuma	Çalışma zamanındaki UTC zamanındaki dakikanın saniye bilgisine erişmek için kullanılır. 0 ve 59 arasında değer alır.	Integer value= dateTime_second;
dateTime_epochMillis	Çalışma Zamanı	Long	Okuma	Çalışma zamanındaki UTC zamanındaki epoch milisaniye bilgisine erişmek için kullanılır. 1970-01-01T00:00:00Z tarihinden erişim anına kadar olan milisaniye bilgisine erişilir.	Long value= dateTime_epochMillis;
dateTime_formattedText	Çalışma Zamanı	String	Okuma	Çalışma zamanındaki UTC zamanındaki tarih zaman bilgisine "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'" formatında erişmek için kullanılır.	String value= dateTime_formattedText;
date_formattedText	Çalışma Zamanı	String	Okuma	Çalışma zamanındaki UTC zamanındaki tarih bilgisine "yyyy-MM-dd" formatında erişmek için kullanılır.	String value= date_formattedText;
time_formattedText	Çalışma Zamanı	String	Okuma	Çalışma zamanındaki UTC zamanındaki zaman bilgisine "HH:mm:ss" formatında erişmek için kullanılır.	String value= time_formattedText;
environment_certificateMap	Çalışma Zamanı	Map<String, X509Certificate>	Okuma	Çalışma zamanında ortama yüklü olan "X509Certificate" değerlerine erişmek için kullanılır. Erişim için varlığın adı kullanılır.	import java.security.cert.X509Certificate; X509Certificate obj= environment_certificateMap.get("obj-name");
environment_privateKeyMap	Çalışma Zamanı	Map<String, java.security.PrivateKey>	Okuma	Çalışma zamanında ortama yüklü olan "Private Key" değerlerine erişmek için kullanılır.	import java.security.PrivateKey; PrivateKey obj= environment_privateKeyMap.get("obj-name");
environment_publicKeyMap	Çalışma Zamanı	Map<String, java.security.PublicKey>	Okuma	Çalışma zamanında ortama yüklü olan "Public Key" değerlerine erişmek için kullanılır.	import java.security.PublicKey; PublicKey obj= environment_publicKeyMap.get("obj-name");
environment_secretKeyMap	Çalışma Zamanı	Map<String, javax.crypto.spec.SecretKeySpec>	Okuma	Çalışma zamanında ortama yüklü olan "Secret Key" değerlerine erişmek için kullanılır.	import javax.crypto.spec.SecretKeySpec; SecretKeySpec obj= environment_secretKeyMap.get("obj-name");
environment_keyStoreMap	Çalışma Zamanı	Map<String, java.security.KeyStore>	Okuma	Çalışma zamanında ortama yüklü olan "Keystore" değerlerine erişmek için kullanılır.	import java.security.KeyStore KeyStore obj= environment_keyStoreMap.get("obj-name");
environment_jwkMap	Çalışma Zamanı	Map<String, com.apinizer.common.apigw.jwk.Jwk>	Okuma	Çalışma zamanında ortama yüklü olan "JWK" değerlerine erişmek için kullanılır.	import com.apinizer.common.apigw.jwk.Jwk Jwk obj= environment_jwkMap.get("obj-name");
environmentVariableMap	Çalışma Zamanı	Map<String, String> (salt-okunur)	Okuma	Aktif ortamda tanımlı ortam değişkenlerine script gövdesinden erişim sağlar. Script gövdesinde ${değişken} ifadesi çözülmediği için bu yöntem kullanılır. Gizli (Secret) olarak işaretlenmiş değerler çözülmüş olarak döner. Büyük/küçük harf duyarsızdır. Yazma desteklenmez; ancak iteration (keySet()/values()/entrySet()) desteklenir.	String dbHost= environmentVariableMap.get("dbHost"); if (environmentVariableMap.containsKey("apiKey")) { ... }

Credential Değişkenleri

Akış Değişkenleri	Sahip Olduğu Değerin Yeri	Veri Tipi	İzin Verilen İşlem	Açıklama	Örnek Kullanım
credential_username	Çalışma Zamanı	String	Okuma	Politikadan önce ayarlanmış olan credential'ın "kullanıcı adı" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	String value= credential_username;
credential_email	Çalışma Zamanı	String	Okuma	Politikadan önce ayarlanmış olan credential'ın "email" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	String value= credential_email;
credential_fullName	Çalışma Zamanı	String	Okuma	Politikadan önceayarlanmış olan credential'ın "tam adı" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	String value= credential_fullName;
credential_secretKey	Çalışma Zamanı	javax.crypto.SecretKey	Okuma	Politikadan önce ayarlanmış olan credential'ın "Secret Key" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	javax.crypto.SecretKey value=credential_secretKey;
credential_certificate	Çalışma Zamanı	java.security.cert.X509Certificate	Okuma	Politikadan önce ayarlanmış olan credential'ın "Certificate" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	java.security.cert.X509Certificate value=credential_certificate;
credential_publicKey	Çalışma Zamanı	java.security.PublicKey	Okuma	Politikadan önce ayarlanmış olan credential'ın "Public Key" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	java.security.PublicKey value=credential_publicKey;
credential_privateKey	Çalışma Zamanı	java.security.PrivateKey	Okuma	Politikadan önce ayarlanmış olan credential'ın "Private Key" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	java.security.PrivateKey value=credential_privateKey;
credential_keyStore	Çalışma Zamanı	java.security.KeyStore	Okuma	Politikadan önce ayarlanmış olan credential'ın "Keystore" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	java.security.KeyStore value=credential_keyStore;
credential_trustStore	Çalışma Zamanı	java.security.KeyStore	Okuma	Politikadan önce ayarlanmış olan credential'ın "Truststore" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	java.security.KeyStore value=credential_trustStore;
credential_jwkForValidationAndSign	Çalışma Zamanı	com.apinizer.common.apigw.jwk.Jwk	Okuma	Politikadan önce ayarlanmış olan credential'ın "imzalama ve imza doğrulama için kullanılan JWK" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	com.apinizer.common.apigw.jwk.Jwk value=credential_jwkForValidationAndSign;
credential_jwkForDecryptionAndEncryption	Çalışma Zamanı	com.apinizer.common.apigw.jwk.Jwk	Okuma	Politikadan önce ayarlanmış olan credential'ın "şifreleme ve şifre çözme için kullanılan JWK" bilgisine erişmek için kullanılır. Eğer credential yoksa veya ayarlanmamış ise değeri null olur.	com.apinizer.common.apigw.jwk.Jwk value=credential_jwkForDecryptionAndEncryption;
credentialMap	Çalışma Zamanı	Map (salt-okunur)	Okuma	Aktif ortamdaki herhangi bir credential'a kullanıcı adı veya istemci kimliği ile erişim sağlar. Yukarıdaki credential_* değişkenleri yalnızca isteğin doğrulanmış credential'ını dönerken, bu yöntem ile başka bir credential'ın alanlarına da erişilebilir. Dönen nesne üzerinden çözülmüş parola, kullanıcı adı, e-posta, tam ad, organizasyon bilgisi, proje/uygulama bilgisi, rol isimleri, özel anahtar/değer metadata, ortam-bazlı parola, geçerlilik süresi, yetki tipi ve anahtar materyali (Secret Key, Certificate, Public Key, Private Key, Keystore, Truststore, JWK) okunabilir. Anahtar listesi çıkarılamaz ve değer yazılamaz.	def cred= credentialMap.get("acme-app"); String pwd= cred?.getResolvedPassword(); java.security.PublicKey pk= cred?.getPublicKey();

Custom Variables (Özel Değişkenler)

Request veya Response pipeline üzerindeki politikalar ile geçici olarak değişken tanımlama ve sonraki politikada kullanma ihtiyacı olabilir. Bu durumda customVariableMap değişkeni kullanılabilir.

Değişken Adı	Tip	Erişim	Açıklama	Örnek Kullanım
customVariableMap	Map<String, String>	Okuma, Yazma	İstek veya Yanıt hattında politikalar ile geçici olarak değişken tanımlanması yapmak ve bir sonraki politikada kullanmak ihtiyacı ortaya çıkabilir. Bu durumda "customVariableMap" değişkeni kullanılır. Örneğin; Bir API Proxy'nin script politikasından önceki politikasında iş kuralı politikası ile oluşturulan "testVariable" ismindeki değişkene script politikasında erişmek ve değerini değiştirmek gerekebilir. Bu durumda customVariableMap.get("testVariable") diyerek bu değişkene atanan değer okunmuş olur. Benzer şekilde script politikasında özel değişken oluşturmak için customVariableMap.put("testVariable","test value") şeklinde kullanım yapılması gerekir. Böylece bir sonraki politikada custom variable tipinde ve "testVariable" adında bir değişken oluşturularak script politikasında eklenen değere erişilebilir.	String value = customVariableMap.get("testVariable"); customVariableMap.put("testVariable", "test value");

Önemli Kısıtlamalar

uyarı

Pipeline Kısıtlamaları:

• İstek Hattına eklenen Script Politikası Yanıt Hattındaki değişkenlere erişemez.
• Yanıt Hattına eklenen Script Politikası ise İstek Hattındaki değişkenleri sadece okuyabilir.

Cache Erişimi

Script politikasından dağıtık cache'e yazmak, okumak ve silmek için cache değişkeni kullanılır. Bu değişken Cache Politikası ile aynı cache alanını paylaşır; depolama dağıtıktır, yani tüm gateway (worker) sunucuları aynı veriyi görür.

Metot	İmza	Dönüş	Davranış
get	cache.get(String key)	String | null	Cache'teki değeri döner. Kayıt yoksa, anahtar boşsa veya bir hata oluşursa null döner.
put	cache.put(String key, Object value, long ttlSeconds)	boolean	Değeri ttlSeconds saniye boyunca saklar. Anahtar boşsa veya ttlSeconds 0 ya da negatifse hiçbir şey yapmaz ve false döner.
delete	cache.delete(String key)	boolean	Kaydı siler. Silme başarılıysa true döner.

import groovy.json.JsonOutput
import groovy.json.JsonSlurper

def key = "profile|" + request_usernameOrKey
def cached = cache.get(key)
if (cached == null) {
    def fresh = JsonOutput.toJson([name: "Acme", tier: "gold"])
    cache.put(key, fresh, 600)   // 600 saniye boyunca sakla
    cached = fresh
}
def profile = new JsonSlurper().parseText(cached)

uyarı

• Dönen değer her zaman metindir. put ile bir nesne veya Map verseniz bile get size metin karşılığını döner. JSON/XML veriler için put öncesi serialize, get sonrası parse etmeniz gerekir.
• TTL zorunludur ve saniye cinsindendir. Süresiz saklama desteklenmez.
• Ayrı bir isim alanı (namespace) yoktur. Cache Politikası ile aynı alan kullanıldığından, anahtar çakışmasını önlemek için ayırt edici bir ön ek kullanın (profile|... gibi).
• Cache hataları script'e yansımaz. Tüm hatalar yutulur ve loglanır; cache çağrıları hiçbir zaman hata fırlatmaz, null veya false döner.

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	- Editör araç çubuğundaki Dene düğmesine tıklayın. Script'i Test Etme penceresi açılır. Başlığın yanındaki rozet script dilini gösterir. Apinizer hiçbir şeyi kaydetmez ve backend'i çağırmaz. - Üst satır: Script'iniz nerede çalışıyor? başlığının altında İstek veya Yanıt seçin. Rozetler akışı gösterir: İstek için Client → Script → Backend API, Yanıt için Backend API → Script → Client. Pencere, script'inizdeki değişkenlerin çalıştığı hattı seçer. Hattı değiştirebilirsiniz. - Üst satır: Ortam listesinden ortamı seçin. Ortam zorunludur. Script'i Çalıştır düğmesine tıklayın veya Ctrl+Enter tuşlarına basın (macOS'ta Cmd+Enter). Ortam seçmeden ve script yazmadan düğme devre dışı kalır. Düğmenin altındaki metin eksik olanı söyler. - Çalıştırmadan önce: Script'i Çalıştır düğmesi ve Ctrl+Enter önce editör kontrollerini ve derleme kontrolünü çalıştırır. Script hata içeriyorsa Script hata içeriyor penceresi sorar: Script'te N hata var. Yine de çalıştırılsın mı? Script'i çalıştırmak için Yine de çalıştır düğmesine tıklayın. Hataları düzeltmek için Geri dön düğmesine tıklayın. - 1 Test verisi: Bir bilgi mesajı, script'in okuduğu ve hâlâ boş olan verileri listeler. Mesajdaki düğmeler bu verileri ekler. Mesajın altında her mesaj için bir kart bulunur: From Client, To Backend, From Backend ve To Client. Kart; başlıkları, parametreleri, istek URL yolunu, gövdeyi, hata mesajını ve durum kodunu içerir. script okur ve script değiştirir rozetleri script'in kullandığı alanları işaretler. Alan eklemek için Alan ekle: yanındaki bir ada tıklayın. Doldurmadığınız bir alanı gizlemek için Gizle düğmesine tıklayın. - Test bağlamı: İsteğe bağlı Test bağlamı kutusu kartların altındadır. Credential (doğrulanan istemci) listesinden bir credential seçin. Pencere credential_* değerlerini ve credentialMap değişkenini doğrulanmış bir çağrıdaki gibi doldurur. Varsayılan değer Credential yok seçeneğidir. HTTP metodu listesinden bir metot seçin; seçim request_httpMethod değerini doldurur. Varsayılan değer POST'tur. Çalıştırmadan sonra test bağlamını değiştirirseniz sonuç eskir. Script'i yeniden çalıştırın. - 2 Script: Script editöründe kod tamamlama, editör kontrolleri, derleme kontrolü (Kontrol et) ve sorun listesi bulunur. Bu editör, politika ekranındaki editördür; ancak Değişkenler bandı ve yan paneli yoktur. Script'i değiştirip yeniden çalıştırın. Script boşsa pencere Script boş. Test etmek için bir script yazın. uyarısını gösterir. - 2 Script: Değişkenler paneli editörün altındadır. Bir değişkenin adını kopyalamak için değişkene tıklayın. Script'inizde geçen değişkenler vurgulanır. Her değişken grubunun rozeti seçili hattaki erişimi gösterir: Yalnızca okunur, Okunur ve değiştirilir veya Burada kullanılamaz. - 3 Sonuç: İlk çalıştırmadan önce sütun Henüz sonuç yok mesajını ve bir ipucu gösterir. Çalıştırmadan sonra özet Başarılı veya Başarısız durumunu, milisaniye cinsinden süreyi ve değişiklik sayısını gösterir. Değişiklik yok yazıyorsa script hiçbir şeyi değiştirmemiştir. - 3 Sonuç: Script hata verirse hata bloğu Script bir hatayla durdu. iletisini ve nedeni gösterir. Hata boş test verisinden kaynaklanabiliyorsa blok boş değerlerin adlarını listeler. - 3 Sonuç: Script akışı keserse sonuç Akış burada durur. Client bu hatayı alır. iletisini, durum kodunu ve mesajı gösterir. stopFlowAsSuccess true ise sonuç Akış burada SUCCESS sonucuyla durur. Client bu mesajı alır. iletisini gösterir. - 3 Sonuç: Başlık Backend API'ye giden istek veya Client'a giden yanıt olur. Başlık ve parametre tabloları sonucu test verisiyle karşılaştırır. Her satırda bir rozet bulunur: eklendi, değişti, silindi veya değişmedi. Değişmeyen satırları görmek için Değişmeyen N satırı göster düğmesine tıklayın. Script gövdeyi değiştirirse yeni gövde değişti rozetiyle görünür. Eski gövdeyi görmek için Script öncesi gövdeyi göster düğmesine tıklayın. Değer varsa sonuç ayrıca Özelleştirilmiş Backend URL ve Durum Kodu satırlarını gösterir. - 3 Sonuç: Kapalı Script'e verilen değerler (N) paneli, script'in aldığı değerlerin adlarını listeler. Panel adları kaynağa göre gruplar: Test girdilerinden, Ortamdan, Seçilen credential'dan, Try It'te sabit ve Çalışma zamanı servisi. Panel değerleri hiçbir zaman göstermez. - Çalıştırmadan sonra veriyi veya script'i değiştirirseniz bir not script'i yeniden çalıştırmanızı söyler. - Test penceresi script'i gateway ile aynı motorlarda çalıştırır: Groovy ve JavaScript (GraalJS). JavaScript script'leri Java sınıfı yükleyemez; Java.type kullanılamaz. Java sınıfı gerekiyorsa Groovy seçin. - Pencerede yaptığınız script değişiklikleri, pencereyi kapattığınızda editöre döner. Aynı pencere Script-2-API için de geçerlidir; bkz. Script'i Test Etme. - Güvenlik: Test penceresi gizli değerleri ****** olarak maskeler: credential'ın parolasını ve diğer gizli alanlarını, ayrıca gizli ortam değişkenlerini. - Güvenlik: Dene yalnızca test projesinin ve yönetici projesinin anahtar nesnelerini (sertifika, anahtar, keystore ve JWK) alır. Sertifikalar ve açık anahtarlar gerçek değerleriyle gelir. Özel anahtarlar, gizli anahtarlar, keystore'lar ve JWK'ler yalnızca adıyla bulunur; değerleri null olur. Yalnız projenin credential'ları kullanılabilir. - Yetki: Derleme kontrolü ve Dene, projede API Creator veya Genel Ayarlar için MANAGE yetkisi olan kullanıcılara açıktır. - Güvenlik: Cache yazmaları gerçek cache'e değil, geçici bir test cache'ine gider. Pencere backend'i hiçbir zaman çağırmaz.
Context Value Kütüphanesi	- Bağlam kutusu aranabilir bir listedir. Değerleri etikete veya ada göre arayın. - Değerler şu gruplarda yer alır: Request, Response, Metadata, Date/Time, Error ve Credential. - Bir değer seçtiğinizde değer panoya kopyalanır. - Kutunun yanındaki İmlece ekle düğmesi, seçili değeri imlecin olduğu yere ekler. - Değeri script içinde kullanarak çalışma zamanı bilgisine erişin.
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. Java sınıfı kullanacaksanız Groovy seçin.
Teknik	JavaScript script'inde Java sınıfı kullanabilir miyim?	Hayır. Worker'daki JavaScript script'leri Java sınıfı yükleyemez. Java.type kullanılamaz ve çalışma zamanında ReferenceError hatası oluşur. Java sınıfı gerekiyorsa Groovy seçin.
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?	Bağlam kutusundan bir değer seçtiğinizde ilgili ortam/metadata bilgisi panoya kopyalanır. Kutunun yanındaki düğme değeri imlece ekler. Script içinde kullanarak runtime verilerine erişebilirsiniz.
Kullanım	Script test ekranı gerçek trafiği etkiler mi?	Hayır. Test ekranı izole çalışır ve girilen örnek verilerle scripti çalıştırır. Backend'i çağırmaz ve gerçek cache'e yazmaz.
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.