Menggunakan pdfx dalam Terminal dan CI: Daripada Perintah Pertama kepada Skrip yang Boleh Dipercayai

Sebelum anda meletakkan pdfx dalam skrip atau integrasi berterusan (CI), ingat dua perkara. Kod keluar 0 tidak selalu bermakna fail telah ditulis: alat penapis bersyarat tanpa padanan juga keluar dengan 0. Dan --json mempunyai bentuk yang berbeza untuk satu input berbanding beberapa input, jadi skrip yang hanya menghuraikan tatasusunan files tidak menemui apa-apa apabila hanya satu fail sepadan. pdfx ialah klien HTTP: fail dimuat naik ke pelayan untuk diproses, tiada enjin setempat, dan tiada mod luar talian. Rujukan perintah penuh ada dalam panduan CLI di halaman pembangun.

Pasang, kemudian gabungkan dua fail

Anda memerlukan Node 20.3 atau lebih baharu, atau Bun:

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

Jika anda tidak mahu memasang secara global, letakkan npx @pdf123/cli di hadapan perintah. Dengan dua PDF dalam direktori semasa:

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

Jika berjaya, output standard mencetak merged.pdf. Itulah Gabungkan PDF. Sebelum bertukar alat, minta medan dan jangan meneka nama parameter:

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

(Petikan sahaja; medan juga termasuk --rotation, --customColor dan lain-lain.) Medan hanyalah pilihan baris perintah:

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

pdfx list menyenaraikan kesemua 95 alat, --category security menyenaraikan satu kategori sahaja, dan --query watermark mencari mengikut perkataan.

Beberapa fail masuk ke dalam direktori, dan fail sedia ada tidak ditimpa

Beri alat satu fail beberapa input dan setiap fail ditulis ke dalam direktori yang dinamakan oleh -o sebaik sahaja ia siap, tidak ditahan sehingga akhir. Jika satu fail gagal, yang lain diteruskan, dan kod keluar pada akhir kelompok ialah 1.

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

Output standard daripada satu larian kelihatan seperti ini, dan urutannya boleh berbeza setiap kali:

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

Direktori yang sudah wujud boleh digunakan terus; jika direktori belum wujud, -o memerlukan / di hujung, jika tidak small dianggap sebagai nama fail. Tanpa -o, hasil diletakkan dalam direktori semasa dengan nama yang diberikan pelayan; fail sedia ada tidak ditimpa dan yang baharu menjadi a-1.pdf, a-2.pdf. Nama fail tertentu (-o same.pdf) menggantikan kandungan sedia ada, seperti yang anda arahkan. Secara lalai dua fail diproses pada satu masa; ubahnya dengan --concurrency. Jika anda menekan Ctrl-C di tengah-tengah kelompok, fail yang sudah ditulis kekal dan kod keluar ialah 130.

Buka fail yang disulitkan dengan --input-password PASSWORD. Apabila kelompok mencampurkan fail berkunci dan tidak berkunci, gunakan --password-for FILE=PASSWORD, yang boleh diulang.

Panggil alat secara berasingan untuk fail perantara, jika tidak gunakan pipeline

Untuk menggabungkan, kemudian menambah tera air, kemudian memampatkan, apabila anda tidak memerlukan hasil perantara pada cakera, lipatkannya menjadi satu permintaan dengan pipeline; fail perantara tidak dimuat turun dan dimuat naik semula. Jika anda mahu fail daripada setiap langkah, panggil alat itu secara berasingan. Satu pipeline menghasilkan satu fail.

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

# Apabila satu langkah memerlukan parameter, huraikan langkah dalam JSON
pdfx pipeline a.pdf b.pdf \
  --steps '[{"tool":"merge"},{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' \
  -o out.pdf

Satu pipeline mempunyai paling banyak 8 langkah; langkah ke-9 mendapat HTTP 400: at most 8 pipeline steps allowed. Alat yang memerlukan fail kedua (contohnya overlay-pdfs, yang menindih PDF lain) tidak boleh menjadi langkah pipeline. pdfx menolaknya sebelum memuat naik, dengan kod keluar 2 dan mesej Tool "overlay-pdfs" needs a second file and cannot run as a pipeline step.

Gunakan input standard hanya apabila anda mahu menyambung perintah itu pada paip. Argumen fail - membaca daripada input standard, dan -o - menulis hasil ke output standard:

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

Dalam mod ini output standard hanya membawa bait fail; mesej dan ralat pergi ke ralat standard, jadi pengubahan hala selamat. Kami menyemaknya dengan PDF sekitar 1 KB: output standard memuatkan PDF sebanyak 1040 bait, sama saiz dengan fail yang ditulis dengan -o, dan ralat standard kosong. Apabila anda membaca daripada input standard dan tidak memberi -o, hasil dinamakan stdin.pdf, ditulis ke direktori semasa dengan satu nota pada ralat standard.

Skrip harus memadankan sebab, bukan mesej

Jika gagal, selain satu baris mesej, ralat standard membawa tiga baris: reason:, code: dan hint:. Fail yang disulitkan dengan kata laluan salah menghasilkan ini secara setempat:

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

Cara anda menghantar kata laluan mengubah baris pertama mesej: unlock --password memberi baris di atas. Dengan --input-password pada alat lain, pelayan menganggap pembukaan kunci sebagai langkah dalaman dan baris pertamanya ialah HTTP 400: Pipeline step 0 (security/remove-password) failed: The password is incorrect., manakala baris reason: ialah wrong_password dalam kedua-dua kes. Tanpa kata laluan sama sekali, mesejnya ialah This PDF is password-protected. Enter its password. dan reason ialah password_required. Skrip harus memadankan baris reason:. code lebih kasar, dan nilai yang biasa ialah bad_request.

Nama alat yang salah eja keluar dengan 2, dan mesej mencadangkan nama yang serupa:

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

Jenis hasil yang bercanggah dengan nama fail juga keluar dengan 2, dan ia berlaku sebelum apa-apa ditulis. Menulis ZIP yang dihasilkan oleh Asingkan PDF ke 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

Tamat masa juga keluar dengan 1, dengan code ditetapkan kepada timeout. Unit --timeout ialah milisaat dan nilai lalainya 300000, iaitu 5 minit, jadi --timeout 60 bermakna 60 milisaat, bukan 60 saat.

Apabila syarat palsu, kod keluar tetap 0

Satu kelas alat menjawab soalan ya atau tidak: adakah bilangan halaman lebih daripada N, adakah fail mengandungi teks tertentu, adakah fail lebih besar daripada saiz tertentu. Apabila jawapannya ya, ia memulangkan fail input tanpa perubahan; apabila tidak, ia tidak memulangkan apa-apa, dan pdfx mencetak satu baris no match dan keluar dengan 0. Alat penapis ini wujud hanya dalam SDK, baris perintah dan MCP; laman web tidak mempunyai halaman untuknya.

Ini berbeza daripada satu lagi jenis hasil kosong. Apabila PDF ke CSV tidak menemui jadual dalam PDF, pelayan memulangkan 204 dan pdfx keluar dengan 1 serta melaporkan no_content: alat itu bertujuan menghasilkan kandungan dan tidak berbuat demikian, dan sebabnya ada dalam Eksport Jadual Kosong (204): PDF Anda Mungkin Tiada Lajur. Bagi alat penapis, "tiada padanan" ialah jawapan yang memang patut diberikannya.

Untuk membacanya dalam skrip, gunakan --json. Padanan mencetak fail yang ditulis; tiada padanan mencetak { "matched": false }:

# Padan: fail ditulis, dan maklumatnya dicetak
$ pdfx filter-page-count three.pdf --pageCount 2 --comparator Greater --json -o big/
{ "path": "big/three.pdf", "contentType": "application/pdf", "bytes": 2594 }

# Tiada padanan: tiada fail ditulis
$ pdfx filter-page-count three.pdf --pageCount 5 --comparator Greater --json
{ "matched": false }

Untuk menyimpan hanya fail yang lebih daripada 2 halaman, anda boleh menulisnya seperti ini. Kami menjalankannya secara setempat pada a.pdf (1 halaman) dan three.pdf (3 halaman), dan hanya yang kedua disimpan:

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: dilangkau"
  fi
done

jq -e '.matched == false' keluar dengan 0 apabila tiada padanan dan 1 apabila ada. Jika ada padanan, fail sudah ditulis ke dalam big/ oleh pdfx; if hanya menentukan sama ada hendak mencetak "dilangkau", bukan sama ada hendak menulis.

Dengan satu input sahaja, --json tidak mempunyai tatasusunan files

Dengan beberapa input, output standard di bawah --json ialah laporan penuh. input ialah laluan mutlak. processed mengira fail yang permintaannya berjaya, termasuk yang tiada padanan. unmatched ialah bilangan antaranya yang tiada padanan, dan entri mereka ialah { "ok": true, "matched": false } tanpa path. Apabila setiap fail dalam kelompok tiada padanan, kod keluar tetap 0. Apabila anda menghantar --idempotency-key kepada kelompok, kunci yang dihantar bagi setiap fail ialah <key>:<index>; mekanismenya ada dalam Idempotency-Key: Cubaan Semula yang Selamat untuk Tugasan 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 }
  ]
}

Dengan satu input, laluan satu fail digunakan: --json mencetak { "path": ..., "contentType": ..., "bytes": ... } dan tiada tatasusunan files. Jika gagal, output standard kosong dan segala-galanya berada pada ralat standard. Apabila anda mengembangkan fail dengan glob, skrip mesti mengendalikan kedua-dua format, sama ada satu fail sepadan atau beberapa.

Himpunkan peraturan di atas dalam satu langkah CI

Skrip ini hanya memampatkan dan tidak menggunakan alat penapis. Kegagalan pemampatan keluar dengan 1, dan langkah itu gagal bersamanya. Alat penapis tanpa padanan keluar dengan 0, jadi CI tidak gagal hanya kerana tiada padanan; sama ada ketiadaan padanan dianggap masalah, anda yang menentukannya dengan membaca --json, seperti dalam bahagian penapis di atas.

Jika mana-mana fail ditolak, langkah ini gagal dan menyenaraikan nama fail serta sebabnya dalam log. Logiknya sama seperti tadi: baca kod keluar dahulu, cetak ralat standard jika gagal, kemudian gunakan jq untuk mengeluarkan reason daripada laporan kelompok. Tanpa argumen direktori ia keluar serta-merta, supaya "$1"/*.pdf tidak pernah dikembangkan menjadi /*.pdf.

#!/usr/bin/env bash
# Penggunaan: ./ci-step.sh docs
docs="${1:?penggunaan: ./ci-step.sh <direktori>}"
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"

Kami menjalankannya secara setempat dengan empat jenis input:

Tanda soal di hujung .files[]? dalam jq menghalang laporan satu fail (yang tiada files) daripada menimbulkan ralat. Satu fail rosak tidak mempunyai laporan kelompok dan sebabnya hanya muncul dalam errors.log, jadi simpan kedua-dua baris output.

Tiga perkara lagi perlu disemak sebelum anda meletakkannya dalam CI. pdfx memerlukan rangkaian: fail dimuat naik ke PDFX_API_BASE, yang lalainya https://pdf123.xyz. Untuk dokumen yang mesti kekal dalam rangkaian anda, jalankan perkhidmatan sendiri dan halakan pemboleh ubah ini kepadanya; lihat Apa Sebenarnya yang Anda Dapat daripada Self-Host (dan Apa Kosnya). Apabila anda memerlukan identiti, letakkan kunci dalam PDFX_API_KEY dan bukan dalam argumen baris perintah, kerana di sana ia kekal dalam senarai proses dan log. Versi yang diterbitkan sekarang ialah 0.1.0; dalam CI gunakan npx @pdf123/[email protected] ... untuk menetapkannya, supaya format output dan kod keluar tidak berubah dengan keluaran baharu dan naik taraf menjadi perubahan yang anda lakukan dengan sengaja.

Halaman pakej ini di npm ialah @pdf123/cli.