Önbellekleme (Cache)

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ış

Önbellek politikası, politika zinciri içinde bağımsız önbellek okuma (LOOKUP), yazma (POPULATE) ve silme (INVALIDATE) işlemlerini gerçekleştirir. Bu politika, API Çağrısı politikasının kendi içindeki önbellek mekanizmasından farklı olarak, ne zaman önbelleğe erişileceğini, hangi değerin yazılacağını ve neyin silineceğini politika akışında açıkça kontrol etmenizi sağlar.

Politika; istek (request), yanıt (response) ve hata (error) akışlarının hepsine eklenebilir.

Amacı Nedir?

• Sık değişmeyen verileri önbellekte tutarak backend servis yükünü azaltmak.
• Pahalı hesaplama veya API çağrılarının sonuçlarını saklayarak tekrar yapılmasını önlemek.
• Politika zinciri içinde değişken değerlerini geçici olarak saklamak.
• Veri değiştiğinde ilgili önbellek kaydını silerek (INVALIDATE) önbelleği güncel tutmak.

Çalışma Prensibi

Önbellek Anahtarı

Üç işlem tipinin hepsi aynı şekilde oluşturulan bir anahtar kullanır:

• Anahtar Öneki: Anahtarın başına eklenen sabit metin (örn. profile, user-session). Farklı politikaların anahtarlarının çakışmasını önlemek için kullanılır.
• Anahtar Değişkenleri: Anahtarın parçalarını oluşturan değişken (Variable) listesi. HTTP header, query parametresi, gövde alanı, context değişkeni gibi her türlü değişken kullanılabilir. En fazla 32 değişken eklenebilir.

Anahtar, önek ve değişkenlerin çözümlenmiş değerlerinin sırayla | karakteriyle birleştirilmesiyle oluşur:

<Anahtar Öneki>|<değişken1 değeri>|<değişken2 değeri>|...

uyarı

• Anahtar Öneki ve Anahtar Değişkenleri'nden en az biri tanımlanmalıdır; ikisi de boşsa politika kaydedilemez.
• Anahtara proje, ortam veya API Proxy bilgisi otomatik olarak eklenmez. Aynı anahtar farklı API Proxy'ler ve ortamlar arasında paylaşılır. Çakışmayı önlemek için Anahtar Öneki kullanın.
• Oluşan anahtar 1024 karakteri aşarsa otomatik olarak MD5 özetine dönüştürülür.

Saklama Tipi

Seçenek	Açıklama
Dağıtık (varsayılan)	Kayıtlar Apinizer Cache servisinde tutulur ve tüm Gateway pod'ları tarafından paylaşılır.
Lokal	Kayıtlar her Gateway pod'unun kendi belleğinde tutulur; pod'lar arasında paylaşılmaz.

1. LOOKUP (Önbellekten Oku)

Oluşturulan anahtarla önbellekte kayıt arar ve sonuca göre Hedef Değişken'i günceller. Kaydın bulunamaması bir hata değildir ve akışı durdurmaz. Önbelleğe erişimde hata oluşursa davranış Hata Yönetimi ayarına göre belirlenir.

LOOKUP Sonuç Durumları

Durum	Ne zaman oluşur	Hedef Değişken	Akış
Bulundu (Hit)	Anahtara karşılık bir kayıt var	Önbellekteki değer yazılır	Devam eder
Boş Değer Bulundu	Anahtara karşılık bilinçli olarak saklanmış boş değer var ("Boş Değerleri de Önbelleğe Al" ile yazılmış)	Boş değer yazılır — bu da bir bulgudur	Devam eder
Bulunamadı (Miss)	Anahtara karşılık hiç kayıt yok	Özel değişken: temizlenir (önceki adımlardan kalan değerden arındırılır). Gövde / başlık / parametre: dokunulmaz — miss durumunda mesaj değiştirilmez	Devam eder

bilgi

Miss durumunda özel (custom) Hedef Değişken neden temizlenir? Aynı değişken politika zincirinde daha önce bir değer almış olabilir. Arama sonuçsuz kaldığında değişken temizlenmezse, bu eski değer yanlışlıkla "önbellekten gelen sonuç" gibi algılanabilir. Bu nedenle bulunamama durumunda özel Hedef Değişken her zaman boşaltılır; böylece sonraki politikalar "değişken dolu mu?" kontrolünü güvenle yapar.

Gövde, başlık ve parametre hedefleri neden temizlenmez? Bu hedefler mesajın kendisidir. Miss durumunda temizlenmeleri, istek ya da yanıtı backend'e ulaşmadan bozar (örneğin istek gövdesinin silinmesi, JSON yolunda null değerli yeni bir alan oluşması ya da XML düğümünün boşalması). Bu nedenle miss durumunda bu hedefler olduğu gibi bırakılır; yalnızca kayıt bulunduğunda yazılır.

2. POPULATE (Önbelleğe Yaz)

Kaynak Değişken'in değerini oluşturulan anahtarla önbelleğe yazar.

• Kaynak değer boşsa yazma atlanır. Boş Değerleri de Önbelleğe Al seçeneği işaretliyse boş değer de yazılır; bu şekilde saklanan değer sonraki aramalarda Bulundu olarak döner. Böylece sonucu boş olduğu bilinen sorgular için backend'e tekrar gidilmez.
• TTL: Kaydın önbellekte kalacağı süre (saniye). Yeni politikada 3600 olarak gelir; alan boşaltılırsa 60 saniye kullanılır.
• Kapasite: Önbellek alanının kapasitesi. Yeni politikada 10000 olarak gelir; alan boşaltılırsa 1000 kullanılır. Tüm Önbellek politikaları aynı ortak önbellek alanını kullanır; Lokal saklamada bu alanın kapasitesi, alanı ilk oluşturan politikanın değeriyle belirlenir.
• Dinamik TTL: Etkinleştirildiğinde TTL, bir değişkenin değerinden hesaplanır (bkz. Dinamik TTL).

3. INVALIDATE (Önbelleği Geçersiz Kıl)

Oluşturulan anahtara karşılık gelen kaydı önbellekten siler. Örneğin, bir güncelleme işleminden sonra eski kaydı temizlemek için kullanılır. Bu işlem için anahtar dışında ek bir alan yoktur.

Dinamik TTL

POPULATE işleminde Dinamik TTL Etkin açıldığında, TTL sabit değer yerine Dinamik TTL Değişkeni'nin değerinden hesaplanır. Değişken değerinin nasıl yorumlanacağı Dinamik TTL Kaynağı ile belirlenir:

Dinamik TTL Kaynağı	Değerin anlamı
ISO 8601 DateTime	Kaydın geçerliliğinin biteceği zaman, ISO 8601 biçiminde
Custom DateTime	Kaydın geçerliliğinin biteceği zaman, Özel Tarih Formatı alanında belirtilen biçimde
Epoch Seconds	Bitiş zamanı, epoch saniye
Epoch Milliseconds	Bitiş zamanı, epoch milisaniye
Expires-In Seconds	Şu andan itibaren geçerlilik süresi, saniye
Expires-In Milliseconds	Şu andan itibaren geçerlilik süresi, milisaniye
TTL String	Sayı ve birimden oluşan süre ifadesi: s (saniye), m (dakika), h (saat); birim büyük harfle de yazılabilir. Örn. 300s, 5m, 1h

Ek alanlar:

• JWT Token mı?: Açıldığında değişken değeri bir JWT olarak çözülür ve TTL bilgisi JWT Claim Adı alanında belirtilen claim'den okunur. Claim adı $. ile başlıyorsa JSONPath olarak işlenir.
• Offset (saniye): Hesaplanan TTL'den çıkarılan süre. Örneğin 30 girilirse kayıt, hesaplanan süreden 30 saniye önce geçersiz olur.
• Yedek TTL (saniye): Dinamik TTL çözümlenemezse kullanılacak TTL.

TTL şu sırayla belirlenir:

1. Dinamik TTL başarıyla çözümlenir ve pozitif bir değer verirse bu değer kullanılır.
2. Dinamik TTL çözümlenir ancak sıfır veya negatif bir değer verirse (örneğin bitiş zamanı geçmişse) kayıt yazılmaz.
3. Dinamik TTL çözümlenemezse Yedek TTL kullanılır.
4. Yedek TTL tanımlı değilse TTL alanındaki değer (yeni politikada 3600), o alan boşsa 60 saniye kullanılır.

bilgi

Dinamik TTL etkinken TTL alanı ekranda düzenlenemez.

Hata Yönetimi

Alan	Varsayılan	Açıklama
Önbellek Bağlantı Zaman Aşımı (saniye)	3	Dağıtık önbellek işlemlerinin bağlantı zaman aşımı. Yalnızca Saklama Tipi Dağıtık olduğunda uygulanır.
Önbellek Hatası Durumunda Davranış	Akışa Devam Et	Önbellek işlemi sırasında hata oluştuğunda (örneğin önbellek servisine bağlanılamadığında) davranışı belirler. Akışa Devam Et seçilirse akış sürer; Akışı Durdur seçilirse politika hata üretir. INVALIDATE işleminde silme başarısız olursa da bu ayar uygulanır; Lokal saklamada var olmayan bir anahtarı silmek de başarısız sayılır.

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir Önbellek politikası oluşturabilir ya da mevcut politika parametrelerini yapılandırarak önbellek işlemlerini tanımlayabilir.

Yeni Önbellek Politikası Oluşturma

Yapılandırma Adımları

Adım	Açıklama / İşlem
Adım 1: Oluşturma Sayfasına Gitme	Sol menüden Global Politikalar → Önbellek sayfasına gidin ve yeni politika oluşturun. Politika, bir API Proxy'nin akışına doğrudan da eklenebilir.
Adım 2: Genel Bilgiler	Durum: Aktif/Pasif durumu gösterir. Ad (Zorunlu): Politikanın adı. Sistem adın kullanılabilir olup olmadığını kontrol eder. Açıklama: Politikanın amacını açıklayan metin.
Adım 3: Operasyon	İşlem tipini seçin (Zorunlu): - Önbellekten Oku (LOOKUP) - Önbelleğe Yaz (POPULATE) - Önbelleği Geçersiz Kıl (INVALIDATE)
Adım 4: Önbellek Anahtarı	Saklama Tipi: Lokal veya Dağıtık (varsayılan: Dağıtık). Anahtar Öneki: Anahtarın başına eklenen sabit metin. Anahtar Değişkenleri: + butonuyla anahtarı oluşturacak değişkenleri ekleyin. Anahtar Öneki ve Anahtar Değişkenleri'nden en az biri dolu olmalıdır.
Adım 5a: Okuma (LOOKUP) Detayları	Hedef Değişken (Zorunlu): Önbellekten okunan değerin yazılacağı değişken.
Adım 5b: Yazma (POPULATE) Detayları	Kaynak Değişken (Zorunlu): Önbelleğe yazılacak değerin alınacağı değişken. Kapasite (adet): 1 – 1.000.000 (varsayılan 10000). TTL (saniye): 1 – 2.592.000 (varsayılan 3600). Boş Değerleri de Önbelleğe Al: Kaynak değer boş olsa bile yazılmasını sağlar. Dinamik TTL Etkin: Açıldığında Dinamik TTL Değişkeni (zorunlu), Dinamik TTL Kaynağı (zorunlu), Özel Tarih Formatı (Custom DateTime seçildiğinde zorunlu), JWT Token mı?, JWT Claim Adı (JWT seçildiğinde zorunlu), Offset (saniye) ve Yedek TTL (saniye) alanları görünür.
Adım 5c: INVALIDATE	Ek alan yoktur; Adım 4'te tanımlanan anahtara karşılık gelen kayıt silinir.
Adım 6: Hata Yönetimi	Önbellek Bağlantı Zaman Aşımı (saniye) (Zorunlu): Varsayılan 3. Önbellek Hatası Durumunda Davranış: Akışa Devam Et (varsayılan) veya Akışı Durdur.
Adım 7: Koşullar (İsteğe Bağlı)	Koşullar sekmesinde, politikanın yalnızca belirli koşullar sağlandığında çalışmasını tanımlayabilirsiniz.
Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)	Hata Mesajı Özelleştirme sekmesinde, politika hata ürettiğinde (Akışı Durdur) dönecek mesajı özelleştirebilirsiniz.
Adım 9: Kaydetme	Global Politikalar sayfasında Kaydet ve Yükle, API Proxy akışı içinden açılan pencerede Kaydet butonuna tıklayın. Ad, işlem tipi, anahtar (önek veya değişken) ve işleme göre Hedef/Kaynak Değişken eksikse buton pasif kalır; Dinamik TTL alanları ve zaman aşımı gibi diğer zorunlu alanlar kaydetme sırasında kontrol edilir ve eksikse kayıt reddedilir.

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.

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Önbellek politikası ile API Çağrısı politikasının önbelleği arasındaki fark nedir?	API Çağrısı politikasının önbelleği, o politikanın yaptığı çağrının yanıtını saklar. Önbellek politikası ise bağımsız LOOKUP / POPULATE / INVALIDATE işlemleriyle hangi değerin ne zaman okunup yazılacağını sizin belirlemenizi sağlar.
Genel	Aynı API'de birden fazla Önbellek politikası kullanabilir miyim?	Evet. Örneğin bir LOOKUP politikası ile değeri okuyup, değer yoksa backend çağrısından sonra bir POPULATE politikası ile yazabilirsiniz. Aynı veriye erişmek için iki politikada da aynı Anahtar Öneki ve Anahtar Değişkenleri kullanılmalıdır.
Teknik	Uzun anahtarlar nasıl ele alınır?	Oluşan anahtar 1024 karakteri aşarsa otomatik olarak MD5 özetine dönüştürülür. Ayrı bir ayar gerekmez.
Teknik	Dinamik TTL çözümlenemezse ne olur?	Yedek TTL, o da yoksa TTL alanındaki değer, o alan boşsa 60 saniye kullanılır. Dinamik TTL sıfır veya negatif çıkarsa (bitiş zamanı geçmişse) kayıt yazılmaz.
Kullanım	LOOKUP'ta kayıt bulunursa akışa ne olur?	Değer Hedef Değişken'e yazılır ve akış normal şekilde devam eder.
Kullanım	LOOKUP miss olduğunda Hedef Değişken'e ne olur?	Özel (custom) Hedef Değişken temizlenir; gövde, başlık veya parametre hedefine dokunulmaz. Akış devam eder; miss bir hata değildir.
Kullanım	Boş bir değer önbelleğe yazılmışsa LOOKUP nasıl davranır?	"Boş Değerleri de Önbelleğe Al" ile saklanmış boş değer, aramada Bulundu kabul edilir ve Hedef Değişken'e boş değer yazılır.
Hata	Önbellek erişim hatası olduğunda ne olur?	Önbellek Hatası Durumunda Davranış alanına bağlıdır: Akışa Devam Et seçiliyse akış sürer; Akışı Durdur seçiliyse politika hata üretir.
Hata	Önbelleğe yazma başarılı ama okuma miss dönüyor. Neden?	POPULATE ve LOOKUP politikalarındaki Anahtar Öneki ve Anahtar Değişkenleri'nin aynı olduğunu ve değişkenlerin çalışma anında aynı değerleri ürettiğini kontrol edin. Ayrıca iki politikanın aynı Saklama Tipi'ni kullandığından emin olun.