Kutumia pdfx kwenye Terminali na CI: Kutoka Amri ya Kwanza hadi Hati Inayotegemewa

Kabla ya kuweka pdfx kwenye hati au kwenye ujumuishaji endelevu (CI), kumbuka mambo mawili. Msimbo wa kutoka 0 haumaanishi kila mara kwamba faili iliandikwa: zana ya kichujio cha masharti isiyopata mlingano pia hutoka na 0. Na --json ina umbo tofauti kwa ingizo moja kuliko kwa ingizo kadhaa, kwa hiyo hati inayochanganua safu ya files pekee haipati kitu pale faili moja tu inapolingana. pdfx ni mteja wa HTTP: faili hupakiwa kwenye seva kuchakatwa, hakuna injini ya ndani, na hakuna hali ya nje ya mtandao. Rejea kamili ya amri iko katika mwongozo wa CLI kwenye ukurasa wa watengenezaji.

Isakinishe, kisha unganisha faili mbili

Unahitaji Node 20.3 au mpya zaidi, au Bun:

npm install -g @pdf123/cli
pdfx --version

Ikiwa hupendi kusakinisha kwa ujumla, weka npx @pdf123/cli mbele ya amri. Ukiwa na PDF mbili kwenye saraka ya sasa:

pdfx merge a.pdf b.pdf -o merged.pdf

Ikifanikiwa, pato la kawaida huchapisha merged.pdf. Hiyo ilikuwa Unganisha PDF. Kabla ya kubadilisha zana, omba sehemu badala ya kubahatisha majina ya vigezo:

pdfx describe watermark

Add Watermark (watermark) - Add text or image watermarks to PDF files
Input:    1 file (.pdf)
Result:   file
Fields:
  --watermarkText <value>  Watermark text [default: PDF123]
  --fontSize <number>      Font size [default: 30]
                           min 6, max 200

(Dondoo; sehemu zingine ni pamoja na --rotation, --customColor na nyinginezo.) Sehemu ni kigezo cha mstari wa amri tu:

pdfx watermark in.pdf --watermarkText DRAFT -o marked.pdf

pdfx list huorodhesha zana zote 95, --category security huorodhesha kundi moja tu, na --query watermark hutafuta kwa neno.

Faili nyingi huenda kwenye saraka, na faili zilizopo hazifutwi

Ipe zana ya faili moja ingizo kadhaa na kila faili huandikwa kwenye saraka iliyotajwa na -o mara tu inapokamilika, bila kusubiri hadi mwisho. Faili moja ikishindwa, zingine huendelea, na msimbo wa kutoka mwishoni mwa kundi ni 1.

pdfx compress a.pdf b.pdf -o small/

Pato la kawaida la mwendesho mmoja lilionekana hivi, na mpangilio unaweza kutofautiana kila mara:

a.pdf -> small/a.pdf
b.pdf -> small/b.pdf

Saraka iliyopo hufanya kazi kama ilivyo; saraka isipokuwepo bado, -o inahitaji / mwishoni, vinginevyo small huchukuliwa kama jina la faili. Bila -o, matokeo huwekwa kwenye saraka ya sasa chini ya jina ambalo seva inayapa; faili iliyopo haifutwi na mpya huitwa a-1.pdf, a-2.pdf. Jina maalum la faili (-o same.pdf) hubadilisha maudhui yaliyopo, kama ulivyoagiza. Kwa chaguo-msingi faili mbili huchakatwa kwa wakati mmoja; badilisha kwa --concurrency. Ukibonyeza Ctrl-C katikati ya kundi, faili zilizokwisha andikwa hubaki na msimbo wa kutoka ni 130.

Fungua faili iliyosimbwa kwa --input-password PASSWORD. Kundi likichanganya faili zilizofungwa na zisizofungwa, tumia --password-for FILE=PASSWORD, ambayo unaweza kurudia.

Ita zana kando kwa faili za kati, vinginevyo tumia pipeline

Ili kuunganisha, kisha kuweka alama ya maji, kisha kubana, usipohitaji matokeo ya kati kwenye diski, yakunje kuwa ombi moja kwa pipeline; faili za kati hazipakuliwi wala kupakiwa tena. Ukitaka faili ya kila hatua, ita zana kando kando. Pipeline hutoa faili moja.

pdfx pipeline a.pdf b.pdf --step merge --step compress -o merged-small.pdf

# When a step needs parameters, describe the steps in JSON
pdfx pipeline a.pdf b.pdf \
  --steps '[{"tool":"merge"},{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' \
  -o out.pdf

Pipeline ina hatua zisizozidi 8; hatua ya 9 hupata HTTP 400: at most 8 pipeline steps allowed. Zana inayohitaji faili ya pili (kwa mfano overlay-pdfs, inayoweka PDF nyingine juu) haiwezi kuwa hatua ya pipeline. pdfx huikataa kabla ya kupakia, kwa msimbo wa kutoka 2 na ujumbe Tool "overlay-pdfs" needs a second file and cannot run as a pipeline step.

Tumia ingizo la kawaida pale tu unapotaka kuunganisha amri na bomba. Hoja ya faili ya - husoma kutoka kwenye ingizo la kawaida, na -o - huandika matokeo kwenye pato la kawaida:

cat report.pdf | pdfx compress - -o - > report-small.pdf

Katika hali hii pato la kawaida hubeba baiti za faili pekee; ujumbe na hitilafu huenda kwenye hitilafu ya kawaida, kwa hiyo kuelekeza upya ni salama. Tuliangalia kwa PDF ya takriban KB 1: pato la kawaida lilikuwa na PDF ya baiti 1040, ukubwa uleule wa faili iliyoandikwa kwa -o, na hitilafu ya kawaida ilikuwa tupu. Unaposoma kutoka ingizo la kawaida bila kutoa -o, matokeo huitwa stdin.pdf, yakiandikwa kwenye saraka ya sasa pamoja na ujumbe kwenye hitilafu ya kawaida.

Hati zilinganishe na sababu, si ujumbe

Inaposhindwa, mbali na mstari mmoja wa ujumbe, hitilafu ya kawaida hubeba mistari mitatu: reason:, code: na hint:. Faili iliyosimbwa yenye nenosiri lisilo sahihi ilitoa hii ndani ya mashine:

pdfx: HTTP 400: The password is incorrect.
reason: wrong_password
code: bad_request
hint: Check the password and try again.

Njia unayopitisha nenosiri hubadilisha mstari wa kwanza wa ujumbe: unlock --password hutoa mstari ulio juu. Kwa --input-password kwenye zana nyingine, seva huchukulia kufungua kama hatua ya ndani na mstari wa kwanza ni HTTP 400: Pipeline step 0 (security/remove-password) failed: The password is incorrect., huku mstari wa reason: ukiwa wrong_password katika hali zote mbili. Bila nenosiri kabisa ujumbe ni This PDF is password-protected. Enter its password. na reason ni password_required. Hati inapaswa kulinganisha mstari wa reason:. code ni pana zaidi, na thamani ya kawaida ni bad_request.

Jina la zana lililoandikwa vibaya hutoka na 2, na ujumbe hupendekeza majina yanayofanana:

pdfx: Unknown tool "compres". Did you mean: compress, decompress-pdf? Run `pdfx list` to see all tools.

Aina ya matokeo inayopingana na jina la faili pia hutoka na 2, na hutokea kabla ya kitu chochote kuandikwa. Kuandika ZIP inayozalishwa na Gawanya PDF kwenye x.pdf:

pdfx: The result is application/zip but "x.pdf" has a .pdf extension; name it *.zip or write into a directory
code: output_mismatch

Muda kuisha pia hutoka na 1, huku code ikiwa timeout. Kipimo cha --timeout ni milisekunde na chaguo-msingi ni 300000, yaani dakika 5, kwa hiyo --timeout 60 inamaanisha milisekunde 60, si sekunde 60.

Sharti likiwa si kweli, msimbo wa kutoka bado ni 0

Aina moja ya zana hujibu swali la ndiyo au hapana: je, idadi ya kurasa ni kubwa kuliko N, je, faili ina maandishi fulani, je, faili ni kubwa kuliko ukubwa fulani. Jibu likiwa ndiyo, hurudisha faili ya ingizo bila kuibadilisha; likiwa hapana, havirudishi kitu, na pdfx huchapisha mstari no match na hutoka na 0. Zana hizi za vichujio zipo tu katika SDK, mstari wa amri na MCP; tovuti haina ukurasa wao.

Hii ni tofauti na aina nyingine ya matokeo matupu. PDF kuwa CSV isipopata jedwali kwenye PDF, seva hurudisha 204 na pdfx hutoka na 1 na kuripoti no_content: zana ililenga kuzalisha maudhui na haikuzalisha, na sababu iko katika Utoaji wa Jedwali Tupu (204): PDF Yako Huenda Haina Safu. Kwa zana ya kichujio, "hakuna mlingano" ndilo jibu iliyopaswa kutoa.

Ili kulisoma kwenye hati, tumia --json. Mlingano huchapisha faili iliyoandikwa; kutokuwa na mlingano huchapisha { "matched": false }:

# Match: the file is written, and its info is printed
$ pdfx filter-page-count three.pdf --pageCount 2 --comparator Greater --json -o big/
{ "path": "big/three.pdf", "contentType": "application/pdf", "bytes": 2594 }

# No match: no file is written
$ pdfx filter-page-count three.pdf --pageCount 5 --comparator Greater --json
{ "matched": false }

Ili kubakiza faili zenye kurasa zaidi ya 2 pekee, unaweza kuandika hivi. Tuliiendesha ndani ya mashine kwa a.pdf (ukurasa 1) na three.pdf (kurasa 3), na ya pili tu ndiyo ilibaki:

mkdir -p big
for f in *.pdf; do
  if pdfx filter-page-count "$f" --pageCount 2 --comparator Greater --json -o big/ \
      | jq -e '.matched == false' >/dev/null; then
    echo "$f: imerukwa"
  fi
done

jq -e '.matched == false' hutoka na 0 pasipo mlingano na 1 kukiwa na mlingano. Kukiwa na mlingano, pdfx tayari imeandika faili kwenye big/; if huamua tu kama kuchapisha "imerukwa", si kama kuandika.

Ingizo likiwa moja, --json haina safu ya files

Kwa ingizo kadhaa, pato la kawaida chini ya --json ni ripoti kamili. input ni njia kamili. processed huhesabu faili ambazo ombi lake lilifanikiwa, ikiwemo zisizo na mlingano. unmatched ni idadi ya zile zisizo na mlingano, na ingizo zao ni { "ok": true, "matched": false } bila path. Kila faili katika kundi isipokuwa na mlingano, msimbo wa kutoka bado ni 0. Ukipitisha --idempotency-key kwa kundi, ufunguo unaotumwa kwa kila faili ni <key>:<index>; utaratibu uko katika Idempotency-Key: Majaribio Salama kwa Kazi za PDF.

{
  "processed": 2,
  "unmatched": 0,
  "failed": 1,
  "files": [
    { "input": "/work/a.pdf", "ok": true, "path": "out/a.pdf", "contentType": "application/pdf", "bytes": 1040 },
    { "input": "/work/broken.pdf", "ok": false, "error": "HTTP 400: The file is not a valid PDF or it is damaged.", "reason": "invalid_pdf" },
    { "input": "/work/b.pdf", "ok": true, "path": "out/b.pdf", "contentType": "application/pdf", "bytes": 1027 }
  ]
}

Kwa ingizo moja, njia ya faili moja hutumika: --json huchapisha { "path": ..., "contentType": ..., "bytes": ... } na hakuna safu ya files. Inaposhindwa, pato la kawaida ni tupu na kila kitu kiko kwenye hitilafu ya kawaida. Unapopanua faili kwa glob, hati lazima ishughulikie miundo yote miwili, iwe faili moja au kadhaa zimelingana.

Kusanya kanuni zilizo juu katika hatua moja ya CI

Hati hii inabana tu na haitumii zana yoyote ya kichujio. Kushindwa kubana hutoka na 1, na hatua hushindwa pamoja nayo. Zana ya kichujio isiyopata mlingano hutoka na 0, kwa hiyo CI haishindwi kwa sababu tu hakukuwa na mlingano; kama kukosa mlingano ni tatizo ni juu yako kuamua kwa kusoma --json, kama ilivyo katika sehemu ya vichujio hapo juu.

Faili yoyote ikikataliwa, hatua hii inashindwa na kuorodhesha majina ya faili na sababu kwenye kumbukumbu. Mantiki ni ile ile ya awali: soma msimbo wa kutoka kwanza, chapisha hitilafu ya kawaida inaposhindwa, kisha tumia jq kutoa reason kutoka ripoti ya kundi. Bila hoja ya saraka hutoka mara moja, ili "$1"/*.pdf isipanuliwe kamwe kuwa /*.pdf.

#!/usr/bin/env bash
# Matumizi: ./ci-step.sh docs
docs="${1:?matumizi: ./ci-step.sh <saraka>}"
mkdir -p out
pdfx compress "$docs"/*.pdf -o out/ --json > report.json 2> errors.log
status=$?
if [ "$status" -ne 0 ]; then
  cat errors.log >&2
  jq -r '.files[]? | select(.ok | not) | "\(.input | split("/") | last)\t\(.reason)"' report.json >&2
fi
exit "$status"

Tuliiendesha ndani ya mashine kwa aina nne za ingizo:

Alama ya kuuliza mwishoni mwa .files[]? katika jq huzuia ripoti ya faili moja (isiyo na files) isilete hitilafu. Faili moja iliyoharibika haina ripoti ya kundi na sababu inaonekana tu katika errors.log, kwa hiyo hifadhi mistari yote miwili ya pato.

Mambo matatu zaidi ya kukagua kabla ya kuweka hii kwenye CI. pdfx inahitaji mtandao: faili hupakiwa kwenye PDFX_API_BASE, ambayo chaguo-msingi ni https://pdf123.xyz. Kwa nyaraka zinazopaswa kubaki ndani ya mtandao wako, endesha huduma yako mwenyewe na elekeza kigeu hiki kwake; tazama Kujipangisha Hukupa Nini Hasa (na Kunagharimu Nini). Unapohitaji utambulisho, weka ufunguo kwenye PDFX_API_KEY na si kwenye hoja za mstari wa amri, ambako ungebaki kwenye orodha ya michakato na kumbukumbu. Toleo lililochapishwa kwa sasa ni 0.1.0; kwenye CI tumia npx @pdf123/[email protected] ... kulibana, ili muundo wa pato na misimbo ya kutoka visibadilike na matoleo mapya na uboreshaji uwe badiliko unalofanya kwa makusudi.

Ukurasa wa kifurushi kwenye npm ni @pdf123/cli.