Πώς εγκαθιστώ το SDK;
Εγκαταστήστε το πακέτο με τον διαχειριστή πακέτων σας. Απαιτείται Node 20.3 ή νεότερο, Bun ή bundler. Οι τύποι TypeScript περιλαμβάνονται και το @types/node δεν χρειάζεται.
npm install @pdf123/sdkΤα bun add @pdf123/sdk και pnpm add @pdf123/sdk λειτουργούν με τον ίδιο τρόπο.
Πώς συγχωνεύω δύο PDF;
Δημιουργήστε έναν πελάτη, εκτελέστε το εργαλείο merge σε δύο αρχεία και αποθηκεύστε το αποτέλεσμα. Χωρίς επιλογές, ο πελάτης επικοινωνεί ανώνυμα με το δημόσιο API.
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";
const client = new Pdf123Client();
const result = await client.run("merge", {
input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
const path = await saveResult(result, { output: "merged.pdf" });
console.log(path);Το αποτέλεσμα περιέχει τα byte στο data, το contentType, το filename του διακομιστή και το json για εργαλεία που επιστρέφουν αναφορά. Η ίδια λειτουργία είναι διαθέσιμη στον ιστότοπο ως Συγχώνευση PDF.
Ποιο σημείο εισόδου να εισαγάγω;
| Σημείο εισόδου | Απαιτεί | Παρέχει |
|---|---|---|
@pdf123/sdk | Μόνο fetch | Pdf123Client, TOOLS, getTool, Pdf123Error και τα βοηθήματα του καταλόγου |
@pdf123/sdk/node | Node ή Bun | readFileInput, fileSource, saveResult, checkOutput και clientFromEnv |
Εισαγάγετε από το βασικό σημείο εισόδου σε προγράμματα περιήγησης και περιβάλλοντα edge, και προσθέστε το σημείο node μόνο εκεί όπου διαβάζετε ή γράφετε αρχεία.
Ποιες μεθόδους έχει ο πελάτης;
| Μέθοδος | Τι κάνει |
|---|---|
run(tool, { input, params }) | Εκτελεί ένα εργαλείο και επιστρέφει ένα αποτέλεσμα |
runBatch(tool, inputs, options) | Εκτελεί ένα εργαλείο ενός αρχείου σε πολλές εισόδους και επιστρέφει μία εγγραφή ανά είσοδο |
pipeline(steps, input, options) | Εκτελεί πολλά εργαλεία σε ένα αίτημα |
call(target, files, fields) | Στέλνει ανεπεξέργαστο αίτημα σε αναγνωριστικό εργαλείου, αναγνωριστικό λειτουργίας ή διαδρομή /api/... |
upload(file) | Ανεβάζει ένα αρχείο μέσω του API μεταφόρτωσης σε τμήματα και επιστρέφει το αναγνωριστικό του |
Τα βοηθήματα του καταλόγου είναι απλές συναρτήσεις: το TOOLS παραθέτει όλα τα εργαλεία, το getTool(id) επιστρέφει τα πεδία, τις προεπιλογές και τους αποδεκτούς τύπους αρχείων ενός εργαλείου, και τα toolGroup, toolSummary, matchesQuery και suggestTools βοηθούν στη δημιουργία επιλογέων εργαλείων. Η γραμμή εντολών τυπώνει τον ίδιο κατάλογο με τα pdfx list και pdfx describe.
Πώς περνώ επιλογές σε ένα εργαλείο;
Το params έχει τύπους ανά εργαλείο. Δέχεται μόνο τα πεδία του συγκεκριμένου εργαλείου και τα πεδία επιλογής δέχονται μόνο τις επιτρεπόμενες τιμές τους. Τα αριθμητικά πεδία ελέγχονται ως προς το ελάχιστο και το μέγιστο, και κάθε αρχείο ως προς τους αποδεκτούς τύπους, πριν ανέβει οτιδήποτε. Οι προεπιλογές που χρειάζεται ο διακομιστής συμπληρώνονται αυτόματα.
const marked = await client.run("watermark", {
input: await readFileInput("a.pdf"),
params: { watermarkText: "DRAFT", fontSize: 40, rotation: -45 },
});
await saveResult(marked, { output: "draft.pdf" });Μια κενή συμβολοσειρά σημαίνει «δεν έχει οριστεί», οπότε ισχύει η προεπιλογή. Δείτε την Προσθήκη υδατογραφήματος για το τι κάνει κάθε επιλογή.
Πώς επεξεργάζομαι πολλά αρχεία;
Το runBatch εκτελεί ένα εργαλείο ενός αρχείου, όπως η Συμπίεση, η Περιστροφή ή η Προσθήκη κωδικού, σε κάθε είσοδο με τις ίδιες επιλογές. Από προεπιλογή επεξεργάζεται δύο αρχεία τη φορά. Ένα προβληματικό αρχείο δεν σταματά ποτέ τα υπόλοιπα.
import { fileSource, saveResult } from "@pdf123/sdk/node";
const controller = new AbortController();
const entries = await client.runBatch("compress", [fileSource("a.pdf"), fileSource("b.pdf")], {
concurrency: 2,
signal: controller.signal,
onResult: async (entry, index) => {
if (entry.ok) await saveResult(entry.result, { output: "compressed/" });
},
});
console.log(entries.map((entry) => entry.ok));- Το
fileSource(path)είναι πηγή με αναβολή, που διαβάζεται μόνο όταν την αναλάβει ένας εργάτης, ώστε πολλά μεγάλα αρχεία να μην βρίσκονται ποτέ μαζί στη μνήμη. - Το
onResultλαμβάνει κάθε αποτέλεσμα μόλις ολοκληρωθεί. Αποθηκεύστε το εκεί και, αν ακυρώσετε στο αρχείο 50 από τα 100, θα διατηρηθούν τα πρώτα 49. ΜεretainData: false, ο πίνακας που επιστρέφεται δεν κρατά τα byte. - Κάθε κλήση δέχεται
timeoutMsκαι έναsignalγια ακύρωση. - Το
idempotencyKeyγίνεται<key>:<index>για κάθε αρχείο.
Τα εργαλεία φίλτρου (αναγνωριστικά που αρχίζουν με filter-) επιστρέφουν matched: false αντί να ρίξουν σφάλμα όταν δεν ισχύει η συνθήκη τους. Σε παρτίδα, ένα τέτοιο αρχείο εξακολουθεί να μετρά ως ok.
Πώς αλυσοδένω εργαλεία σε ένα αίτημα;
Το pipeline στέλνει μια λίστα βημάτων και μία ή περισσότερες εισόδους. Ο διακομιστής περνά την έξοδο κάθε βήματος στο επόμενο.
const piped = await client.pipeline(
[{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
[await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
await saveResult(piped, { output: "out.pdf" });Τα pipelines δέχονται τις ίδιες επιλογές κωδικού με το run.
Πώς δουλεύω με κρυπτογραφημένα PDF;
Περάστε το password στο run για να ανοίξετε πρώτα μια κρυπτογραφημένη είσοδο. Το ξεκλείδωμα και το εργαλείο εκτελούνται σε ένα αίτημα. Για εργαλεία που δέχονται πολλά αρχεία, όπως η Συγχώνευση, περάστε το passwords με μία εγγραφή ανά είσοδο, χρησιμοποιώντας κενή συμβολοσειρά για ανοιχτό αρχείο. Κάθε αρχείο ξεκλειδώνεται ξεχωριστά.
await client.run("compress", { input: await readFileInput("locked.pdf"), password: "secret" });
await client.run("merge", {
input: [await readFileInput("locked.pdf"), await readFileInput("open.pdf")],
passwords: ["secret", ""],
});Για παρτίδα, το passwordFor(file, index) επιστρέφει τον κωδικό κάθε εισόδου. Για να αφαιρέσετε την προστασία μόνιμα, χρησιμοποιήστε το εργαλείο Αφαίρεση κωδικού.
Πώς λειτουργούν τα σφάλματα;
Οι αποτυχίες ρίχνουν Pdf123Error. Διαθέτει status (undefined όταν δεν υπήρξε απάντηση), code, reason για την αναλυτική αιτία, όπως password_required, και problem με τις λεπτομέρειες προβλήματος του διακομιστή, που περιλαμβάνουν hint όταν υπάρχει. Τα σφάλματα επικύρωσης ρίχνονται πριν ανέβει οτιδήποτε.
import { Pdf123Error } from "@pdf123/sdk";
try {
await client.run("compress", { input: await readFileInput("locked.pdf") });
} catch (error) {
if (error instanceof Pdf123Error) {
console.error(error.status, error.code, error.reason, error.problem?.hint);
} else {
throw error;
}
}Οι κωδικοί του διακομιστή παρατίθενται στους Κωδικούς σφαλμάτων. Ο πελάτης προσθέτει τους δικούς του κωδικούς:
| Κωδικός | Σημασία |
|---|---|
network_error | Το αίτημα δεν έλαβε απάντηση |
timeout | Ένα αίτημα ξεπέρασε το timeoutMs |
cancelled | Το signal σας ακύρωσε την κλήση |
input_unreadable | Δεν ήταν δυνατή η ανάγνωση μιας τοπικής διαδρομής |
output_unwritable | Δεν ήταν δυνατή η αποθήκευση του αποτελέσματος στη διαδρομή που δόθηκε |
output_mismatch | Το saveResult αρνήθηκε να γράψει ένα ZIP με όνομα .pdf |
unsupported_file_type | Ο τύπος αρχείου δεν γίνεται δεκτός από το εργαλείο |
unknown_tool | Το αναγνωριστικό εργαλείου δεν υπάρχει· το μήνυμα προτείνει παρόμοια αναγνωριστικά |
invalid_target | Το call απέρριψε διαδρομή /api/... με τμήματα .., . ή κενά |
no_content | Το εργαλείο δεν είχε τίποτα να επιστρέψει (HTTP 204) |
Το saveResult δεν αντικαθιστά ποτέ αρχείο μέσα σε κατάλογο. Καλέστε πρώτα το checkOutput(output, { several }) για να μάθετε, πριν ανέβει οτιδήποτε, αν μπορεί να γραφτεί μια διαδρομή.
Ποιες ρυθμίσεις TypeScript και ενοτήτων λειτουργούν;
Οι τύποι επιλύονται με τις ρυθμίσεις moduleResolution nodenext, node16, bundler και το παλαιότερο node10, συμπεριλαμβανομένης της υποδιαδρομής @pdf123/sdk/node. Το πακέτο είναι ενότητα ES, οπότε το import λειτουργεί παντού. Το require("@pdf123/sdk") από CommonJS λειτουργεί σε Node 22.12 ή νεότερο και δεν είναι διαθέσιμο σε Node 20.
Πώς ρυθμίζω τον πελάτη;
| Επιλογή | Μεταβλητή περιβάλλοντος | Προεπιλογή |
|---|---|---|
baseUrl | PDFX_API_BASE | https://pdf123.xyz |
apiKey | PDFX_API_KEY | καμία, ανώνυμα |
timeoutMs | καμία | 300000 |
Το new Pdf123Client() δεν διαβάζει ποτέ το περιβάλλον. Το clientFromEnv() από το @pdf123/sdk/node διαβάζει τις δύο μεταβλητές, και οι επιλογές που περνάτε υπερισχύουν. Το κλειδί στέλνεται ως κεφαλίδα X-API-KEY· δείτε την Ταυτοποίηση.
Για να χρησιμοποιήσετε τον δικό σας διακομιστή, ορίστε το baseUrl στη διεύθυνσή του, για παράδειγμα http://localhost:8080. Δείτε την Αυτοφιλοξενία.
Μπορώ να χρησιμοποιήσω το SDK σε πρόγραμμα περιήγησης;
Ναι. Το βασικό σημείο εισόδου @pdf123/sdk χρειάζεται μόνο fetch και δεν έχει εξαρτήσεις από το Node. Δημιουργήστε μόνοι σας αντικείμενα FileInput από ένα File ή ένα Uint8Array, γιατί τα βοηθήματα αρχείων βρίσκονται στο σημείο εισόδου node. Μην συμπεριλαμβάνετε κλειδί API σε κώδικα προγράμματος περιήγησης που μπορούν να διαβάσουν άλλοι.
Σχετικές σελίδες
- Επισκόπηση για προγραμματιστές, με το REST API και την ταυτοποίηση
- Γραμμή εντολών pdfx, χτισμένη πάνω σε αυτό το SDK
- Διακομιστές MCP για πράκτορες AI
- Swagger UI και το έγγραφο OpenAPI
- Σελίδες εργαλείων: Συγχώνευση, Διαχωρισμός, Συμπίεση, OCR, Προσθήκη κωδικού
Συχνές ερωτήσεις
Χρειάζεται το SDK κλειδί API;
Όχι. Ένας πελάτης που δημιουργείται χωρίς επιλογές καλεί το δημόσιο API ανώνυμα. Περάστε το apiKey για να σταλεί η κεφαλίδα X-API-KEY.
Ποια έκδοση του Node χρειάζεται το SDK;
Node 20.3 ή νεότερο, ή Bun. Το βασικό σημείο εισόδου χρειάζεται μόνο fetch, οπότε λειτουργεί και σε προγράμματα περιήγησης και bundlers.
Πώς χρησιμοποιώ ένα εργαλείο που είναι νεότερο από το SDK;
Χρησιμοποιήστε το client.call. Δέχεται αναγνωριστικό εργαλείου, αναγνωριστικό λειτουργίας όπως το general/merge-pdfs ή διαδρομή /api/..., μαζί με αρχεία και πεδία. Τίποτα δεν επικυρώνεται και καμία προεπιλογή δεν συμπληρώνεται τοπικά.
Πόσο μεγάλο αρχείο μπορώ να ανεβάσω;
Είσοδοι άνω των 95 MB συνολικά περνούν αυτόματα από το API μεταφόρτωσης σε τμήματα. Το σώμα ενός άμεσου αιτήματος περιορίζεται στα 100 MiB.
Γιατί η κλήση μου έριξε σφάλμα για ένα PDF χωρίς πίνακες;
Εργαλεία όπως τα pdf-to-csv και pdf-to-xlsx απαντούν χωρίς περιεχόμενο όταν το PDF δεν έχει εντοπίσιμο πίνακα. Το SDK ρίχνει Pdf123Error με τον κωδικό no_content αντί να επιστρέψει κενό αρχείο. Ελέγξτε αυτόν τον κωδικό αν ένα κενό αποτέλεσμα είναι αποδεκτό.