ภาพรวมของ NextPDF Gotenberg

ภาพรวมโดยสังเขป

NextPDF Gotenberg เป็นบริดจ์ขนาดเล็กที่เชื่อม NextPDF กับบริการ Gotenberg ภายนอก ใช้บริดจ์นี้เมื่อ NextPDF ไม่สามารถเรนเดอร์เอกสาร Office ได้โดยตรง บริดจ์จะส่งเอกสารไปยังอินสแตนซ์ Gotenberg ผ่าน Hypertext Transfer Protocol (HTTP) รับเอาต์พุต Portable Document Format (PDF) แล้วส่งต่อ PDF ให้แอปพลิเคชันของคุณ จากนั้น NextPDF จะจัดการงานประมวลผลภายหลังที่เหลือทั้งหมด

แพ็กเกจนี้มีขนาดเล็กและมีขอบเขตการทำงานชัดเจน ไม่ฝังเรนเดอเรอร์ ไม่สร้างกระบวนการ LibreOffice และไม่รันเบราว์เซอร์ การแปลงแต่ละครั้งใช้คำขอ HTTP แบบ multipart เพียงคำขอเดียวไปยังเอนด์พอยต์ Gotenberg คุณเป็นผู้ดูแลเอนด์พอยต์ดังกล่าว และกำหนดค่าให้บริดจ์ชี้ไปยังเอนด์พอยต์นั้น

ใช้บริดจ์นี้เมื่อคุณมีไฟล์ต้นฉบับ .docx, .xlsx, .pptx, .odt, .ods หรือ .odp และต้องการเอาต์พุต PDF ภายในไปป์ไลน์ NextPDF เมื่อได้ PDF แล้ว NextPDF หรือ nextpdf/premium จะจัดการการลงลายเซ็น การแปลงเป็น PDF/A การใส่ลายน้ำ และการรวมไฟล์

บริดจ์ต้องพึ่งพาสิ่งใดบ้าง

บริดจ์มีดีเพนเดนซีระหว่างรันไทม์เพียงรายการเดียวที่ไม่ใช่แพ็กเกจ PHP คือ บริการ Gotenberg ที่กำลังทำงานอยู่ ซึ่งบริดจ์สามารถเข้าถึงได้ผ่าน Hypertext Transfer Protocol Secure (HTTPS)

บริดจ์ ไม่ ติดตั้ง จัดการ หรือดูแล Gotenberg คุณต้องดีพลอย Gotenberg เอง โดยโครงการต้นน้ำมีอิมเมจคอนเทนเนอร์เผยแพร่ไว้ให้ คุณเป็นผู้รับผิดชอบความพร้อมใช้งาน ความจุ และการเปิดให้เข้าถึงผ่านเครือข่ายของบริการนี้
บริดจ์สื่อสารกับ เส้นทางการแปลง LibreOffice ของ Gotenberg โดยสร้าง URL ของคำขอเป็น <apiUrl>/forms/libreoffice/convert โดยที่ <apiUrl> คือ URL ฐานที่คุณกำหนดค่าไว้ เส้นทางนี้เป็นตัวกำหนดชุดรูปแบบที่บริดจ์รองรับ
การตรวจสุขภาพจะส่งคำขอ HTTP HEAD ไปยัง <apiUrl>/health และถือว่าสถานะใดๆ ที่ต่ำกว่า 500 ว่าพร้อมใช้งาน

เนื่องจากการแปลงเกิดขึ้นในบริการที่คุณเป็นผู้ดูแล พฤติกรรมจึงขึ้นอยู่กับเวอร์ชัน Gotenberg ที่คุณรัน บริดจ์ส่งคำขอ multipart แบบคงที่ และคาดหวังเส้นทาง Gotenberg เพียงสองเส้นทางเท่านั้น คือเส้นทางการแปลง (/forms/libreoffice/convert) และเส้นทางตรวจสุขภาพ (/health) ดู /integrations/gotenberg/install/ สำหรับเกณฑ์พื้นฐานในการดีพลอย และ /integrations/gotenberg/security-and-operations/ สำหรับการเสริมความแข็งแกร่งให้บริการ

รูปแบบเอกสารที่รองรับ

บริดจ์แปลงได้เฉพาะรูปแบบที่ระบุไว้ในชนิด OfficeFormat เท่านั้น โดยตรวจหารูปแบบจากนามสกุลไฟล์ การจับคู่ไม่คำนึงถึงตัวพิมพ์เล็กพิมพ์ใหญ่ และอนุญาตให้มีจุดนำหน้า จากนั้นบริดจ์จะส่งแต่ละไฟล์ไปยัง Gotenberg พร้อมชนิด Multipurpose Internet Mail Extensions (MIME) แบบคงที่ดังนี้

รูปแบบ	นามสกุล	ชนิด MIME ที่ส่งไปยัง Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

รายการนี้เป็นรายการทั้งหมด นามสกุลที่อยู่นอกชุดนี้จะทำให้เกิด ValueError ก่อนส่งคำขอเครือข่ายใดๆ ดังนั้นบริดจ์จะไม่พยายามแปลงสิ่งที่บริดจ์ไม่สามารถอธิบายได้ บริดจ์ไม่ได้อ้างว่ารองรับ “ไฟล์ Office ใดๆ” หรือ “รูปแบบเอกสารทั้งหมด” บริดจ์รองรับหกรูปแบบข้างต้นเพราะโค้ดรู้จักเพียงหกรูปแบบนั้น และชุดทดสอบก็ทดสอบเฉพาะหกรูปแบบนั้นเท่านั้น

รูปแบบไบนารีรุ่นเก่า (.doc, .xls, .ppt) ริชเท็กซ์ (.rtf) ข้อความธรรมดา comma-separated values (CSV) และรูปแบบรูปภาพ ไม่ อยู่ในชุดที่บริดจ์รู้จัก เส้นทาง LibreOffice ของ Gotenberg เองอาจรับอินพุตได้หลากหลายกว่านี้ แต่บริดจ์จงใจจำกัดตัวเองไว้ที่ชุดที่ระบุ เพื่อให้การตรวจหารูปแบบ ชนิด MIME และเมตาดาตาของผลลัพธ์มีความสอดคล้องและตรวจสอบยืนยันได้

การแปลงทำงานอย่างไร

การแปลงเป็นกระบวนการเชิงเส้นเพียงรอบเดียว บริดจ์ตรวจสอบความถูกต้องของแต่ละขั้นตอนก่อนที่ไบต์ใดๆ จะออกจากกระบวนการ ดังนี้

ตรวจสอบการกำหนดค่า URL ของ Application Programming Interface (API) หาก URL ว่างเปล่า จะล้มเหลวทันทีพร้อมข้อยกเว้นของการแปลง
ตรวจสอบความถูกต้องของ URL ของ API โดยต้องใช้ HTTPS และรีโซลฟ์โฮสต์พร้อมคัดกรองไม่ให้ชี้ไปยังที่อยู่ส่วนตัวหรือที่อยู่ที่สงวนไว้ ชุดที่อยู่ที่รีโซลฟ์ได้จะถูกเก็บไว้สำหรับการปักหมุดในภายหลัง
อ่านอินพุต (สำหรับการแปลงไฟล์ เส้นทางจะถูกทำให้เป็นรูปแบบมาตรฐานก่อนเพื่อป้องกันการไล่ผ่านไดเรกทอรี) แล้วแมปนามสกุลของอินพุตไปยัง OfficeFormat
บริดจ์ตรวจสอบความยาวเป็นไบต์เทียบกับค่าสูงสุดที่กำหนดค่าไว้ และคัดกรองชื่อไฟล์เพื่อหาลำดับการไล่ผ่านไดเรกทอรี เครื่องหมายทับ ไบต์ null และอักขระควบคุม
ชุดที่อยู่จะถูกตรวจสอบอีกครั้งทันทีก่อนส่งคำขอ เพื่อปิดช่องว่างระหว่างการตรวจสอบความถูกต้องกับการเชื่อมต่อ
บริดจ์สร้างเนื้อความแบบ multipart/form-data และส่ง POST ไปยังเส้นทาง LibreOffice พร้อม bearer token ที่กำหนดค่าไว้ หากมี
บริดจ์แยกวิเคราะห์การตอบกลับ สถานะต้องเป็น 200 Content-Type ต้องมี application/pdf และเนื้อความต้องขึ้นต้นด้วยลายเซ็น %PDF จึงจะส่งผลลัพธ์กลับ

ความล้มเหลวใดๆ ในขั้นตอนที่ 1–7 จะทำให้เกิดข้อยกเว้นแบบมีชนิด บริดจ์จะไม่ส่งผลลัพธ์ที่ไม่สมบูรณ์หรือยังไม่ได้ตรวจสอบกลับมา รายการข้อยกเว้นที่แน่นอนและตัวกระตุ้นของแต่ละข้อยกเว้นรวบรวมไว้ใน /integrations/gotenberg/troubleshooting/

สิ่งที่ได้รับกลับมา

การแปลงที่สำเร็จจะส่งคืนอ็อบเจกต์ผลลัพธ์ ซึ่งประกอบด้วยไบต์ PDF ดิบ รูปแบบต้นฉบับที่ถูกแปลง และการวัดเวลาเรนเดอร์ที่เป็นทางเลือก อ็อบเจกต์ยังให้ตรวจสอบความถูกต้องได้ (เนื้อความไม่ว่างเปล่าและขึ้นต้นด้วย %PDF) และมีตัวเข้าถึงขนาดไบต์ ไบต์เหล่านี้เป็นสตรีม PDF ปกติ จึงเขียนลงดิสก์ สตรีมไปยังไคลเอนต์ หรือป้อนเข้าสู่เอกสาร NextPDF เพื่อประมวลผลต่อได้

ขอบเขตของบริดจ์

บริดจ์ทำหน้าที่แปลงและตรวจสอบความถูกต้อง บริดจ์ไม่ทำสิ่งต่อไปนี้

ลงลายเซ็น เข้ารหัสลับ ทำให้เป็นเชิงเส้น หรือแปลงเอาต์พุตเป็น PDF/A งานประมวลผลภายหลังเหล่านั้นจัดการโดย NextPDF core หรือ nextpdf/premium
ลองส่งคำขอที่ล้มเหลวใหม่ จัดคิวงาน หรือแคชผลลัพธ์ สิ่งเหล่านี้เป็นงานระดับแอปพลิเคชัน /integrations/gotenberg/production-usage/ แสดงวิธีเพิ่มความสามารถเหล่านี้รอบๆ บริดจ์
จัดการวงจรชีวิตของบริการ Gotenberg การดีพลอยและการดำเนินงานครอบคลุมไว้ใน /integrations/gotenberg/security-and-operations/

เอดิชันและการประมวลผลภายหลัง

core แบบ open source software (OSS) สามารถเขียน PDF ที่แปลงแล้วได้ตามที่เป็นอยู่ หากคุณต้องการลงลายเซ็นเอกสารที่แปลงแล้ว สร้างโปรไฟล์การจัดเก็บถาวร PDF/A หรือใส่ลายน้ำ แพ็กเกจ nextpdf/premium จะเพิ่มความสามารถเหล่านี้ให้ ตัวบริดจ์เองเป็นกลางต่อเอดิชัน โดยผลิต PDF ออกมาเท่านั้น สิ่งที่คุณทำกับ PDF นั้นจะเป็นตัวกำหนดว่าจำเป็นต้องใช้เอดิชันเชิงพาณิชย์หรือไม่

เกณฑ์พื้นฐาน PDF Advanced Electronic Signatures (PAdES) ที่มีในเอดิชัน Pro คือ B-B เท่านั้น โปรไฟล์ long-term validation (LTV) (B-T, B-LT, B-LTA) ไม่ได้เป็นส่วนหนึ่งของ เอดิชัน Pro และไม่มีให้ในบริดจ์นี้ อย่าอนุมาน ว่ามีความสามารถด้านการประทับเวลาหรือ LTV จากการมีแพ็กเกจนี้อยู่

ดูเพิ่มเติม

/integrations/gotenberg/install/ — ติดตั้งแพ็กเกจและดีพลอย Gotenberg ขั้นพื้นฐาน
/integrations/gotenberg/configuration/ — ทุกตัวเลือกการกำหนดค่า ชนิด ค่าเริ่มต้น และผลของแต่ละตัวเลือก
/integrations/gotenberg/quickstart/ — รันการแปลงครั้งแรก
/integrations/gotenberg/production-usage/ — เชื่อมต่อบริดจ์เข้ากับแอปพลิเคชันจริง
/integrations/gotenberg/troubleshooting/ — รายการข้อยกเว้นและความหมายของแต่ละข้อยกเว้น
/integrations/gotenberg/security-and-operations/ — แบบจำลองความปลอดภัยและวิธีดำเนินงานบริการที่พึ่งพาอย่างปลอดภัย
/integrations/gotenberg/boot-and-discovery/ — วิธีที่เฟรมเวิร์กโฮสต์ค้นพบและเชื่อมต่อบริดจ์
/integrations/gotenberg/integration/ — ขับเคลื่อนการเรนเดอร์ของ NextPDF ผ่านบริการ