Product3 dk okuma

Idempotency-Key: PDF işleri için güvenli yeniden denemeler

POST /api/v1/ işlerinde Idempotency-Key gönderin. PDF123 başarılı yanıtları 24 saat süreç belleğinde önbelleğe alır; Idempotency-Replayed: true tekrarı önler.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: PDF işleri için güvenli yeniden denemeler

Ağ zaman aşımları ve istemci yeniden denemeleri çok parçalı PDF yüklemeleri için olağandır. Bir idempotency anahtarı olmadan ikinci bir POST aynı birleştirmeyi, OCR’ı veya sıkıştırmayı sıfırdan yeniden çalıştırır; yükleme ve işleme süresi boşa tekrarlanır. Idempotency-Key ile PDF123 ilk başarılı yanıtı yeniden oynatabilir.

Ara yazılım ne yapar

pdfx-server içindeki sunucu ara yazılımı yalnızca değiştirici çağrılara uygulanır: /api/v1/ altındaki yollara yapılan POST istekleri (/api/v1/pipeline dahil). GET ve diğer yöntemler değişmeden geçer. İstekte Idempotency-Key başlığı yoksa (veya kırpma sonrası boşsa), işlem normal şekilde çalışır ve önbellek araması yapılmaz.

Başlık mevcut olduğunda:

  1. Depo, girdiyi asıl + anahtar ile anahtarlar. Asıl, X-API-KEY’den (key:… olarak), yoksa Authorization’dan (auth:… olarak), yoksa birebir anon değerinden türetilir. Bu iki değer (SHA-256 ile) eşleme anahtarına hashlanır; istek gövdesi anahtarın parçası değildir.
  2. 24 saat içindeki bir önbellek isabetinde ara yazılım, saklanan durumu, içerik türünü, içerik düzenini ve gövdeyi döndürür ve Idempotency-Replayed: true koyar.
  3. Bir isabetsizlikte istek ilerler. Yalnızca başarılı yanıtlar arabelleğe alınır ve saklanır (başarısız yanıtlar yeniden oynatma için önbelleğe alınmaz).
  4. Yanıt gövdeleri, bir yeniden oynatmanın dosya baytlarını yeniden gönderebilmesi için 100 MiB’ye kadar arabelleğe alınır. Arabelleğe alınamayan bir gövde önbelleği sessizce atlamaz: o istek HTTP 500 döndürür; yani sınırı aşan bir yanıt önbelleğe alınmadan geçmek yerine başarısız olur.

Başarısız işleri aynı anahtarla yeniden denemek güvenlidir: başarısızlıklar saklanmadığı için sonraki deneme başarılı olabilir ve ardından önbelleğe alınan sonuç hâline gelir. Bir anahtarı farklı bir dosya veya parametre için yeniden kullanmayın; önbellek gövdeyi değil, yalnızca asıl ve anahtarı hashlar. Ne API anahtarını ne de Authorization’ı paylaşan iki çağırıcı kazara çakışamaz; anonim çağırıcılar anon aslını paylaşır, bu yüzden farklı anahtarlar seçmelidir.

Nasıl gönderilir

Mantıksal iş başına kararlı, opak bir dize seçin (UUID uygundur):

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

Anonim ve API anahtarlı çağırıcıların ikisi de çalışır. Filigranı sonra sıkıştırmayı zincirleyen ardışık düzenler, yine de yinelenmesini istediğiniz her HTTP isteği için bir anahtar göndermelidir: bunları ayrı ayrı POST ediyorsanız her adım için, tek bir /api/v1/pipeline çağrısı için bir anahtar.

Araç sayfalarındaki tarayıcı tek seferlik işleri (Compress, OCR, …) sizden bir anahtar uydurmanızı istemez; başlık yeniden deneyen istemciler için önemlidir. /skills/pdf123.md adresinde yayımlanan beceri de aynı nedenle bir ardışık düzen örneğinde Idempotency-Key gösterir.

İşe yarayan istemci kalıpları

  • Anahtarı ilk POST’tan önce üretin; aynı mantıksal iş için zaman aşımı yeniden denemelerinde onu yeniden kullanın.
  • Başarıda, bu yanıtın önbellekten mi geldiğini yoksa işlemi yeniden mi çalıştırdığını bilmeniz gerekiyorsa Idempotency-Replayed: true olup olmadığına bakın.
  • Dosya, işlem veya parametreler değiştiğinde anahtarı değiştirin; asıl aynı kalsa bile.
  • /api/v1/pipeline için bir anahtar, iç adımların her birini değil, tüm pipeline POST’unu kapsar.

Yeniden oynatma ne değildir

Yeniden oynatma dayanıklı bir iş kuyruğu değildir. Depo, 24 saatlik TTL ile süreç yereldir (mutex arkasında bir HashMap). Süre dolduktan sonra veya bellek içi haritayı düşüren bir süreç yeniden başlatmasından sonra aynı anahtar işlemi yeniden çalıştırır. Çok örnekli kurulumlar, önüne paylaşılan bir depo koymadıkça bu haritayı paylaşmaz; bugünkü ara yazılım süreç başına çalışır.

Idempotency-Replayed: true değerini, bu yanıtın önbellekten geldiğinin kanıtı olarak alın, kalıcı bir defter olarak değil. PDF’nin yeniden işlendiği anlamına gelmez ve TTL’i uzatmaz.

Daha fazla yüzey ayrıntısı: Geliştiriciler ve Yapay zeka ajanları için. Compress gibi araç sayfaları, anahtar uydurmadan tek seferlik tarayıcı işleri için kullanılabilir kalır.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool