154 lines
5.7 KiB
Markdown
154 lines
5.7 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```csv
|
||
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:
|
||
|
||
```csv
|
||
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:
|
||
|
||
```text
|
||
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:
|
||
|
||
```bash
|
||
python login.py
|
||
```
|
||
|
||
CSV registration:
|
||
|
||
```bash
|
||
python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv
|
||
```
|
||
|
||
Farklı config dosyaları vermek için:
|
||
|
||
```bash
|
||
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
|
||
```
|