Product3 λεπ. ανάγνωση

Idempotency-Key: ασφαλείς επαναλήψεις για εργασίες PDF

Στείλτε Idempotency-Key σε POST /api/v1/. PDF123 κρατά επιτυχημένες απαντήσεις 24 ώρες σε μνήμη διεργασίας και θέτει Idempotency-Replayed: true, όχι νέα εκτέλεση.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: ασφαλείς επαναλήψεις για εργασίες PDF

Τα χρονικά όρια δικτύου και οι επαναλήψεις από τον πελάτη είναι φυσιολογικά για μεταφορτώσεις PDF με multipart. Χωρίς κλειδί ιδιομορφίας, ένα δεύτερο POST εκτελεί ξανά την ίδια συγχώνευση, το OCR ή τη συμπίεση από την αρχή, διπλασιάζοντας τη μεταφόρτωση και τον χρόνο επεξεργασίας. Με το Idempotency-Key, το PDF123 μπορεί να επαναλάβει την πρώτη επιτυχημένη απάντηση.

Τι κάνει το λογισμικό μεσολάβησης

Το λογισμικό μεσολάβησης του διακομιστή στο pdfx-server εφαρμόζεται μόνο σε μεταλλακτικές κλήσεις: POST σε διαδρομές κάτω από το /api/v1/ (μαζί με το /api/v1/pipeline). Τα GET και οι άλλες μέθοδοι περνούν αμετάβλητα. Αν το αίτημα δεν έχει κεφαλίδα Idempotency-Key (ή είναι κενή μετά την αφαίρεση κενών), η λειτουργία εκτελείται κανονικά χωρίς αναζήτηση στην προσωρινή αποθήκευση.

Όταν η κεφαλίδα υπάρχει:

  1. Η αποθήκη κλειδώνει την εγγραφή κατά ταυτότητα + κλειδί. Η ταυτότητα προκύπτει από το X-API-KEY (ως key:…), αλλιώς από το Authorization (ως auth:…), αλλιώς από το κυριολεκτικό anon. Οι δύο τιμές κατακερματίζονται (SHA-256) σε κλειδί χάρτη· το σώμα του αιτήματος δεν αποτελεί μέρος του κλειδιού.
  2. Σε επιτυχία στην προσωρινή αποθήκευση εντός 24 ωρών, το λογισμικό μεσολάβησης επιστρέφει την αποθηκευμένη κατάσταση, τον τύπο περιεχομένου, τη διάθεση περιεχομένου και το σώμα, και θέτει Idempotency-Replayed: true.
  3. Σε αποτυχία αναζήτησης, το αίτημα προχωρά. Μόνο οι επιτυχημένες απαντήσεις αποθηκεύονται προσωρινά (οι μη επιτυχημένες δεν αποθηκεύονται για επανάληψη).
  4. Τα σώματα απαντήσεων αποθηκεύονται προσωρινά έως 100 MiB, ώστε μια επανάληψη να μπορεί να ξαναστείλει τα bytes του αρχείου. Σώμα που δεν μπορεί να αποθηκευτεί προσωρινά δεν παρακάμπτει σιωπηλά την προσωρινή αποθήκευση: το αίτημα επιστρέφει HTTP 500, οπότε μια απάντηση πάνω από το όριο αποτυγχάνει αντί να περάσει χωρίς προσωρινή αποθήκευση.

Οι αποτυχημένες εργασίες είναι ασφαλείς για επανάληψη με το ίδιο κλειδί: επειδή οι αποτυχίες δεν αποθηκεύονται, η επόμενη προσπάθεια μπορεί να πετύχει και μετά να γίνει το αποθηκευμένο αποτέλεσμα. Μην ξαναχρησιμοποιείτε κλειδί για διαφορετικό αρχείο ή παραμέτρους· η προσωρινή αποθήκευση δεν κατακερματίζει το σώμα, μόνο την ταυτότητα και το κλειδί. Δύο καλούντες που δεν μοιράζονται ούτε κλειδί API ούτε Authorization δεν μπορούν να συγκρουστούν κατά λάθος· οι ανώνυμοι καλούντες μοιράζονται την ταυτότητα anon, οπότε πρέπει να διαλέγουν διακριτά κλειδιά.

Πώς να το στείλετε

Διαλέξτε σταθερή αδιαφανή συμβολοσειρά ανά λογική εργασία (ένα UUID αρκεί):

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

Οι ανώνυμοι καλούντες και αυτοί με κλειδί API λειτουργούν και οι δύο. Οι αγωγοί που αλυσοδένουν υδατογράφημα και μετά συμπίεση πρέπει πάλι να στέλνουν ένα κλειδί ανά αίτημα HTTP που θέλετε να αποδιπλοποιηθεί, είτε ένα για κάθε βήμα αν τα στέλνετε χωριστά, είτε ένα για μία κλήση στο /api/v1/pipeline.

Οι μεμονωμένες εργασίες στον φυλλομετρητή στις σελίδες εργαλείων (Συμπίεση, OCR κ.ά.) δεν απαιτούν να επινοήσετε κλειδί· η κεφαλίδα μετρά για πελάτες που επαναλαμβάνουν. Η δημοσιευμένη δεξιότητα στο /skills/pdf123.md δείχνει ένα Idempotency-Key σε παράδειγμα αγωγού για τον ίδιο λόγο.

Μοτίβα πελατών που λειτουργούν

  • Δημιουργήστε το κλειδί πριν από το πρώτο POST· ξαναχρησιμοποιήστε το στις επαναλήψεις λόγω χρονικού ορίου για την ίδια λογική εργασία.
  • Σε επιτυχία, ελέγξτε για Idempotency-Replayed: true αν θέλετε να ξέρετε αν η απάντηση ήρθε από την προσωρινή αποθήκευση ή εκτέλεσε ξανά τη λειτουργία.
  • Αλλάξτε το κλειδί όταν αλλάζει το αρχείο, η λειτουργία ή οι παράμετροι, ακόμη κι αν η ταυτότητα μένει ίδια.
  • Για το /api/v1/pipeline, ένα κλειδί καλύπτει ολόκληρο το POST του αγωγού, όχι κάθε εσωτερικό βήμα.

Τι δεν είναι η επανάληψη

Η επανάληψη δεν είναι ανθεκτική ουρά εργασιών. Η αποθήκη είναι τοπική στη διεργασία (HashMap πίσω από mutex) με διάρκεια ζωής 24 ώρες. Μετά τη λήξη, ή μετά από επανεκκίνηση της διεργασίας που χάνει τον χάρτη στη μνήμη, το ίδιο κλειδί εκτελεί ξανά τη λειτουργία. Οι αναπτύξεις με πολλές παρουσίες δεν μοιράζονται αυτόν τον χάρτη, εκτός αν βάλετε μπροστά κοινή αποθήκη· το σημερινό λογισμικό μεσολάβησης είναι ανά διεργασία.

Αντιμετωπίστε το Idempotency-Replayed: true ως απόδειξη ότι αυτή η απάντηση ήρθε από την προσωρινή αποθήκευση, όχι ως μόνιμο καθολικό μητρώο. Δεν σημαίνει ότι το PDF επεξεργάστηκε ξανά και δεν παρατείνει τη διάρκεια ζωής.

Περισσότερες λεπτομέρειες επιφάνειας: Προγραμματιστές και Φτιαγμένο για πράκτορες AI. Σελίδες εργαλείων όπως η Συμπίεση μένουν διαθέσιμες για μεμονωμένες εργασίες στον φυλλομετρητή χωρίς επινόηση κλειδιών.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool
Read next
Επεξεργασία κειμένου σε PDF online: διορθώστε το χωρίς το αρχείο προέλευσης
Κάντε κλικ σε μια γραμμή κειμένου σε ένα PDF, αλλάξτε την και κατεβάστε το αποτέλεσμα. Δεν ανεβαίνει τίποτα και δεν χρειάζεται σύνδεση. Επεξεργάζονται μόνο γραμμές κειμένου που υπάρχουν ήδη.
Πακέτο σάρωσης σε κείμενο: OCR και μετά συμπίεση του PDF που κρατάτε
Ένα πακέτο σάρωσης θέλει δύο βήματα: το OCR στο PDF123 επιστρέφει Markdown, ενώ η Συμπίεση μικραίνει το αρχικό PDF με επανασυμπίεση ροών. Δύο ξεχωριστές έξοδοι.
Τι είναι το PDF123: μια δωρεάν εργαλειοθήκη PDF που μπορείτε να φιλοξενήσετε και μόνοι σας
Το PDF123 είναι μια δωρεάν εργαλειοθήκη PDF στον φυλλομετρητή: και τα 56 εργαλεία, από τη συγχώνευση και τη συμπίεση έως το OCR και την κρυπτογράφηση, λειτουργούν χωρίς λογαριασμό. Οι ίδιες λειτουργίες εκτίθενται μέσω REST, MCP και του CLI pdfx, ή μπορείτε να φιλοξενήσετε ολόκληρη τη στοίβα και να κρατήσετε τα αρχεία στο δικό σας δίκτυο.