Azure'da Cron Job Timer Trigger ve Hata Çözümleri

Azure'da düzenli rapor, veri eşitleme veya bakım işlemi için Azure Functions Timer Trigger kullanabilirsiniz. Zamanlayıcı tetikleyicisi HTTP isteği beklemeden fonksiyonunuzu takvime göre çalıştırır. Sunucuda crontab dosyası yönetmezsiniz; buna karşılık Function App ayarlarını, depolama bağlantısını ve çalışma kayıtlarını doğru kurmanız gerekir.

Bu rehber Python v2 programlama modeliyle tek bir zamanlanmış fonksiyon kurar. Azure aboneliğiniz, desteklenen bir Python sürümünüz ve Azure Functions Core Tools aracınız olduğu varsayılır. Önce yerelde çalışma kaydını doğrulayacak, sonra aynı projeyi Azure'a yayınlayacaksınız. Cron job kavramına aşinaysanız özellikle NCRONTAB alan sırasına ve planınıza bağlı saat dilimi sınırlarına odaklanın.

Timer Trigger Ne Zaman Uygundur?

İş mantığınız kodla ifade ediliyor ve her çalışmanın süresi öngörülebiliyorsa Timer Trigger uygundur. Görsel bağlantılarla süreç kurmak için Logic Apps, yönetim betikleri için Automation gibi seçenekleri ayrıca değerlendirebilirsiniz. Uzun işi yalnız tetikleyici seçerek çözemezsiniz; Function App planının süre ve kaynak sınırlarını gerçek veriyle ölçün.

Kurulumda iki soruyu ayırın: takvim ne zaman tetiklenecek ve iş hangi veri dönemini işleyecek? Gece yarısı çalışan bir raporun önceki iş gününü açıkça hesaplaması gerekir. Son başarılı dönemi veritabanında tutmak, gecikmeli başlangıçtan sonra eksik veriyi bulmayı kolaylaştırır. Takvim kaydı uygulama düzeyinde bir muhasebe defteri yerine geçmez.

NCRONTAB Alanları ve Çalışma Örnekleri

Bu rehberde açık altı alanlı biçimi kullanıyoruz: saniye, dakika, saat, ayın günü, ay ve haftanın günü. Örneğin 0 */5 * * * * her beş dakikanın sıfırıncı saniyesini tarif eder. İlk alanı unutursanız farklı bir zamanlama elde edebilirsiniz. Azure hem beş hem altı alanlı NCRONTAB kabul etse de örnekleri tek biçimde tutmak incelemeyi kolaylaştırır.

Standart Linux crontab sözdizimindeki dakika alanı burada ikinci sıradadır. AWS cron ifadesinde ise altıncı alan yıldır; bulutlar arasında alan sayısına bakarak dönüşüm yapmayın, AWS cron ifadesinin alan sırası ayrı rehberde karşılaştırmalı verilmiştir. Ayın günüyle haftanın gününü birlikte kısıtlayan karmaşık ifadelerde hedef takvim günlerini ayrıca sınayın. Resmi Timer Trigger başvurusu alanları ve tetikleme davranışını açıklar.

Adım Adım Python Timer Fonksiyonu Oluşturma

1. Core Tools ve Python sürümünüzün Azure Functions tarafından desteklendiğini doğrulayın. Boş bir proje klasöründe sanal ortam açın; örnek komutlar Bash içindir. Windows'ta sanal ortamı etkinleştirme yolu farklıdır.
2. func init ile Python v2 projesini hazırlayın. Üretilen requirements.txt bağımlılıklarını sanal ortamda yükleyin. func new komutunda Timer trigger şablonunu seçin.
3. Üretilen function_app.py içeriğini aşağıdaki küçük örnekle değiştirin. İlk aşamada gerçek silme veya ödeme işlemi eklemeyin; yalnız çalışma kaydını doğrulayın.
4. local.settings.json içindeki Values bölümüne ReportSchedule değerini ekleyin. AzureWebJobsStorage için test depolama hesabınızı veya çalışan Azurite emülatörüne ait UseDevelopmentStorage=true değerini kullanın. Emülatör bu rehberde kurulu varsayılır.
5. func start ile yerel hostu açın. Sonraki beş dakikalık sınırda uygulama günlüğünde tamamlandı kaydını görün. İşlem yapılmadığı için bu kayıt yalnız örnek fonksiyonun çalıştığını kanıtlar.

# Bash; Python ve Core Tools önceden kurulmuş olmalıdır.
mkdir azure-cron-demo
cd azure-cron-demo
python -m venv .venv
source .venv/bin/activate
func init . --worker-runtime python --model V2
func new --name rapor_zamanlayici --template "Timer trigger"
python -m pip install -r requirements.txt

# function_app.py
import logging
from datetime import datetime, timezone
import azure.functions as func

app = func.FunctionApp()

@app.timer_trigger(
    schedule="%ReportSchedule%",
    arg_name="timer",
    run_on_startup=False,
    use_monitor=True
)
def rapor_zamanlayici(timer: func.TimerRequest) -> None:
    if timer.past_due:
        logging.warning("Zamanlayici gecikmeli basladi")
    logging.info(
        "job=rapor_zamanlayici durum=tamamlandi zaman=%s",
        datetime.now(timezone.utc).isoformat()
    )

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "ReportSchedule": "0 */5 * * * *"
  }
}

Yerel ayar dosyasını herkese açık bir depoya koymayın; gerçek depolama bağlantısı gizli bilgi içerir. Python v2 modelinde dekoratörler bağlamaları tanımlar; farklı programlama modeline ait function.json örneğini bu projeye rastgele eklemeyin. Dosya yapısı ve bağımlılık düzeni için Python geliştirici başvurusunu kullanın.

Azure'a Yayınlama ve Depolama Bağlantısı

Azure Portal'da bir Function App oluşturun; Python çalışma zamanı ve uygun plan seçin. Bu rehberdeki bulut ayarları Linux üzerinde UTC kullanacak biçimdedir. Depolama hesabını bağlayın, Application Insights izlemeyi etkinleştirin. Yerel proje ile buluttaki Python sürümünün uyumunu kontrol edin; yerelde çalışması yanlış çalışma zamanı seçimini telafi etmez.

Function App ortam değişkenlerine ReportSchedule ekleyin. local.settings.json değerleri normal yayınlama işlemiyle otomatik taşınmış kabul edilmemelidir. Aşağıdaki komutlarda uygulama ve kaynak grubu adlarını değiştirin. Kullanıcı hesabınızın ilgili uygulamayı yayınlayabildiğini doğrulayın; komutları proje klasöründe çalıştırın.

az login
az functionapp config appsettings set \
  --resource-group cron-kaynak-grubu \
  --name uygulamanizin-adi \
  --settings 'ReportSchedule=0 */5 * * * *'

func azure functionapp publish uygulamanizin-adi

Yayınlamadan sonra fonksiyonun listelendiğini ve sonraki planlanan çalışmanın kaydını kontrol edin. AzureWebJobsStorage, hostun depolama bağlantısıdır; yanlış bağlantı veya depolama güvenlik duvarı zamanlayıcının başlamasını engelleyebilir. Yönetilen kimlik tabanlı bağlantı kullanıyorsanız anahtar tabanlı örneği aynen kopyalamayın; gerekli veri erişim rollerini de tanımlayın. Function App ayarları başvurusu depolama ve çalışma zamanı ayarlarını açıklar.

İstanbul Saati ve Hosting Planı Kısıtları

Varsayılan zaman dilimi UTC'dir. İstanbul için 09:00 hedefiniz varsa ve UTC kullanıyorsanız 0 0 6 * * * yazın. Bu örnek mevcut UTC+3 farkına dayanır; iş kuralınız yerel takvime bağlıysa saat dilimi kurallarındaki değişiklikleri de izleyin. Loglarda hem UTC zamanını hem iş dönemini saklayın. Saat dilimini iş tanımında açıkça seçebilen bir bulut zamanlayıcı arıyorsanız Google Cloud Scheduler kurulumunda bu seçeneğin karşılığı anlatılır.

WEBSITE_TIME_ZONE desteği işletim sistemine ve plana bağlıdır. Windows'ta Windows saat dilimi adı, desteklenen Linux Premium veya Dedicated planlarında IANA adı kullanılır. Linux Consumption ve Flex Consumption üzerinde WEBSITE_TIME_ZONE ve TZ desteklenmez; bu ayarları eklemek SSL ve metrik sorunlarına neden olabilir. Bu planlarda UTC tabanlı zamanlama kullanın. Saat dilimi uygulama ayarının resmi açıklamasını planınızla karşılaştırın.

Gecikme, Yeniden Deneme ve İzleme

past_due, çalışmanın takvimdeki zamanından geç başladığını belirtir; her kaçırılmış aralığın tek tek işlendiğinin garantisi değildir. use_monitor zamanlama durumunun izlenmesini sağlar. run_on_startup değerini üretimde false tutun; host yeniden başlamasını iş için ek bir tetikleme haline getirmeyin. Ölçeklenmede timer kilidi aynı fonksiyonun birden çok hostta eşzamanlı tetiklenmesini sınırlar.

Timer tetikleyicisi varsayılan olarak başarısız çalışmayı anında yeniden denemez. Ayrı bir retry ilkesi tanımlayacaksanız dil ve uzantı desteğini kontrol edin; ödeme gibi yan etkilerde önce tekrar işlemeyi önleyin. Azure Functions hata ve retry rehberi bu politikaları açıklar.

Application Insights içinde fonksiyon adı, başlangıç, bitiş, süre, işlenen kayıt sayısı ve son başarılı dönemi birlikte izleyin. Beklenen aralıkta hiç çalışma olmaması için de uyarı tanımlayın; yalnız exception sayısını izlemek sessiz durmayı yakalamaz. Resmi yürütme izleme belgesindeki sorguları uygulamanızın günlük yapısına uyarlayın.

İki Gerçek Kullanım Senaryosu

Beş Dakikada Bir Sipariş Eşitleme

Örnekteki takvimle dış sistemden güncellenen siparişleri alın. Son başarılı imleci yalnız veri yazma tamamlandıktan sonra ilerletin. Siparişin dış kimliğine benzersiz kısıt koyun; yeniden çalışma aynı siparişi çoğaltmasın. İş süresi aralığı aşmaya başladıysa daha sık tetiklemek yerine sayfalama boyutunu ve kuyruk tüketimini düzenleyin.

Günlük Dosya Temizliği

Her gün 06:00 UTC'de geçici dosyaları tarayın. Önce yalnız silinecek adayları raporlayan bir deneme modu kullanın. Kapsayıcıyı, öneki ve son değiştirilme sınırını açıkça sınırlandırın; dosya listesindeki bütün sayfaları değerlendirin. Kurallar yalnız yaşa bağlıysa kod yazmadan önce depolama yaşam döngüsü politikasının ihtiyacı karşılayıp karşılamadığını inceleyin. Silme yetkisini rapor okuma yetkisinden ayrı tutun.

Sık Hatalar ve Çözümleri

The listener for function ... was unable to start

Bu host mesajında asıl neden iç exception kaydındadır. AzureWebJobsStorage değerini, depolama erişimini ve kimlik rollerini kontrol edin. Depolama hesabı anahtarı değiştiyse bağlantı bilgisini güncelleyin. Yalnız fonksiyon kodunu yeniden yayınlamak bir ağ engelini çözmez.

ModuleNotFoundError: No module named 'azure.functions'

Bağımlılık yüklenmemiş veya yanlış Python ortamı seçilmiş olabilir. Sanal ortamın etkinliğini ve requirements.txt içinde azure-functions bulunduğunu doğrulayın. Bulut derleme günlüğünü inceleyin; yerel makinenizdeki bağımlılıkların buluta kendiliğinden geçtiğini varsaymayın.

Geçersiz NCRONTAB veya Eksik ReportSchedule

ReportSchedule değerinin Azure'da da tanımlı olduğunu ve dekoratörde aynı adla kullanıldığını kontrol edin. Basit 0 */5 * * * * ifadesiyle başlayın. Geçersiz ifade Portal testinde 404 gösterebilir; ayrıntıyı host veya Application Insights kaydından okuyun.

Görev Her Yeniden Başlatmada Çalışıyor

run_on_startup seçeneğinin yanlışlıkla true kalıp kalmadığını kontrol edin. Aynı projede ikinci bir timer, dağıtım slotu veya eski uygulama kopyası da bulunabilir. Kaynak adlarını ve iş günlüklerini karşılaştırın; tek takvim tanımı görmeniz bütün ortamda tek üretici olduğu anlamına gelmez.

Çalışma Kaydı Var, Beklenen Veri Yok

İş tamamlanmadan başarı kaydı yazılmış veya exception yakalanıp yutulmuş olabilir. Beklenen rapor dosyasını ve veritabanı durumunu doğrulayın. Gerekirse cron hata teşhisi adımlarını kullanarak tetikleme, erişim ve iş mantığını ayrı kontrol edin.

cronjob.com.tr ile HTTP Tabanlı Alternatif

Timer fonksiyonunu dışarıdan çağırılacak normal URL sanmayın. Harici zamanlama istiyorsanız iş mantığını ortak bir fonksiyona taşıyıp ayrı HTTP trigger ekleyin. Yönetim amaçlı host anahtarını panelde paylaşmak yerine uygulamaya özel gizli token doğrulayın. Aşağıdaki Python v2 parçası mevcut app nesnesine eklenir; anonim platform erişimi uygulama token kontrolüyle korunur. Easy Auth gibi ek bir katman varsa onun erişim koşullarını da karşılamalısınız.

import hmac
import os

@app.route(
    route="cron-http",
    methods=["POST"],
    auth_level=func.AuthLevel.ANONYMOUS
)
def cron_http(req: func.HttpRequest) -> func.HttpResponse:
    expected = os.environ["CRON_HTTP_TOKEN"]
    supplied = req.headers.get("X-Cron-Token", "")
    if not expected or not hmac.compare_digest(expected, supplied):
        return func.HttpResponse("Unauthorized", status_code=401)
    # Ortak iş mantığınızı burada çalıştırın.
    return func.HttpResponse("Erisim dogrulandi", status_code=200)

Panelde URL olarak https://uygulamanizin-adi.azurewebsites.net/api/cron-http, metot olarak POST, X-Cron-Token header değeri olarak ortamdaki sırrı ve beş dakikalık aralığı girin. Function App genel ağdan erişilebilir olmalı; özel ağ adreslerine istek gönderilmez. Hem Timer hem HTTP yolunu aynı iş için etkin bırakmayın.

Beş dakikalık hazır aralıkta timeout 290 saniye, bir dakikada 55, iki dakikada 115 saniyedir. Bağlantı hatası olmadan HTTP 200–399 başarı sayılır. Varsayılan ardışık hata eşiği üçtür; erişim sorunu ve düzelme e-postaları gönderilir, aynı işte bildirimler arasında en az 60 dakika bulunur. Loglar yedi gün tutulur. Uzun işi kalıcı kuyruğa kabul ederseniz kuyruğun tamamlanma durumunu ayrıca izleyin.

Sıkça Sorulan Sorular (SSS)

Azure NCRONTAB ifadesinde ilk alan nedir?

Bu rehberde kullanılan altı alanlı biçimde ilk alan saniyedir. Beş alanlı Linux cron ifadesiyle veya yıl alanı içeren AWS cron ifadesiyle karıştırmayın.

Linux Flex Consumption üzerinde WEBSITE_TIME_ZONE kullanılır mı?

Hayır. Linux Flex Consumption ve Linux Consumption planlarında WEBSITE_TIME_ZONE ve TZ desteklenmez. Bu planlarda UTC üzerinden zamanlama yapın.

past_due bütün kaçırılan görevleri telafi eder mi?

Hayır. past_due gecikmeli başlangıcı belirtir; geçmişteki her veri döneminin ayrı ayrı işlendiğini kanıtlamaz. Eksik dönemleri uygulamanızın kayıtlarından belirleyin.

Timer Trigger hata sonrası otomatik yeniden dener mi?

Varsayılan timer davranışı anında yeniden deneme değildir. Ayrı retry politikası gerekiyorsa kullanılan dil ve uzantının desteğini kontrol ederek açıkça yapılandırın.

Timer Trigger ücretsiz midir?

Maliyet; plan, yürütme süresi, depolama ve izleme kullanımına bağlıdır. Hesabınıza ve seçtiğiniz plana uygulanan ücretsiz kullanım koşullarını resmi Azure fiyatlandırmasından kontrol edin.

İlgili Rehberler