Tổng quan NextPDF Gotenberg

Tổng quan nhanh

NextPDF Gotenberg là một cầu nối nhỏ giữa NextPDF và một dịch vụ Gotenberg bên ngoài. Dùng nó khi NextPDF không thể kết xuất trực tiếp một tài liệu Office. Cầu nối gửi tài liệu đến một phiên bản Gotenberg qua Hypertext Transfer Protocol (HTTP), nhận đầu ra Portable Document Format (PDF), rồi trao tệp PDF cho ứng dụng của bạn. Từ đó, NextPDF xử lý các bước hậu xử lý còn lại.

Gói này nhỏ gọn và rõ ràng. Nó không nhúng bộ kết xuất, không khởi chạy LibreOffice, và không chạy trình duyệt. Mỗi lần chuyển đổi dùng một yêu cầu HTTP multipart gửi đến một endpoint của Gotenberg. Bạn vận hành endpoint đó và trỏ cầu nối tới nó trong cấu hình.

Dùng cầu nối này khi bạn có các tệp nguồn .docx, .xlsx, .pptx, .odt, .ods, hoặc .odp và cần đầu ra PDF trong một pipeline NextPDF. Sau khi tệp PDF được tạo, NextPDF hoặc nextpdf/premium xử lý việc ký, chuyển đổi PDF/A, đóng hình mờ, và gộp tệp.

Cầu nối phụ thuộc vào điều gì

Cầu nối có một phần phụ thuộc khi chạy không phải là gói PHP: một dịch vụ Gotenberg đang chạy mà cầu nối có thể truy cập qua Hypertext Transfer Protocol Secure (HTTPS).

Cầu nối không cài đặt, quản lý hay giám sát Gotenberg. Bạn tự triển khai Gotenberg; dự án thượng nguồn phát hành một image container. Bạn chịu trách nhiệm về tính khả dụng, công suất, và mức độ phơi bày mạng của dịch vụ.
Cầu nối giao tiếp với tuyến chuyển đổi LibreOffice của Gotenberg. URL yêu cầu được dựng thành <apiUrl>/forms/libreoffice/convert, trong đó <apiUrl> là URL cơ sở mà bạn cấu hình. Tuyến này quyết định tập định dạng được cầu nối hỗ trợ.
Bộ thăm dò tình trạng gửi một yêu cầu HTTP HEAD đến <apiUrl>/health và xem mọi trạng thái dưới 500 là khả dụng.

Vì quá trình chuyển đổi chạy trong dịch vụ do bạn vận hành, hành vi phụ thuộc vào phiên bản Gotenberg mà bạn chạy. Cầu nối gửi một yêu cầu multipart cố định, và chỉ giả định hai đường dẫn Gotenberg: đường dẫn tuyến (/forms/libreoffice/convert) và đường dẫn tình trạng (/health). Xem /integrations/gotenberg/install/ để biết nền tảng triển khai và /integrations/gotenberg/security-and-operations/ để biết cách tăng cường bảo mật cho dịch vụ.

Các định dạng tài liệu được hỗ trợ

Cầu nối chỉ chuyển đổi các định dạng được liệt kê trong kiểu OfficeFormat của nó. Nó phát hiện từng định dạng dựa trên phần mở rộng tệp. Việc so khớp không phân biệt chữ hoa chữ thường, và cho phép có dấu chấm ở đầu. Sau đó, cầu nối gửi từng tệp đến Gotenberg với một kiểu Multipurpose Internet Mail Extensions (MIME) cố định:

Định dạng	Phần mở rộng	Kiểu MIME gửi đến 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`

Danh sách này là đầy đủ. Một phần mở rộng nằm ngoài tập này sẽ làm phát sinh ValueError trước khi có bất kỳ yêu cầu mạng nào, nên cầu nối không bao giờ thử một lần chuyển đổi mà nó không thể mô tả. Cầu nối không tuyên bố hỗ trợ “mọi tệp Office” hay “tất cả các định dạng tài liệu.” Nó hỗ trợ sáu định dạng ở trên vì mã chỉ nhận diện đúng sáu định dạng đó và bộ kiểm thử cũng chỉ kiểm tra đúng sáu định dạng đó.

Các định dạng nhị phân cũ (.doc, .xls, .ppt), văn bản định dạng phong phú (.rtf), văn bản thuần, comma-separated values (CSV), và các định dạng ảnh không thuộc tập định dạng mà cầu nối nhận diện. Bản thân tuyến LibreOffice của Gotenberg có thể chấp nhận dải đầu vào rộng hơn. Cầu nối cố ý tự giới hạn ở tập đã liệt kê để việc phát hiện định dạng, kiểu MIME, và siêu dữ liệu kết quả luôn nhất quán và có thể kiểm chứng.

Một lần chuyển đổi diễn ra như thế nào

Một lần chuyển đổi là một lượt xử lý đơn, tuyến tính. Cầu nối xác thực từng bước trước khi bất kỳ byte nào rời khỏi tiến trình:

Cấu hình được kiểm tra. URL Application Programming Interface (API) rỗng sẽ thất bại ngay lập tức với một ngoại lệ chuyển đổi.
URL API được xác thực. HTTPS là bắt buộc, và máy chủ được phân giải rồi kiểm tra để nó không thể trỏ tới địa chỉ riêng tư hoặc dành riêng. Tập địa chỉ đã phân giải được ghi lại để ghim về sau.
Đầu vào được đọc (với các lần chuyển đổi tệp, đường dẫn được chuẩn hóa trước để chặn duyệt thư mục) và phần mở rộng của nó được ánh xạ tới một OfficeFormat.
Cầu nối kiểm tra độ dài byte so với giá trị tối đa đã cấu hình, đồng thời kiểm tra tên tệp để tìm các chuỗi duyệt thư mục, dấu gạch chéo, byte null, và ký tự điều khiển.
Tập địa chỉ được kiểm tra lại ngay trước yêu cầu để khép khoảng cách giữa lúc xác thực và lúc kết nối.
Cầu nối dựng thân multipart/form-data và gửi POST đến tuyến LibreOffice, kèm bearer token nếu có cấu hình.
Cầu nối phân tích phản hồi. Trạng thái phải là 200, Content-Type phải chứa application/pdf, và thân phản hồi phải bắt đầu bằng chữ ký %PDF. Chỉ khi đó kết quả mới được trả về.

Bất kỳ thất bại nào ở các bước 1–7 đều làm phát sinh một ngoại lệ có kiểu. Cầu nối không trả về kết quả từng phần hoặc chưa được kiểm tra. Các ngoại lệ cụ thể và điều kiện kích hoạt chúng được liệt kê trong /integrations/gotenberg/troubleshooting/.

Những gì bạn nhận lại

Một lần chuyển đổi thành công trả về một đối tượng kết quả. Đối tượng này bao gồm các byte PDF thô, định dạng nguồn đã chuyển đổi, và một phép đo thời gian kết xuất tùy chọn. Nó cũng cung cấp phép kiểm tra tính hợp lệ (thân không rỗng bắt đầu bằng %PDF) và bộ truy cập kích thước byte. Các byte là một luồng PDF bình thường, nên bạn có thể ghi chúng ra đĩa, truyền chúng tới client, hoặc đưa chúng vào một tài liệu NextPDF để xử lý thêm.

Cầu nối dừng ở đâu

Cầu nối chuyển đổi và xác thực. Nó không:

Ký, mã hóa, tuyến tính hóa, hoặc chuyển đổi đầu ra sang PDF/A. NextPDF core hoặc nextpdf/premium xử lý các mối quan tâm hậu xử lý đó.
Thử lại các yêu cầu thất bại, xếp hàng công việc, hoặc lưu đệm kết quả. Đó là các mối quan tâm ở cấp ứng dụng. /integrations/gotenberg/production-usage/ cho thấy cách thêm chúng quanh cầu nối.
Quản lý vòng đời của dịch vụ Gotenberg. Việc triển khai và vận hành được trình bày trong /integrations/gotenberg/security-and-operations/.

Phiên bản và hậu xử lý

Lõi open source software (OSS) có thể ghi tệp PDF đã chuyển đổi nguyên trạng. Nếu bạn cần ký tài liệu đã chuyển đổi, tạo hồ sơ lưu trữ PDF/A, hoặc áp dụng hình mờ, gói nextpdf/premium bổ sung những khả năng đó. Bản thân cầu nối trung lập về phiên bản: nó tạo ra một tệp PDF. Việc bạn làm gì với tệp PDF đó quyết định liệu bạn có cần phiên bản thương mại hay không.

Nền tảng PDF Advanced Electronic Signatures (PAdES) có sẵn trong phiên bản Pro chỉ là B-B. Các hồ sơ long-term validation (LTV) (B-T, B-LT, B-LTA) không thuộc phiên bản Pro và không được cầu nối này cung cấp. Đừng suy diễn khả năng đóng dấu thời gian hoặc LTV từ sự hiện diện của gói này.

Xem thêm

/integrations/gotenberg/install/ — cài đặt gói và triển khai nền tảng Gotenberg.
/integrations/gotenberg/configuration/ — mọi tùy chọn cấu hình, kiểu, giá trị mặc định, và tác động của chúng.
/integrations/gotenberg/quickstart/ — chạy lần chuyển đổi đầu tiên.
/integrations/gotenberg/production-usage/ — kết nối cầu nối vào một ứng dụng thực tế.
/integrations/gotenberg/troubleshooting/ — danh mục ngoại lệ và ý nghĩa của từng ngoại lệ.
/integrations/gotenberg/security-and-operations/ — mô hình bảo mật và cách vận hành dịch vụ phụ thuộc một cách an toàn.
/integrations/gotenberg/boot-and-discovery/ — cách các framework chủ phát hiện và kết nối cầu nối.
/integrations/gotenberg/integration/ — điều khiển việc kết xuất NextPDF thông qua dịch vụ.