Zaman Kısıtlaması

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?

• API Proxy (API Vekil Sunucusu) trafiğini gün ve saat aralıklarına göre filtreleyerek yetkisiz zamanlarda erişimi engellemek.
• Bakım pencereleri veya kampanya süreleri gibi belirli zaman dilimlerinde istekleri otomatik olarak yönetmek.
• Farklı zaman dilimlerinden gelen çağrıları Zone ID ayarı sayesinde tutarlı şekilde değerlendirmek.
• Allow/Restrict aksiyon modlarıyla aynı yapılandırmayı hem izin verme hem de engelleme senaryolarında yeniden kullanmak.

Ç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ü: Zaman Kısıtlaması 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. Saat Bloğu Değerlendirmesi: Tanımlı hourWrapper kuralları seçilen Zone ID üzerinden gün, ay ve saat aralıklarına göre çalıştırılır; Allow modunda en az bir kural eşleşmesi gerekir, Restrict modunda eşleşen kural isteği bloklar.
4. Karar Verme:
   • Eşleşme Var: Allow modunda istek geçer; Restrict modunda isteğe varsayılan veya özelleştirilmiş hata kodu döndürülür.
   • Eşleşme Yok: Allow modunda istek 403 ile reddedilir; Restrict modunda istek 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

• Çoklu Saat Bloğu Yönetimi: Bir politika içinde sınırsız hourWrapper tanımlanarak farklı gün ve saat aralıkları aynı politikada toplanabilir.
• Çift Modlu Aksiyon Tipi: EnumRestrictionType (ALLOW/RESTRICT) desteği ile aynı yapılandırma hem izin verme hem de engelleme senaryolarına uygulanabilir.
• Zone ID Tabanlı Değerlendirme: Zone ID alanı sayesinde istekler varsayılan sunucu saatinden bağımsız, seçilen zaman dilimine göre değerlendirilir.
• 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

• Özel Gün ve Ay Tanımları: EnumDayType.CUSTOM seçimiyle tek bir gün, belirli bir ayın tamamı veya her ayın aynı günü gibi kurallar oluşturulabilir.
• Tam Gün Kuralı: WholeDay seçeneğiyle saat detayı girmeden gün bazlı tam bloklama veya izin verme yapılır.
• Kapsayıcı Doğrulama: isValid() kontrolleri ile zorunlu alan denetimleri, saat aralığı bütünlüğü ve isim benzersizliği otomatik doğrulanır.
• 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ç
Mesai Saati Kontrolü	Hafta içi 09:00-18:00 dışında gelen çağrılar engellenecek	dayType=WEEK, enumWeekDayList=Pazartesi–Cuma, 09:00:00-18:00:00, actionType=ALLOW.	Mesai dışı çağrılar 403 döner, mesai içi çağrılar işlenir.
Hafta Sonu Bakımı	Hafta sonu tüm gün bakım çalışması var	dayType=WEEK, enumWeekDayList=ALL, wholeDay=true, actionType=RESTRICT.	Cumartesi-Pazar tüm istekler 403 Bakım Modu mesajı ile reddedilir.
Ay Sonu Kapanış	Her ayın son günü erişim kapatılacak	dayType=CUSTOM, day=0, month=12 (Aralık) yerine gün=0, month=0 + wholeDay=false, actionType=RESTRICT.	Ay sonu dışındaki istekler çalışır, ay sonu günlerinde erişim reddedilir.
Kampanya Süresi	Belirli tarihlerde gece 23:00-02:00 arası ekstra rate limit uygulanacak	dayType=WEEK, enumWeekDayList=ALL, start=23:00:00, end=02:00:00 (sınır taşıyan blok iki wrapper ile), actionType=ALLOW.	Kampanya saatlerinde istek geçer, dışında Rate Limiting devreye girer.
Bölgesel Zamanlama	Farklı ülkeler için farklı saat dilimleri	Zone ID=+03:00 (TR) ve Zone ID=+00:00 (UK) için iki ayrı politika.	Her kullanıcı isteği kendi bölgesine göre değerlendirilir.
Acil Durum Kesintisi	Ani risk durumunda tüm trafik geçici kapatılacak	WholeDay=true, enumWeekDayList=ALL, actionType=RESTRICT, active=true.	Politika aktif edildiğinde tüm trafiği anında bloke eder.
Sadece Tatil Günleri (opsiyonel)	Yalnızca resmi tatillerde hizmet verilecek	dayType=CUSTOM, belirli gün/ay kombinasyonları, actionType=ALLOW.	Tatil günlerinde erişim sağlanır, diğer günlerde 403 döner.

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP'lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.

Yeni Zaman Kısıtlaması Politikası Oluşturma

Yapılandırma Adımları

Adım	Açıklama / İşlem
Adım 1: Oluşturma Sayfasına Gitme	- Sol menüden Development → Global Settings → Global Policies → Zaman Kısıtlaması bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın.
Adım 2: Temel Bilgileri Girme	Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Production_TimeWindow - Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: "Hafta içi mesai dışı erişimi engeller." - Maks. 1000 karakter. - Politikanın amacını açıklayın.
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: Saat Bloğu Konfigürasyonu	- Hour Name alanına kuralı tanımlayan kısa bir ad verin. - Day Type alanında WEEK veya CUSTOM seçin. - WEEK seçeneğinde çoklu hafta günü işaretleyin veya ALL ile tamamını kapsayın. - CUSTOM seçeneğinde gün ve ay seçimlerini kullanarak özel tarihleri belirleyin (0 değeri "her gün/ay"). - Whole Day seçeneği tüm günü kaplar; kapalıysa başlangıç ve bitiş saatini HH:MM:SS şeklinde girin. - Eklemeden önce saat aralığının başlangıçtan küçük olması zorunludur.
Adım 5: Aksiyon Tipini Belirleme	- Action Type alanında ALLOW seçerseniz yalnızca tanımlı bloklara uyan istekler kabul edilir. - RESTRICT seçerseniz seçilen bloklara uyan istekler engellenir. - Not: Restrict modunda çakışan bloklar tüm eşleşen istekleri durdurur.
Adım 6: Zone ID ve Kural Listesi Yönetimi	- Zone ID alanına ISO-8601 formatında (örn. +03:00 veya Europe/Istanbul) bir değer girin. - Farklı bölgeler için doğru zaman dilimini belirtmek önemlidir; aksi halde değerlendirme hatalı olur. - Eklenen hourWrapper kayıtları tabloya düşer; düzenlemek için silip yeniden ekleyin.
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
Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)	- Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 403, "message": "[Default hata mesajı]" } Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir hourWrapper 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.

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
Zaman Dilimi Uyarlama Motoru	- Zone ID alanına bölgesel değer girin. - Tüm hourWrapper blokları bu zaman dilimine göre hesaplanır. - Gerektiğinde aynı politikayı kopyalayarak farklı Zone ID'lerle çalıştırın.
Whole Day Acil Durum Kipi	- Whole Day seçeneğini aktifleştirin. - ALLOW veya RESTRICT moduna bağlı olarak tüm gün erişimi açın veya kapatın. - Geçici durumlarda active/passive togglesını kullanın.
Çoklu Saat Penceresi Zinciri	- Birden fazla hourWrapper ekleyin. - Her biri için farklı gün ve saat kombinasyonları belirleyin. - Çakışan pencereleri tespit etmek için liste tablosunu kontrol edin.

Best Practices

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Çalışma Saatleri Yönetimi	Kötü: Tüm gün için Restrict seçip saat aralığı bırakmak. İyi: Mesai dışı için tek bir Restrict hourWrapper eklemek. En İyi: Mesai içi Allow, mesai dışı Restrict politikalarını ayrı yönetip koşullarla bağlamak.
Bakım Pencereleri	Kötü: Bakım için manuel deploy yapmak. İyi: Whole Day Restrict kuralı oluşturmak. En İyi: Bakım tarihini Condition ile bağlayıp otomatik aktifleşen politika tasarlamak.
Çoklu Zaman Dilimi	Kötü: Tüm ülkeler için aynı Zone ID değerini kullanmak. İyi: Her bölgeye uygun Zone ID girmek. En İyi: Bölgesel politikaları Policy Group altında organize edip centrally deploy etmek.
İsimlendirme Stratejisi	Kötü: Rastgele UUID bırakmak. İyi: Ortam + amaç formatında adlandırmak. En İyi: Env_Function_TimeWindow şablonunu, açıklamada kapsamı belirterek kullanmak.
Aksiyon Modu Seçimi	Kötü: Varsayılan RESTRICT modunu her senaryoda kullanmak. İyi: İhtiyaca göre ALLOW veya RESTRICT seçmek. En İyi: Aynı API için Allow/Restrict kombinasyonlarını test ederek son kullanıcı davranışlarını doğrulamak.

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Zaman Dilimi Tutarlılığı	Zone ID yanlışsa istekler beklenmedik şekilde engellenebilir; proje standart Zone ID listesini kullanın.
Whole Day Kuralları	Whole Day ve RESTRICT birlikte kullanıldığında tüm trafik bloklanır; aktif etmeden önce koşulları doğrulayın.
Koşul Tabanlı Kısıtlama	Policy Condition ile ortam, header veya endpoint filtreleri kullanarak gereksiz bloklamayı önleyin.
Hata Mesajı Gizliliği	Özelleştirilmiş mesajda iç sistem bilgisi paylaşmayın; genel ifadeler kullanın.
Log İzlenebilirliği	PolicyAllowedHoursFailedException loglarını takip edin; beklenmeyen bloklamaları hızlıca tespit edin.

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Çakışan Saat Aralıkları	Neden kaçınılmalı: Allow modunda çakışmalar beklenmedik izinlere yol açar. Alternatif: Aynı zaman dilimlerini tek bir hourWrapper içinde tanımlayın.
Zone ID Boş Bırakma	Neden kaçınılmalı: Sunucu varsayımı farklı bölgelerde hatalı değerlendirme yapar. Alternatif: Politika oluştururken zorunlu Zone ID alanını doldurun.
İsim Tekrarı	Neden kaçınılmalı: API Proxy seçim ekranlarında ayırt etmek zorlaşır. Alternatif: Ortam ve fonksiyon bilgisi içeren benzersiz isim verin.
Global Politika Deneme	Neden kaçınılmalı: Canlı API'lerde anlık kesintiye yol açar. Alternatif: Önce local kopya üzerinden test edin, ardından globalde uygulayın.

Performans İpuçları

Kriter	Öneri / Etki
HourWrapper Sayısı	Öneri: Aynı davranışı sağlayan kuralları birleştirin. Etki: Politika değerlendirmesi daha hızlı tamamlanır.
Koşul Karmaşıklığı	Öneri: Query Builder'da gereksiz koşul eklemeyin. Etki: Koşul kontrolü hafifler, gecikme azalır.
Zone ID Değeri	Öneri: Sabit ofset yerine IANA tanımı kullanın. Etki: Yaz/kış saati değişimlerinde manuel müdahale azalır.
Whole Day Kullanımı	Öneri: Tam gün bloklama gerekiyorsa saat alanlarını sıfırlayın. Etki: Saat karşılaştırması yapılmadığı için işlem maliyeti düşer.
Politika Paylaşımı	Öneri: Aynı politikayı birden fazla API'de kullanırken Policy Group'tan yönetin. Etki: Deploy sırasında tek seferde güncelleme yapılır.

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Zaman Kısıtlaması politikası hangi senaryolarda tercih edilir?	İş mesai saatleri, bakım pencereleri, kampanya süreleri veya bölgesel saat farklarını yönetmek için kullanılır.
Genel	Aynı API'ye birden fazla Zaman Kısıtlaması politikası ekleyebilir miyim?	Evet, farklı koşullarla tetiklenen birden fazla politika eklenebilir; değerlendirme sırası API Gateway politika zincirine göre yapılır.
Teknik	Zone ID alanına ne tür değerler girilebilir?	ISO-8601 ofsetleri (+03:00) veya desteklenen IANA tanımları (Europe/Istanbul) girilebilir; sunucu runtime'ı bu değeri kullanır.
Teknik	Allow ve Restrict modları arasındaki fark nedir?	Allow modunda yalnızca tanımlı bloklarla eşleşen istekler geçer; Restrict modunda eşleşen istekler bloklanır, diğerleri serbest bırakılır.
Kullanım	Whole Day seçeneği gece yarısını kapsayan senaryolarda nasıl çalışır?	Whole Day seçildiğinde saat aralığına bakılmaz; ilgili gün boyunca aksiyon tipi uygulanır. Gece yarısı geçen bloklar için iki ayrı hourWrapper tanımlayın.
Kullanım	Politika hatası aldığımda hata mesajını nereden değiştiririm?	Error Message Customization sekmesinden HTTP statusCode, errorCode ve mesaj alanlarını düzenleyebilirsiniz; değişiklik global ise deploy gerekir.