Repository navigation
SDK Cluster ve Bulk
English · Türkçe · Languages / Diller
Kapsam: JSON API Forge 0.5.1 · İnceleme: 17 Eylül 2026 · Dil: Türkçe
Cluster istemcisi aynı mantıksal hizmetin birkaç endpoint'i arasında seçim yapar. Sunucuları replike etmez, veritabanlarını senkronize etmez ve uygulama state'ini başka bölgeye taşımaz. Failover'ın güvenli olması, deployment'ların eşdeğer sözleşme ve veri tutarlılığına bağlıdır.
import os
from json_api_forge import ForgeCluster, ForgeEndpoint, RoutingStrategy, CircuitBreakerPolicy
endpoints = [
ForgeEndpoint("region-a", "https://a.example.com", api_key=os.environ["REGION_A_KEY"]),
ForgeEndpoint("region-b", "https://b.example.com", api_key=os.environ["REGION_B_KEY"]),
]
with ForgeCluster(
endpoints,
strategy=RoutingStrategy.RENDEZVOUS,
circuit_breaker=CircuitBreakerPolicy(failure_threshold=3, recovery_seconds=15),
) as cluster:
response = cluster.request(
"GET", "api/wiki-demo/v1/items",
routing_key="tenant-42", params={"limit": 20},
)ROUND_ROBIN varsayılandır. RENDEZVOUS, routing key + endpoint adına göre kararlı sıralama üretir; weight skoru etkiler. Endpoint isimleri benzersiz olmalıdır. Endpoint ekleme/çıkarma ve devre durumu hedef seçimini değiştirebilir. Routing key tenant yetkilendirmesi değildir.
Transport hatası ve HTTP >=500 cluster retryable hata sayılır. Uygulama istemcisinin RetryPolicy status listesi farklıdır; 429'un client retry ile cluster failover'da aynı işlendiğini varsaymayın.
Circuit, ardışık hata eşiğinde açılır; recovery süresinden sonra endpoint tekrar aday olabilir. Bütün devreler açık olduğunda kod en eski açılan endpoint'i prob olarak seçebilir. "Hiçbir çağrı gönderilmez" garantisi yoktur.
GET/HEAD/OPTIONS/PUT/DELETE method açısından failover'a izinlidir; diğer method'lar idempotency_key ister. Tek request ID endpoint denemeleri arasında korunur. İstemci katmanına ayrıca RetryPolicy eklerseniz toplam deneme ve timeout bütçesi katlanabilir.
Yan etkili failover için hedeflerin aynı mantıksal iş ve idempotency durumunu görmesi gerekir. Ayrı DB'li iki region, aynı key'i ayrı ayrı işleyebilir. SDK bunu distributed transaction'a dönüştürmez.
ForgeCluster.bulk_create(project, resource, payloads, max_workers=8, max_items=10000, ...) her öğe için ayrı sonuç üretir. Sonuçlar giriş sırasına göre BulkResult(index, value, error) nesneleridir. succeeded, error'ın boş olup olmadığını gösterir. Maksimum worker 64, ayarlanabilir input tavanı 100000'dir.
Bu işlem tek DB transaction'ı değildir. Kısmen başarısız bulk'ta sadece başarısız öğeleri ve güvenli idempotency sözleşmesini dikkate alın; bütün listeyi körlemesine tekrar göndermeyin.
async def run_jobs(cluster, commands):
jobs = [
lambda command=command: cluster.call_operation(
"wiki-demo", "items.rename", command["payload"],
idempotency_key=command["key"],
)
for command in commands
]
return await cluster.bulk(jobs, concurrency=8, max_items=500)AsyncForgeCluster.bulk awaitable üreten callable'lar alır. lambda command=command döngüde yanlış son elemanı yakalamayı önler. Varsayılan concurrency 16, üst sınır 256'dır. Sync taraftaki bulk_create ile async taraftaki bulk aynı imza değildir.
health_all her endpoint için response veya exception döndürür. Bu çağrı sürekli arka plan monitor oluşturmaz. Kapanışta cluster'ın sahip olduğu istemciler kapatılır. Tam imzalar cluster referansında bulunur.
Bu sayfa aşağıdaki sabit commitlerdeki davranışı açıklar. Yeni bir sürümde aynı davranışın sürdüğünü varsaymayın.