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ı: 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 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, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz.
• Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz.
• Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar.
• Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.

Adım 4: 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ı

Script Language altında Javascript veya Groovy seçin. Seçim kod editörünün sözdizimini ve IntelliSense'i belirler.

Adım 6: 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
• Dene (Try it) düğmesiyle Script'i Test Etme penceresini açın ve script'i örnek veriyle çalıştırın. Apinizer hiçbir şeyi kaydetmez ve backend'i çağırmaz.

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.

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;

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.
• Büyük/küçük harf duyarsız: get("dbHost"), get("DBHOST"), get("dbhost") aynı değeri döner.

// Discovery örneği — aktif ortamdaki tüm değişkenleri logla
environmentVariableMap.keySet().each { name ->
    request_log("env: " + name + " = " + environmentVariableMap.get(name));
}

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.

Ö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_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	- Dene (Try it) düğmesiyle açılır. - Pencere, script'teki değişkenlerin çalıştığı hattı (İstek veya Yanıt) seçer. Ortam listesinden ortamı seçin. - Yalnız script'in okuduğu değerler için örnek veri girin. Pencere, script'in okuduğu boş değerleri listeler. - Script'i Çalıştır düğmesine tıklayın veya Ctrl + Enter tuşlarına basın. Sonuç, script'in yaptığı değişiklikleri gösterir: eklendi, değişti ve silindi. - Pencerede yaptığınız script değişiklikleri pencereyi kapattığınızda editöre aktarılır. Ayrıntılar için Script'i Test Etme bölümüne bakın.
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.