Overzicht van NextPDF Gotenberg

In een oogopslag

NextPDF Gotenberg is een kleine bridge tussen NextPDF en een externe Gotenberg-service. Gebruik ze wanneer NextPDF een Office-document niet zelf kan renderen. De bridge stuurt het document via Hypertext Transfer Protocol (HTTP) naar een Gotenberg-instantie, ontvangt Portable Document Format (PDF) als uitvoer en geeft die PDF door aan uw applicatie. Vanaf dat punt verzorgt NextPDF de verdere nabewerking.

Het pakket is klein en expliciet opgezet. Het bevat geen ingebouwde renderer, start geen LibreOffice en draait geen browser. Elke conversie verloopt via één multipart-HTTP-verzoek naar een Gotenberg-endpoint. U beheert dat endpoint en laat de bridge er via de configuratie naar verwijzen.

Gebruik deze bridge wanneer u .docx-, .xlsx-, .pptx-, .odt-, .ods- of .odp-bronbestanden hebt en PDF-uitvoer nodig hebt binnen een NextPDF-pijplijn. Zodra de PDF bestaat, verzorgen NextPDF of nextpdf/premium het ondertekenen, de PDF/A-conversie, het toevoegen van watermerken en het samenvoegen.

Waarvan de bridge afhankelijk is

De bridge heeft één runtime-afhankelijkheid die geen PHP-pakket is: een draaiende Gotenberg-service die de bridge via Hypertext Transfer Protocol Secure (HTTPS) kan bereiken.

De bridge installeert, beheert of bewaakt Gotenberg niet. U implementeert Gotenberg zelf; het upstreamproject publiceert een container-image. U bent verantwoordelijk voor de beschikbaarheid, capaciteit en de blootstelling ervan via het netwerk.
De bridge communiceert met de LibreOffice-conversieroute van Gotenberg. De verzoek-URL wordt opgebouwd als <apiUrl>/forms/libreoffice/convert, waarbij <apiUrl> de basis-URL is die u configureert. Deze route bepaalt de set ondersteunde formaten van de bridge.
De health-probe stuurt een HTTP-HEAD-verzoek naar <apiUrl>/health en beschouwt elke status lager dan 500 als beschikbaar.

Omdat de conversie plaatsvindt in een service die u beheert, hangt het gedrag af van de Gotenberg-versie die u gebruikt. De bridge stuurt een vast multipart-verzoek en gaat slechts uit van twee Gotenberg-paden: het routepad (/forms/libreoffice/convert) en het health-pad (/health). Zie /integrations/gotenberg/install/ voor de basisimplementatie en /integrations/gotenberg/security-and-operations/ voor het verharden van de service.

Ondersteunde documentformaten

De bridge converteert alleen de formaten die in het bijbehorende OfficeFormat-type worden opgesomd. Ze herkent elk formaat aan de bestandsextensie. De herkenning is hoofdletterongevoelig en een punt aan het begin is toegestaan. De bridge stuurt vervolgens elk bestand naar Gotenberg met een vast Multipurpose Internet Mail Extensions (MIME)-type:

Formaat	Extensie	MIME-type dat naar Gotenberg wordt gestuurd
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`

Deze lijst is volledig. Een extensie buiten deze set leidt tot een ValueError voordat er een netwerkverzoek wordt gedaan, zodat de bridge nooit een conversie probeert uit te voeren die ze niet kan beschrijven. De bridge claimt niet dat ze “elk Office-bestand” of “alle documentformaten ondersteunt”. Ze ondersteunt de zes formaten hierboven omdat de code alleen die zes herkent en de testsuite alleen die zes test.

Oudere binaire formaten (.doc, .xls, .ppt), rich text (.rtf), platte tekst, comma-separated values (CSV) en afbeeldingsformaten maken geen deel uit van de door de bridge herkende set. Gotenbergs eigen LibreOffice-route kan een bredere reeks invoer accepteren. De bridge beperkt zich bewust tot de opgesomde set zodat formaatdetectie, het MIME-type en de resultaatmetadata consistent en verifieerbaar blijven.

Hoe een conversie verloopt

Een conversie is één lineair proces. De bridge valideert elke stap voordat er ook maar een byte het proces verlaat:

De configuratie wordt gecontroleerd. Bij een lege Application Programming Interface (API)-URL mislukt de conversie onmiddellijk met een conversie-exceptie.
De API-URL wordt gevalideerd. HTTPS is vereist en de host wordt omgezet en gescreend zodat deze niet naar een privé- of gereserveerd adres kan verwijzen. De omgezette adresverzameling wordt vastgelegd voor latere pinning.
De invoer wordt gelezen (bij bestandsconversies wordt het pad eerst gecanoniceerd om traversal te blokkeren) en de extensie wordt toegewezen aan een OfficeFormat.
De bridge controleert de bytelengte tegen het geconfigureerde maximum en screent de bestandsnaam op traversal-reeksen, slashes, null-bytes en stuurtekens.
De adresverzameling wordt vlak voor het verzoek opnieuw gecontroleerd om de kloof tussen validatie en verbinding te dichten.
De bridge bouwt een multipart/form-data-body op en stuurt deze met POST naar de LibreOffice-route, met een bearertoken als die is geconfigureerd.
De bridge parseert het antwoord. De status moet 200 zijn, de Content-Type moet application/pdf bevatten en de body moet beginnen met de %PDF-handtekening. Pas dan wordt er een resultaat geretourneerd.

Elke fout in stappen 1–7 veroorzaakt een getypeerde exceptie. De bridge retourneert geen gedeeltelijk of ongecontroleerd resultaat. De exacte excepties en hun triggers zijn gecatalogiseerd in /integrations/gotenberg/troubleshooting/.

Wat u terugkrijgt

Een geslaagde conversie retourneert een resultaatobject. Het object bevat de ruwe PDF-bytes, het geconverteerde bronformaat en een optionele meting van de rendertijd. Het stelt ook een geldigheidscontrole beschikbaar (een niet-lege body die begint met %PDF) en een accessor voor de bytegrootte. De bytes vormen een normale PDF-stream, zodat u ze naar schijf kunt schrijven, naar een client kunt streamen of in een NextPDF-document kunt invoeren voor verdere verwerking.

Waar de bridge ophoudt

De bridge converteert en valideert. Ze doet niet het volgende:

De uitvoer ondertekenen, versleutelen, lineariseren of naar PDF/A converteren. NextPDF core of nextpdf/premium verzorgt die nabewerkingstaken.
Mislukte verzoeken opnieuw proberen, werk in een wachtrij plaatsen of resultaten cachen. Dat zijn taken op applicatieniveau. /integrations/gotenberg/production-usage/ laat zien hoe u die rond de bridge toevoegt.
De levenscyclus van de Gotenberg-service beheren. Implementatie en beheer komen aan bod in /integrations/gotenberg/security-and-operations/.

Edities en nabewerking

De open source software (OSS)-core kan de geconverteerde PDF ongewijzigd wegschrijven. Als u het geconverteerde document moet ondertekenen, een PDF/A-archiveringsprofiel moet produceren of een watermerk moet toepassen, voegt het nextpdf/premium-pakket die mogelijkheden toe. De bridge zelf is editieneutraal: ze produceert een PDF. Wat u met die PDF doet, bepaalt of u een commerciële editie nodig hebt.

De PDF Advanced Electronic Signatures (PAdES)-baseline die in de Pro-editie beschikbaar is, is uitsluitend B-B. Long-term validation (LTV)-profielen (B-T, B-LT, B-LTA) maken geen deel uit van de Pro-editie en worden niet door deze bridge geleverd. Leid geen tijdstempel- of LTV-mogelijkheid af uit de aanwezigheid van dit pakket.

Zie ook

/integrations/gotenberg/install/ — installeer het pakket en implementeer een basis voor Gotenberg.
/integrations/gotenberg/configuration/ — elke configuratieoptie, het type, de standaardwaarde en het effect ervan.
/integrations/gotenberg/quickstart/ — voer uw eerste conversie uit.
/integrations/gotenberg/production-usage/ — koppel de bridge aan een echte applicatie.
/integrations/gotenberg/troubleshooting/ — de exceptiecatalogus en wat elke exceptie betekent.
/integrations/gotenberg/security-and-operations/ — het beveiligingsmodel en hoe u de afhankelijke service veilig beheert.
/integrations/gotenberg/boot-and-discovery/ — hoe host-frameworks de bridge ontdekken en koppelen.
/integrations/gotenberg/integration/ — stuur NextPDF-rendering aan via de service.