Dinamik Değişkenler

Genel Bakış

Apinizer'da politika ayarları, bağlantı konfigürasyonları ve routing adresleri gibi birçok string alanda dinamik değişkenler kullanılabilir. Bu sayede sabit değerler yerine ortama, isteğe veya çalışma zamanına göre değişen değerler tanımlanabilir.

İki tür dinamik değişken vardır:

Environment Variable — ${key}

Ortam değişkenleri, deploy anında çözümlenir. Geliştirme, test ve üretim gibi ortamlara göre farklı değerler alabilir.

Context Variable — #{key}

Bağlam değişkenleri, her istekte çözümlenir. İstek bilgileri, tarih/saat gibi sistem verileri veya script ile atanan özel değerler içerir.

İki Değişken Türü

Özellik	Environment Variable (`${key}`)	Context Variable (`#{key}`)
Format	`${variableName}`	`#{variableName}`
Çözümleme Zamanı	Deploy anında	Her istekte
Değer Kaynağı	Environment Variable yönetim ekranından tanımlanır	Sistem otomatik oluşturur veya script ile atanır
Ortam Bağımlılığı	Evet — dev, test, prod için farklı değer	Hayır — istek bazlı
Tanım Gereksinimi	Environment Variable ekranında tanım gerekir	Sistem değişkenleri: gerekmez. Global değişkenler: Custom Variable tanımı gerekir
Tipik Kullanım	Host adları, base URL'ler, port'lar, bağlantı bilgileri	Kullanıcı bilgileri, istek detayları, tarih/saat, hata bilgileri
Değişkenlik	Deploy sonrası sabittir	Her istekte farklı olabilir

Environment Variable (`${key}`)

Environment Variable'lar, farklı ortamlarda (geliştirme, test, üretim) farklı değerler kullanmanızı sağlar. Deploy anında çözümlenir ve çalışma zamanında sabit kalır.

Örnek: ${api.hostname} → Geliştirmede localhost:8080, üretimde api.example.com

bilgi

Environment Variable tanımlama ve yönetim hakkında detaylı bilgi için Environment Variable sayfasına bakabilirsiniz. CRUD işlemleri ve kullanım senaryoları için Environment Variable Yönetimi sayfasını inceleyebilirsiniz.

Context Variable (`#{key}`)

Context Variable'lar her istekte çözümlenir ve iki alt kategoriden oluşur:

1. Sistem Context Variable'ları — Otomatik oluşturulur, tanım gerektirmez:

#{context.request.httpMethod}, #{context.request.uri}, #{context.request.remoteAddress}
#{context.system.year}, #{context.system.dateTime}
#{context.message.correlationId}
#{context.apiProxy.name}, #{context.apiProxy.id}
#{context.credential.clientId}, #{context.credential.username}
#{error.defaultErrorCode}, #{error.defaultMessage}

2. Global Variable'lar — Script ile oluşturulur, Custom Variable tanımı gerekir:

#{userId}, #{tenantId}, #{customValue}
Script politikasında customVariableMap.put("key", "value") ile değer atanır

bilgi

Variable tanımları hakkında detaylı bilgi için Değişkenler sayfasına bakabilirsiniz.

Karışık Kullanım

İki tür aynı anda kullanılabilir:

https://${api.hostname}/v1/users/#{userId}

${api.hostname} deploy anında çözümlenir (örn: api.example.com), #{userId} her istekte farklı değer alır.

Desteklenen Alanlar

Dinamik değişkenler, politika ve bağlantı ayarlarında neredeyse tüm string alanlarda kullanılabilir.

Politikalar

Politika	Desteklenen Alanlar	Değişken Türleri
REST API Call	URL, header, parametre, body	`${key}` ve `#{key}`
OIDC	Token endpoint, introspection endpoint, resource endpoint, form parametreleri	`${key}` ve `#{key}`
JOSE Validation / Implementation	Dynamic key HTTP endpoint	`${key}` ve `#{key}`
Authentication API	URL, header, parametre	`${key}` ve `#{key}`
Message Builder	Template, header, form alanları	`${key}` ve `#{key}`
Redaction	Key-value listesi	`${key}` ve `#{key}`
Diğer politikalar	Metin (string) giriş alanları	`${key}` ve `#{key}`

uyarı

Script politikası bu tabloda yer almaz. Script politikasında #{key} placeholder mekanizması kullanılmaz çünkü değişkenlere zaten customVariableMap nesnesi ve request_httpMethod, dateTime_year gibi binding'ler üzerinden doğrudan erişim sağlanır. Detaylar için Script'te Kullanım Farkı bölümüne bakınız.

Bağlantılar

Bağlantı Türü	Desteklenen Alanlar
Database Connection	Host, port, kullanıcı adı, şifre, connection string
LDAP Connection	URL, base DN, kullanıcı adı, şifre
Email Connection	Host, port, kullanıcı adı

Diğer Alanlar

Alan	Desteklenen Türler
Routing Adresi	`${key}` ve `#{key}`
JSON Error Response Template	`#{key}` (hata değişkenleri dahil)
XML Error Response Template	`#{key}` (hata değişkenleri dahil)
Identity Provider (DB, LDAP, API)	`${key}` ve `#{key}`
IP Group	`${key}` ve `#{key}`
Credential	`${key}` ve `#{key}`

not

Bağlantı ayarlarında (Database, LDAP, Email) genellikle ${key} (Environment Variable) kullanılır çünkü bu değerler ortam bazlıdır ve deploy anında çözümlenmelidir. #{key} (Context Variable) ise istek zamanında çözümlenir ve daha çok politika ayarlarında ve routing adreslerinde kullanılır.

UI'da Değişken Seçimi

Politika ve bağlantı düzenleme ekranlarında, breadcrumb alanında "Değişken" butonu bulunur. Bu butona tıklandığında açılan menüden iki diyaloğa erişilebilir:

Environment Variable Diyaloğu

Menüden "Environment Variable" seçildiğinde açılan diyalog, tanımlanmış tüm ortam değişkenlerini listeler:

Global Değişkenler — Tüm ortamlarda geçerli olan değişkenler
Ortama Özel Değişkenler — Belirli ortamlar için tanımlanmış değişkenler

Değişkene tıklandığında ${variableName} formatında panoya kopyalanır ve ilgili alana yapıştırılabilir.

Context Variable Diyaloğu

Menüden "Context Variable" seçildiğinde açılan diyalog, kullanılabilir tüm bağlam değişkenlerini kategorize ederek listeler:

Error Variables — Hata bilgileri
Request Variables — İstek bilgileri
Message Variables — Mesaj bilgileri
API Variables — API Proxy bilgileri
Credential Variables — Tüketici bilgileri
DateTime Variables — Tarih/saat bilgileri

Değişkene tıklandığında #{variableName} formatında panoya kopyalanır.

bilgi

Her iki diyalog da bağımsızdır. Aynı alanda hem ${key} hem #{key} kullanabilirsiniz.

Context Variable Referansı

Request (İstek)

Format	Açıklama	Örnek Değer
`#{context.request.httpMethod}`	HTTP metodu	`GET`, `POST`
`#{context.request.uri}`	İstek URI'si	`/api/users/123`
`#{context.request.contentType}`	İçerik tipi	`application/json`
`#{context.request.remoteAddress}`	İstemci IP adresi	`192.168.1.100`
`#{context.request.queryString}`	Query parametreleri	`?id=123`
`#{context.request.pathInfo}`	Path bilgisi	`/api/users`
`#{context.request.contextPath}`	Context path	`/apinizer`

DateTime (Tarih/Saat)

Format	Açıklama	Örnek Değer
`#{context.system.year}`	Yıl	`2026`
`#{context.system.month}`	Ay (1-12)	`2`
`#{context.system.dayOfMonth}`	Gün (1-31)	`4`
`#{context.system.dayOfWeek}`	Haftanın günü (1=Pazartesi, 7=Pazar)	`3`
`#{context.system.hour}`	Saat (0-23)	`14`
`#{context.system.minute}`	Dakika (0-59)	`30`
`#{context.system.second}`	Saniye (0-59)	`45`
`#{context.system.epochMillis}`	Unix timestamp (milisaniye)	`1707058245000`
`#{context.system.dateTime}`	Formatlanmış tarih/saat (UTC)	`2026-02-04T14:30:45.000Z`
`#{context.system.date}`	Formatlanmış tarih	`2026-02-04`
`#{context.system.time}`	Formatlanmış saat	`14:30:45`

Çıktı Desenleri

Formatlanmış tarih/saat değerleri şu desenlerde döner:

Tarih-saat: yyyy-MM-dd'T'HH:mm:ss.SSS'Z' → 2026-02-04T14:30:45.000Z
Tarih: yyyy-MM-dd → 2026-02-04
Saat: HH:mm:ss → 14:30:45

Çıktının zaman dilimi, değişken tanımındaki Zone ID alanıyla belirlenir.

Tarih/Saat Yardımcısı (`dtf`)

dtf, mesaj şablonları ve özel hata mesajlarında kullanılabilen bir JEXL helper fonksiyonudur. #{context.system.dateTime} gibi sabit UTC format yerine, zaman dilimi seçerek ve özel desenleri kullanarak esnek tarih/saat biçimlendirmesi sağlar.

API Referansı:

İfade	Açıklama	Örnek Sonuç
`#{dtf.format(zone)}`	Varsayılan format (`yyyy-MM-dd HH:mm:ss`) ile, belirtilen zaman diliminde formatlanmış tarih/saat döner	`#{dtf.format('+03:00')}` → `2026-07-14 15:00:00`
`#{dtf.format(zone, pattern)}`	Özel desenle (ISO offset, unix timestamp gibi) formatlanmış tarih/saat döner	`#{dtf.format('+03:00','yyyy-MM-dd\'T\'HH:mm:ssXXX')}` → `2026-07-14T11:57:13+03:00`
`#{dtf.epochMillis()}`	Unix timestamp (milisaniye cinsinden) döner	`#{dtf.epochMillis()}` → `1740912645000`

Zaman Dilimi (zone):

Offset biçimi: '+03:00', '-05:00', 'UTC'
Zone ID: 'Europe/Istanbul', 'America/New_York', 'Asia/Tokyo'

Pattern Kuralları:

Pattern bir JEXL string argümanı olduğundan, literal karakterler tek-tırnak escape ister: 'T' → \'T\'
XXX: ISO offset biçiminde saat dilimini döner (örn: +03:00)
Diğer yaygın pattern karakterleri: y (yıl), M (ay), d (gün), H (saat), m (dakika), s (saniye)

Karşılaştırma:

İfade	Açıklama	Sonuç
`#{context.system.dateTime}`	Sabit UTC format, seçim yok	`2026-07-14 07:57:14`
`#{dtf.format('+03:00')}`	Zaman dilimi seçilebilir, varsayılan format	`2026-07-14 15:00:00`
`#{dtf.format('+03:00','yyyy-MM-dd\'T\'HH:mm:ssXXX')}`	Hem zaman dilimi hem özel pattern	`2026-07-14T11:57:13+03:00`

Kullanım Senaryosu:

İstemci tarafından ISO 8601 offset formatında tarih/saat gerektiren hata mesajı şablonları:

{
  "error": "İşlem başarısız",
  "timestamp": "#{dtf.format('+03:00','yyyy-MM-dd\'T\'HH:mm:ssXXX')}"
}

Render: { "error": "İşlem başarısız", "timestamp": "2026-07-14T11:57:13+03:00" }

Message (Mesaj)

Format	Açıklama	Örnek Değer
`#{context.message.correlationId}`	Benzersiz istek ID'si	`abc123-def456-ghi789`

bilgi

API Proxy veya Proxy Group üzerinde tanımlanan özel message variable'lar da bu kategoride görüntülenir.

API

Format	Açıklama	Örnek Değer
`#{context.apiProxy.id}`	API Proxy ID'si	`api-proxy-123`
`#{context.apiProxy.name}`	API Proxy adı	`User Management API`

Credential (Kimlik)

Format	Açıklama	Örnek Değer
`#{context.credential.clientId}`	Kimlik doğrulanmış tüketici key/username	`my-app-key`
`#{context.credential.username}`	Tüketici kullanıcı adı	`admin`
`#{context.credential.email}`	Tüketici e-posta	`admin@example.com`
`#{context.credential.fullName}`	Tüketici tam adı	`Ahmet Yılmaz`

Error (Hata)

Format	Açıklama	Örnek Değer
`#{error.customizedErrorCode}`	Özelleştirilmiş hata kodu	`CUSTOM_001`
`#{error.customizedHttpCode}`	Özelleştirilmiş HTTP kodu	`400`
`#{error.customizedMessage}`	Özelleştirilmiş mesaj	`Lütfen tekrar deneyin`
`#{error.defaultErrorCode}`	Varsayılan hata kodu	`DEFAULT_001`
`#{error.defaultMessage}`	Varsayılan mesaj	`Bir hata oluştu`
`#{error.defaultHttpCode}`	Varsayılan HTTP kodu	`500`

Script'te Kullanım Farkı

Context variable'lar script politikası içinde farklı formatta kullanılır. Runtime'da nokta (.) ile ayrılan format, script'te alt çizgi (_) ile yazılır:

Runtime Format	Script Format
`#{context.request.httpMethod}`	`request_httpMethod`
`#{context.system.year}`	`dateTime_year`
`#{context.message.correlationId}`	`message_correlationId`
`#{context.apiProxy.name}`	`apiProxy_name`
`#{error.defaultErrorCode}`	`error_defaultErrorCode`

// Script içinde context variable kullanımı
String method = request_httpMethod
String year = dateTime_year
String correlationId = message_correlationId

Global Variable Kullanımı

Global variable'lar, Custom Variable tanımı ile oluşturulan ve script ile değer atanan değişkenlerdir. Politikalar arasında veri aktarımı için kullanılır.

Variable Tanımı Oluşturun

Project > Variables bölümünden Custom Variable tipinde yeni bir tanım oluşturun.

Script ile Değer Atayın

Script politikası içinde customVariableMap.put("variableName", "value") ile değer atayın.

Değişkeni Kullanın

#{variableName} formatında diğer politika ve ayarlarda kullanın.

Script Örneği:

// Request body'den kullanıcı bilgisi çıkarma
if (bodyTextFC != null && !bodyTextFC.isEmpty()) {
    def jsonBody = new groovy.json.JsonSlurper().parseText(bodyTextFC)
    if (jsonBody.userId) {
        customVariableMap.put("userId", jsonBody.userId.toString())
    }
}

// Header'dan değer alma
String token = headerMapFC.get("X-Custom-Token")
if (token != null) {
    customVariableMap.put("customToken", token)
}

uyarı

Global variable'lar script politikası çalıştıktan sonra kullanılabilir. Değişkeni kullanan politika, değer atayan script politikasından sonra çalışmalıdır (policy sırası önemlidir).

Kullanım Örnekleri

Hata Yanıt Şablonu

{
  "error": {
    "code": "#{error.defaultErrorCode}",
    "message": "#{error.defaultMessage}",
    "requestId": "#{context.message.correlationId}",
    "timestamp": "#{context.system.epochMillis}"
  }
}

Dinamik Routing

https://${api.hostname}/v1/#{tenantId}/users/#{context.request.pathInfo}

${api.hostname} deploy anında, #{tenantId} ve #{context.request.pathInfo} her istekte çözümlenir.

Response Header Ekleme

X-Request-ID: #{context.message.correlationId}
X-API-Name: #{context.apiProxy.name}
X-Processed-At: #{context.system.dateTime}

JSON Kaçışlama (`:json`)

Context variable değeri olduğu gibi yerleştirilir. JSON şablonunda değer ", \ veya satır sonu içerirse gövde geçersiz JSON olur. Değeri JSON metni içinde güvenli kullanmak için değişkene :json ekini yazın:

{
  "error": {
    "code": "#{error.defaultErrorCode:json}",
    "message": "#{error.defaultMessage:json}"
  }
}

Kural adı jb-"quoted" ise #{error.defaultMessage} ... jb-"quoted" verir (geçersiz JSON). #{error.defaultMessage:json} ... jb-\"quoted\" verir (geçerli JSON).

Ek tek değişkenlerde çalışır (custom, error.*, request.*/response.*, context.*, body.$...). #{...} çözen her alanda geçerlidir: Custom Message Builder (şablon modu), hata mesajı şablonları, hata yanıt kuralları, API Proxy hata şablonları, header ve URL alanları.
Eki olmayan şablonlar önceki gibi çalışır.
Ek JEXL ifadelerinin içinde, #FAULTMESSAGE# gibi standart yer tutucularda, ${...} ortam değişkenlerinde ve Message Builder form modunda çalışmaz. Eki addan hemen sonra, boşluksuz yazın (#{name:json}).
Şu biçimler eski anlamını korur: *:json veya ::json ile biten XPath ve adı tam olarak name:json olan custom variable.
body.//a:json gibi önekli bir ad testiyle biten XPath, :json eki olarak okunur. Yalnız *:json veya ::json ile biten XPath XPath anlamını korur.

Davranış Kuralları

Bulunamayan #{key} değerleri boş string ("") ile değiştirilir; hata fırlatılmaz, uyarı log'u yazılır
Bulunamayan ${key} değerleri çözümlenemez ve olduğu gibi kalır
Script politikasında custom variable map'e doğrudan erişim olduğu için #{...} placeholder mekanizması kullanılmaz
Variable isimleri büyük/küçük harf duyarsızdır

Sonraki Adımlar

Environment Variable

Ortam değişkenlerini detaylı öğrenin

Değişkenler

Variable tanımlarını öğrenin

Script Politikası

Script ile değişken kullanımı

Environment Variable Yönetimi

Environment Variable CRUD işlemleri

Genel Bakış​

İki Değişken Türü​

Environment Variable (${key})​

Context Variable (#{key})​

Karışık Kullanım​

Desteklenen Alanlar​

Politikalar​

Bağlantılar​

Diğer Alanlar​

UI'da Değişken Seçimi​

Environment Variable Diyaloğu​

Context Variable Diyaloğu​

Context Variable Referansı​

Request (İstek)​

DateTime (Tarih/Saat)​

Tarih/Saat Yardımcısı (dtf)​

Message (Mesaj)​

API​

Credential (Kimlik)​

Error (Hata)​

Script'te Kullanım Farkı​

Global Variable Kullanımı​

Kullanım Örnekleri​

Hata Yanıt Şablonu​

Dinamik Routing​

Response Header Ekleme​

JSON Kaçışlama (:json)​

Davranış Kuralları​

Sonraki Adımlar​

Genel Bakış

İki Değişken Türü

Environment Variable (`${key}`)

Context Variable (`#{key}`)

Karışık Kullanım

Desteklenen Alanlar

Politikalar

Bağlantılar

Diğer Alanlar

UI'da Değişken Seçimi

Environment Variable Diyaloğu

Context Variable Diyaloğu

Context Variable Referansı

Request (İstek)

DateTime (Tarih/Saat)

Tarih/Saat Yardımcısı (`dtf`)

Message (Mesaj)

API

Credential (Kimlik)

Error (Hata)

Script'te Kullanım Farkı

Global Variable Kullanımı

Kullanım Örnekleri

Hata Yanıt Şablonu

Dinamik Routing

Response Header Ekleme

JSON Kaçışlama (`:json`)

Davranış Kuralları

Sonraki Adımlar