SDK ya TypeScript kwa PDF API: Dakika Tano hadi Simu ya Kwanza, na Kinachobaki Kwako

Unapoita PDF API kutoka Node, kifurushi cha zana za usanidi (SDK) cha @pdf123/sdk hukamata jina la zana au kigezo kilichoandikwa vibaya kabla ya faili lolote kupakiwa. Hakijaribu tena, hakighairi kwa niaba yako, wala hakitiririshi matokeo. new Pdf123Client() huelekeza bila utambulisho kwenye https://pdf123.xyz kwa chaguo-msingi; faili zako hupakiwa huko na kuchakatwa huko, kwa sababu hakuna injini ya ndani.

PDF mbili kwenye folda zinatosha kuunganisha

Unahitaji Node 20.3 au mpya zaidi, au Bun. Kifurushi ni moduli ya ES: weka msimbo kwenye faili ya .mjs, au endesha npm pkg set type=module kwanza. Weka a.pdf na b.pdf kwenye saraka ya sasa.

npm install @pdf123/sdk

// merge.mjs
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const merged = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
console.log(await saveResult(merged, { output: "merged.pdf" }));

Baada ya node merge.mjs, terminali huchapisha njia ya matokeo uliyoipitisha, merged.pdf, na faili iko kwenye saraka ya sasa. readFileInput na saveResult ziko katika @pdf123/sdk/node. Kiingilio cha mzizi kinategemea fetch pekee na hupokea ingizo kama { name, data } ya kawaida, kwa hiyo mazingira yasiyo na mfumo wa faili yanaweza kutumia mteja huyo huyo. Matokeo ni { data, contentType, filename, json }; data ni Uint8Array nzima, na Buffer.from(result.data) hukupa Buffer.

Unganisha PDF ni moja tu kati ya zana.

Faili hurudi katika data, ripoti katika json

Kila zana ni client.run(toolName, { input, params }). Msimbo ulio hapa chini unaendeleza merge.mjs ya sehemu iliyotangulia, ukiwa na client na saveResult tayari kwenye wigo. Mahali pa kusoma matokeo hutegemea sehemu ya returns kutoka getTool, ambayo ni "file" au "json": tumia data kwa ya kwanza, json kwa ya pili.

import { getTool } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

// client comes from merge.mjs in the previous section
const marked = await client.run("watermark", {
  input: await readFileInput("a.pdf"),
  params: { watermarkText: "DRAFT", fontSize: 40 },
});
console.log(await saveResult(marked, { output: "marked.pdf" }));

const info = await client.run("get-info", { input: await readFileInput("a.pdf") });
console.log(info.json.FileSize, info.json.Encrypted);
console.log(getTool("get-info")?.returns); // "json"

Kizuizi cha kwanza huandika faili yenye alama ya maji kwenye marked.pdf; katika cha pili, info.json ndiyo ripoti. Huhitaji kukariri majina ya sehemu, thamani chaguo-msingi wala thamani zinazoruhusiwa: getTool("watermark")?.fields ndiyo katalogi hiyo, na pdfx describe watermark kwenye mstari wa amri husoma ile ile. TOOLS ina zana zote 95. Rejea kamili iko katika mwongozo wa SDK kwenye ukurasa wa watengenezaji.

Ili kuunganisha, kisha kuweka alama ya maji, kisha kubana, unaweza kutumia pipeline au simu tatu za run mfululizo; chaguo hutegemea kama unataka faili za kati. Hapa pia inaendeleza client ya juu. pipeline hukunja hatua hizo tatu kuwa ombi moja, matokeo ya kati hubaki kwenye seva, na mwitaji hupata hatua ya mwisho tu, ambayo msimbo ulio hapa chini huandika kwenye out.pdf. Ukitaka faili ya kila hatua, ziite kando kando.

const result = await client.pipeline(
  [{ tool: "merge" }, { tool: "watermark", params: { watermarkText: "DRAFT" } }, { tool: "compress" }],
  [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
);
console.log(await saveResult(result, { output: "out.pdf" }));

Mnyororo una hatua zisizozidi 8. Hatua ya 9 hupata HTTP 400: at most 8 pipeline steps allowed.

Bila utambulisho, kwa ufunguo, au ukielekezwa kwenye seva yako

Ikiwa umeweka PDFX_API_BASE lakini bado unafika https://pdf123.xyz, ni kwa sababu new Pdf123Client() haisomi vigeu vya mazingira; hutazama chaguo za kijenzi chake pekee.

Kwa simu zisizo na utambulisho, tumia kijenzi hicho kama kilivyo. Kwa ufunguo, andika new Pdf123Client({ apiKey: process.env.PDFX_API_KEY }); kichwa cha ombi ni X-API-KEY.

Ili kuelekeza kwenye seva yako, tumia clientFromEnv() kutoka @pdf123/sdk/node. Husoma PDFX_API_BASE na PDFX_API_KEY. Unaweza pia kuandika moja kwa moja new Pdf123Client({ baseUrl: "http://localhost:8080" }). Anwani isipofikika, simu hushindwa; hakuna hali ya nje ya mtandao. Unachopata na gharama yake faili zikibaki kwenye mtandao wako mwenyewe vimeelezwa katika Kujipangisha Hukupa Nini Hasa (na Kunagharimu Nini).

Kigezo kisicho sahihi hukamatwa kabla ya upakiaji

Bila hili, faili ingepakiwa kwanza na jina la sehemu lililoandikwa vibaya lingeonekana tu kama 400 kutoka kwa seva. Aina za vigezo vya kila zana huzalishwa kutoka katalogi, kwa hiyo makosa matatu ya kawaida hushindwa katika hatua ya tsc:

Simu sahihi kama { angle: 90 } au { watermarkText: "DRAFT", fontSize: 30 } hukusanywa bila tatizo. Sehemu za nambari hukubali nambari na maandishi, kwa hiyo fontSize: 30 na fontSize: "30" ni sawa. Mradi usiotumia TypeScript hupata makosa yale yale wakati wa utekelezaji, na ombi halitumwi kamwe: kesi ya tatu hutoa Field "angle" of "rotate" must be one of: 90, 180, 270, na jina la zana lililoandikwa vibaya hutoa unknown_tool, huku majina yanayofanana yakiorodheshwa ndani ya ujumbe.

Seva inapokataa, tawanya kwa reason

Seva inapokataa ombi, SDK hutupa Pdf123Error yenye status, code, reason na problem.hint. code moja inaweza kuwa na thamani kadhaa za reason, kwa hiyo angalia reason kwanza kisha rudi kwenye code. Hitilafu tatu za kawaida, zilizoendeshwa ndani ya mashine kwa ingizo lile lile, zinaonekana hivi:

import { Pdf123Client, Pdf123Error } from "@pdf123/sdk";
import { readFileInput } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const input = await readFileInput("locked.pdf");
try {
  await client.run("compress", { input });
} catch (error) {
  if (!(error instanceof Pdf123Error)) throw error;
  console.error(error.status, error.code, error.reason, error.problem?.hint);
  if (error.reason === "password_required") {
    await client.run("compress", { input, password: "secret" });
  }
}

Unapojua nenosiri, pitisha password kwa faili moja; kufungua na zana lengwa hufanyika katika ombi lile lile. Kwa faili iliyoharibika, jaribu Rekebisha PDF kwanza.

"Hakuna matokeo" lazima litofautishwe. PDF kuwa CSV isipopata jedwali kwenye PDF, seva hurudisha 204 na SDK hutupa code: "no_content"; sababu iko katika Utoaji wa Jedwali Tupu (204): PDF Yako Huenda Haina Safu. Zana za vichujio vya masharti huchukulia sharti lisilotimia kama matokeo ya kawaida: hazitupi hitilafu, na hurudisha matched: false pamoja na data tupu.

Kujaribu tena, kumbukumbu na kughairi ni kazi ya mwitaji

Hitilafu za mtandao na majibu ya 5xx hutupwa kama yalivyo; SDK haijaribu tena yenyewe kamwe. Kwa ombi linalobadilisha hali, pitisha idempotencyKey yako mwenyewe: kutuma tena kwa ufunguo ule ule hurudisha matokeo ya kwanza badala ya kuchakata upya, na utaratibu na mipaka viko katika Idempotency-Key: Majaribio Salama kwa Kazi za PDF. Matokeo husomwa kwenye kumbukumbu yakiwa mazima, bila kutiririshwa. Ingizo na pato vikiwa vikubwa, hesabu kumbukumbu wanazochukua kwa wakati mmoja.

Kughairi na muda kuisha ni thamani mbili tofauti za code, na simu moja huripoti ile tu inayotokea kwanza. Mfano ufuatao unazijaribu kwa simu mbili tofauti, ili matawi yote mawili yaweze kuendeshwa kweli:

import { Pdf123Client, Pdf123Error } from "@pdf123/sdk";
import { readFileInput } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const input = await readFileInput("a.pdf");

const controller = new AbortController();
setTimeout(() => controller.abort(), 10_000);
try {
  await client.run("compress", { input, signal: controller.signal });
} catch (error) {
  if (error instanceof Pdf123Error && error.code === "cancelled") { /* ulighairi mwenyewe */ }
}

try {
  await client.run("compress", { input, timeoutMs: 60_000 });
} catch (error) {
  if (error instanceof Pdf123Error && error.code === "timeout") { /* timeoutMs imepitwa; hakuna signal safari hii */ }
}

Ishara ya kukatiza (AbortSignal) inapotolewa, ombi hukataliwa mara moja kwa code: "cancelled"; muda ukipitwa hutoa code: "timeout". Kila ombi lina muda wa kuisha wa dakika 5 kwa chaguo-msingi, unaoweza kubadilisha unapounda mteja au kubatilisha kwa kila simu kwa timeoutMs. Katika upakiaji wa vipande, kila ombi hubeba muda huo peke yake. Kughairi hufunga muunganisho huu tu; hakuna hakikisho kwamba seva inaacha kuchakata.

Faili moja ikishindwa, zilizobaki zinaendelea, na simu za kurudi huja kwa mpangilio wa kukamilika

Kwa kundi la ingizo kwa zana ya faili moja, tumia runBatch. Faili moja ikishindwa, zingine huendelea. onResult huitwa mara faili inapokamilika, kwa hiyo huendeshwa kwa mpangilio wa kukamilika, na index ni nafasi ya faili katika safu ya ingizo; safu inayorudishwa iko kila mara kwa mpangilio wa ingizo. Andika baiti kwenye diski ndani ya kitendakazi hiki: retainData: false hufanya data kuwa tupu mara kitendakazi kinaporudi, kwa hiyo matokeo usiyoyafanyia saveResult hapa yamepotea. Ukatizo ukitokea, faili zilizokwisha andikwa hubaki.

Chukulia folda ina PDF tatu nzuri, a.pdf, b.pdf na locked.pdf iliyosimbwa (nenosiri secret), pamoja na faili iliyovunjika broken.pdf yenye herufi chache zilizoandikwa tu:

import { Pdf123Client } from "@pdf123/sdk";
import { fileSource, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const results = await client.runBatch("compress", [
  fileSource("a.pdf"), fileSource("broken.pdf"), fileSource("b.pdf"), fileSource("locked.pdf"),
], {
  concurrency: 2,
  passwordFor: (file) => (file.name === "locked.pdf" ? "secret" : undefined),
  onResult: async (entry, index) => {
    console.log(index, entry.input.name, entry.ok ? "ok" : entry.error.reason);
    if (entry.ok) await saveResult(entry.result, { output: "out/" });
  },
  retainData: false,
});

Kwa chaguo-msingi faili mbili huchakatwa kwa wakati mmoja; badilisha kwa concurrency. fileSource(path) husoma faili kutoka diski wakati zamu yake inapofika tu, kwa hiyo kundi kubwa la faili kubwa halijazwi lote kwenye kumbukumbu kwa mara moja. passwordFor huruhusu kundi lenye faili zilizofungwa na zisizofungwa kuendeshwa kwa mkupuo mmoja. Tulipoendesha faili hizo nne ndani ya mashine, simu ya kurudi ilipokea:

1 broken.pdf invalid_pdf
0 a.pdf ok
2 b.pdf ok
3 locked.pdf ok

Mpangilio wa kukamilika unaweza kutofautiana kila mara; hii ni jinsi mwendesho mmoja ulivyoonekana tu. retainData: false hufanya data katika safu iliyorudishwa kuwa tupu; faili zilizofanikiwa tayari ziliandikwa kwenye out/ na saveResult ya juu. Ukipitisha idempotencyKey kwa runBatch, ufunguo unaotumwa kwa kila faili ni <key>:<index>.

Upakiaji wa vipande huanza tu juu ya 95 MiB kwa jumla

Mwili wa ombi la moja kwa moja una kikomo cha 100 MiB, na kinachozidi hukataliwa; angalia maelezo katika Upakiaji wa PDF Kubwa Unapokataliwa: Kikomo cha 100 MiB cha Mwili wa Ombi na Hitilafu Inayokuelekeza Upande Usiofaa. Faili zote katika ombi moja zikijumlika kuzidi 95 MiB, SDK hubadilisha kwenda upakiaji wa vipande, na simu yako ya client.run haibadiliki. Kiwango cha juu cha chaguo-msingi cha seva kwa upakiaji mmoja ni 500 MiB; unapojipangisha, kirekebishe kwa PDFX_UPLOAD_MAX_BYTES.

Kwa operesheni hiyo hiyo iliyoandikwa kwa curl, MCP na mstari wa amri, tazama Operesheni Moja, Wateja Wanne: Kivinjari, curl, MCP, pdfx: chapisho hilo linaweka simu nne bega kwa bega, na hili linapanua SDK pekee. Ukurasa wa kifurushi kwenye npm ni @pdf123/sdk.