Przegląd integracji NextPDF Gotenberg

W skrócie

NextPDF Gotenberg to niewielki most między NextPDF a zewnętrzną usługą Gotenberg. Skorzystaj z niego, gdy NextPDF nie może natywnie wyrenderować dokumentu pakietu Office. Most wysyła dokument do instancji Gotenberg za pośrednictwem protokołu Hypertext Transfer Protocol (HTTP), odbiera wynik w formacie Portable Document Format (PDF) i przekazuje plik PDF do aplikacji. Dalszym przetwarzaniem końcowym zajmuje się NextPDF.

Pakiet jest mały i ma jasno określony zakres. Nie osadza silnika renderującego, nie uruchamia programu LibreOffice ani przeglądarki. Każda konwersja korzysta z pojedynczego, wieloczęściowego żądania HTTP do punktu końcowego Gotenberg. Tym punktem końcowym zarządzasz samodzielnie i wskazujesz go mostowi w konfiguracji.

Skorzystaj z tego mostu, gdy masz pliki źródłowe .docx, .xlsx, .pptx, .odt, .ods lub .odp i potrzebujesz wyniku w formacie PDF w potoku NextPDF. Gdy plik PDF już istnieje, NextPDF lub nextpdf/premium zajmuje się podpisywaniem, konwersją do PDF/A, dodawaniem znaków wodnych oraz scalaniem.

Czego wymaga most

Most ma jedną zależność uruchomieniową spoza pakietów PHP: działającą usługę Gotenberg, z którą może połączyć się za pośrednictwem protokołu Hypertext Transfer Protocol Secure (HTTPS).

Most nie instaluje Gotenberg, nie zarządza nim ani go nie nadzoruje. Gotenberg wdrażasz samodzielnie; projekt źródłowy publikuje obraz kontenera. Odpowiadasz za dostępność, przepustowość i ekspozycję tej usługi w sieci.
Most komunikuje się z trasą konwersji LibreOffice w Gotenberg. Adres URL żądania jest budowany jako <apiUrl>/forms/libreoffice/convert, gdzie <apiUrl> to bazowy adres URL, który konfigurujesz. Ta trasa definiuje zestaw formatów obsługiwanych przez most.
Sonda kondycji wysyła żądanie HTTP HEAD na adres <apiUrl>/health i traktuje każdy status poniżej 500 jako oznakę dostępności.

Ponieważ konwersja działa w usłudze zarządzanej samodzielnie, jej zachowanie zależy od używanej wersji Gotenberg. Most wysyła żądanie wieloczęściowe o stałej strukturze i zakłada istnienie tylko dwóch ścieżek Gotenberg: trasy konwersji (/forms/libreoffice/convert) oraz ścieżki kondycji (/health). Zobacz /integrations/gotenberg/install/, aby poznać podstawową konfigurację wdrożenia, oraz /integrations/gotenberg/security-and-operations/, aby utwardzić usługę.

Obsługiwane formaty dokumentów

Most konwertuje wyłącznie formaty zdefiniowane w typie OfficeFormat. Format rozpoznaje na podstawie rozszerzenia pliku. Dopasowanie nie uwzględnia wielkości liter, a początkowa kropka jest dozwolona. Następnie most wysyła każdy plik do Gotenberg z przypisanym na stałe typem Multipurpose Internet Mail Extensions (MIME):

Format	Rozszerzenie	Typ MIME wysyłany do 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`

Ta lista jest kompletna. Dla rozszerzenia spoza tego zestawu most zgłasza ValueError przed wysłaniem jakiegokolwiek żądania sieciowego, więc nigdy nie próbuje wykonać konwersji, której nie potrafi opisać. Most nie deklaruje obsługi „dowolnego pliku pakietu Office” ani „wszystkich formatów dokumentów”. Obsługuje sześć wymienionych formatów, ponieważ kod rozpoznaje tylko te sześć, a zestaw testów sprawdza tylko te sześć.

Starsze formaty binarne (.doc, .xls, .ppt), tekst sformatowany (.rtf), zwykły tekst, wartości rozdzielane przecinkami (CSV) oraz formaty obrazów nie należą do zestawu rozpoznawanego przez most. Trasa LibreOffice w samym Gotenberg może akceptować szerszy zakres danych wejściowych. Most celowo ogranicza się do wymienionego zestawu, aby wykrywanie formatu, typ MIME oraz metadane wyniku pozostały spójne i weryfikowalne.

Jak przebiega konwersja

Konwersja ma pojedynczy, liniowy przebieg. Most weryfikuje każdy krok, zanim jakikolwiek bajt opuści proces:

Sprawdzana jest konfiguracja. Pusty adres URL interfejsu programowania aplikacji (API) powoduje natychmiastowe niepowodzenie i zgłoszenie wyjątku konwersji.
Adres URL API jest weryfikowany. Wymagany jest protokół HTTPS, a host jest rozwiązywany i sprawdzany, aby nie wskazywał na adres prywatny lub zarezerwowany. Zestaw rozwiązanych adresów jest zapisywany do późniejszego przypięcia.
Dane wejściowe są odczytywane (w przypadku konwersji plików ścieżka jest najpierw kanonizowana, aby zablokować trawersowanie), a ich rozszerzenie jest mapowane na OfficeFormat.
Most porównuje długość w bajtach ze skonfigurowanym maksimum i sprawdza nazwę pliku pod kątem sekwencji trawersowania, ukośników, bajtów null oraz znaków sterujących.
Zestaw adresów jest ponownie sprawdzany bezpośrednio przed żądaniem, aby wyeliminować lukę między weryfikacją a połączeniem.
Most buduje treść multipart/form-data i wysyła ją metodą POST do trasy LibreOffice, wraz z tokenem bearer, jeśli jest skonfigurowany.
Most analizuje odpowiedź. Status musi wynosić 200, nagłówek Content-Type musi zawierać application/pdf, a treść musi zaczynać się od sygnatury %PDF. Dopiero wtedy zwracany jest wynik.

Każde niepowodzenie w krokach 1–7 zgłasza typowany wyjątek. Most nie zwraca częściowego ani niezweryfikowanego wyniku. Konkretne wyjątki oraz ich przyczyny są skatalogowane w /integrations/gotenberg/troubleshooting/.

Co otrzymujesz w zamian

Pomyślna konwersja zwraca obiekt wyniku. Obiekt zawiera surowe bajty PDF, skonwertowany format źródłowy oraz opcjonalny pomiar czasu renderowania. Udostępnia też sprawdzenie poprawności (niepusta treść zaczynająca się od %PDF) oraz akcesor rozmiaru w bajtach. Bajty stanowią zwykły strumień PDF, więc można zapisać je na dysku, przesłać strumieniowo do klienta lub przekazać do dokumentu NextPDF w celu dalszego przetwarzania.

Gdzie kończy się działanie mostu

Most konwertuje i weryfikuje. Nie wykonuje następujących czynności:

Nie podpisuje, nie szyfruje, nie linearyzuje ani nie konwertuje wyniku do formatu PDF/A. Tymi zadaniami przetwarzania końcowego zajmuje się rdzeń NextPDF lub nextpdf/premium.
Nie ponawia nieudanych żądań, nie kolejkuje zadań ani nie buforuje wyników. Są to kwestie na poziomie aplikacji. /integrations/gotenberg/production-usage/ pokazuje, jak dodać je w warstwie aplikacji wokół mostu.
Nie zarządza cyklem życia usługi Gotenberg. Wdrożenie i obsługę opisano w /integrations/gotenberg/security-and-operations/.

Edycje i przetwarzanie końcowe

Rdzeń open source (OSS) może zapisać skonwertowany plik PDF w niezmienionej postaci. Jeśli musisz podpisać skonwertowany dokument, utworzyć archiwalny profil PDF/A lub nałożyć znak wodny, pakiet nextpdf/premium dodaje te możliwości. Sam most jest niezależny od edycji: produkuje plik PDF. To, co zrobisz z tym plikiem PDF, decyduje o tym, czy potrzebujesz edycji komercyjnej.

W edycji Pro dostępny jest wyłącznie poziom bazowy B-B dla PDF Advanced Electronic Signatures (PAdES). Profile długoterminowej walidacji (LTV) (B-T, B-LT, B-LTA) nie są częścią edycji Pro i nie są udostępniane przez ten most. Nie zakładaj obsługi znaczników czasu ani LTV na podstawie obecności tego pakietu.

Zobacz także

/integrations/gotenberg/install/ — zainstaluj pakiet i wdróż podstawową konfigurację Gotenberg.
/integrations/gotenberg/configuration/ — każda opcja konfiguracji, jej typ, wartość domyślna i działanie.
/integrations/gotenberg/quickstart/ — uruchom pierwszą konwersję.
/integrations/gotenberg/production-usage/ — podłącz most do rzeczywistej aplikacji.
/integrations/gotenberg/troubleshooting/ — katalog wyjątków i znaczenie każdego z nich.
/integrations/gotenberg/security-and-operations/ — model bezpieczeństwa i sposób bezpiecznej obsługi usługi zależnej.
/integrations/gotenberg/boot-and-discovery/ — jak frameworki hostujące wykrywają i podłączają most.
/integrations/gotenberg/integration/ — steruj renderowaniem NextPDF za pośrednictwem tej usługi.