iklim.co Python sandbox istemcileri

Bu klasör HMAC imzalı istek, otomatik login/refresh ve .env token saklama özelliklerini ortak bir istemci katmanında toplar. Geo alarm registration istemcisi bu ortak yapıyı kullanarak noktalı virgüllü CSV satırlarını sırayla işler.

Dosyalar

• common/: tekrar kullanılabilir API, HMAC, retry ve authentication katmanı
• login.py: manuel login komutu
• nowcast-geo-register.py: CSV geo alarm registration istemcisi
• .env.example: güvenli ortam değişkeni şablonu
• webhook.example.json: dört webhook authentication seçeneğini içeren şablon
• nowcast-geo-alarm-filter.example.json: ortak nowcast geo alarm filtreleri şablonu
• nowcast-geo-alarm-registrations.example.csv: CSV şablonu

Gerçek değerler için .env, webhook.json ve nowcast-geo-alarm-filter.json kullanılır. .env ile webhook.json kaynak kod deposuna eklenmemelidir.

Kurulum

cd iklim-sandbox
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Yeni kurulumda şablonları kopyalayın ve gerçek değerlerle düzenleyin:

cp .env.example .env
cp webhook.example.json webhook.json
cp nowcast-geo-alarm-filter.example.json nowcast-geo-alarm-filter.json
cp nowcast-geo-alarm-registrations.example.csv nowcast-geo-alarm-registrations.csv

CSV biçimi

Girdi UTF-8 ve noktalı virgül ayracına sahip olmalıdır:

city;district;recipientId
Ankara;Çankaya;recipient-001
İstanbul;Kadıköy;recipient-002

Script aynı dosyaya şu üç sonuç sütununu ekler veya mevcut değerlerini günceller:

city;district;recipientId;status;httpStatus;registrationId
Ankara;Çankaya;recipient-001;SUCCESS;HTTP_200;f7587d9e-2481-4b4c-818d-c8d1946851b7

• İl ve ilçe adları trim edilip Türkçe büyük/küçük harf kurallarıyla kesin eşleştirilir.
• Bulunamayan konumlar FAILED;NOT_SENT; olarak kaydedilir.
• Daha önce SUCCESS olmuş satırlar konsola bilgi yazılarak atlanır.
• Her satırdan sonra CSV aynı dizinde geçici dosyayla atomik olarak güncellenir.
• recipientId boş olamaz ve US-ASCII karakterlerinden oluşmalıdır.

İl ve ilçe sorgu cache'i

Şehir listesi her script çalıştırmasında yalnızca bir kez API'den alınır ve isim-ID eşleştirmesi bellekte tutulur. İlçe listesi de her benzersiz şehir için yalnızca ilk karşılaşmada alınır; aynı şehirdeki sonraki CSV satırlarında bellekteki sonuç kullanılır. Cache diske yazılmaz ve script kapandığında temizlenir.

Webhook yapılandırması

webhook.json içindeki authentication.selected şu değerlerden biri olmalıdır:

• BASIC
• JWT_TOKEN
• API_KEY
• HMAC_SIGNATURE

Yalnızca seçilen seçeneğin options altındaki alanları API'ye gönderilir. İlk initialization isteğinde tam webhook config gönderilir ve accountId kesinlikle gönderilmez. İlk başarılı kayıttan sonra .env içindeki IKLIM_WEBHOOK_INITIALIZED=true yapılır. Sonraki kayıtlar webhook altında yalnızca API'nin /v1/users/me yanıtındaki account.id değerini gönderir. Webhook'u yeniden tanımlamak için bu değeri elle false yapın.

Test/prod ortamını veya kullanıcı hesabını değiştirirken de yeni ortamın webhook'u ilk kayıtla tanımlayabilmesi için IKLIM_WEBHOOK_INITIALIZED=false yapın.

Nowcast geo alarm filter yapılandırması

Tüm CSV satırlarına uygulanacak ortak nowcast filtreleri nowcast-geo-alarm-filter.json içinde tutulur. Yıldırım, thunderstorm ve yağış filtrelerinden ihtiyaç duyulmayan nesneler dosyadan çıkarılabilir. API isteğindeki alan adı doküman gereği yine filter olarak gönderilir.

Otomatik authentication

Ortak istemci her yetkili istekten önce access token'ı kontrol eder:

1. Access token yoksa .env kullanıcı bilgileriyle login olur.
2. Access token'ın bitmesine 60 saniyeden az kaldıysa geçerli refresh token ile yeniler.
3. Refresh token yoksa/geçersizse yeniden login olur.
4. Sunucu 401 döndürürse refresh veya login yapıp isteği bir kez daha gönderir.
5. Yeni tokenları ve JWT exp değerlerini .env dosyasına kaydeder.

Yetkili isteklerde Authorization: Bearer <accessToken> ile HMAC başlıkları birlikte gönderilir. Tokenlar ve parolalar konsola yazılmaz.

Retry davranışı

Ağ hataları ile 429, 500, 502, 503 ve 504 yanıtları ilk istekten sonra en fazla üç kez, varsayılan olarak 2, 4 ve 8 saniye beklenerek tekrar edilir. 429 yanıtındaki Retry-After varsa ona uyulur. Bir operasyonun retry isteklerinde aynı idempotency key; yeni timestamp, nonce ve HMAC imzası kullanılır.

Belirsiz sonuç veya 409 sonrasında kayıt recipientId ile sorgulanır. Kayıt bulunursa registrationId kurtarılır ve satır SUCCESS yapılır.

Debug HTTP logları

Her çalıştırmada maskelenmiş HTTP istek ve yanıtları aşağıdaki dosyaya yazılır:

logs/iklim-api-debug.log

Log; istek metodu, URL, deneme numarası, başlıklar, istek gövdesi, HTTP durum kodu, yanıt başlıkları ve yanıt gövdesini içerir. Parola, kullanıcı adı, JWT, refresh token, API key, webhook secret, Authorization, cookie ve X-Signature değerleri maskelenir. Dosya 5 MB'a ulaştığında döndürülür ve en fazla üç eski dosya tutulur. Başarılı API yanıtındaki warning/warnings alanları ayrıca konsola yazılır.

Çalıştırma

Manuel login:

python login.py

CSV registration:

python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv

Farklı config dosyaları vermek için:

python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv \
  --webhook-config another-webhook.json \
  --nowcast-filter-config another-nowcast-geo-alarm-filter.json \
  --debug-log logs/custom-debug.log