NextPDF Gotenberg'e genel bakış

Bir bakışta

NextPDF Gotenberg, NextPDF ile harici bir Gotenberg hizmeti arasında çalışan hafif bir köprüdür. NextPDF bir Office belgesini yerel olarak işleyemediğinde bunu kullanın. Köprü, belgeyi Hypertext Transfer Protocol (HTTP) üzerinden bir Gotenberg örneğine gönderir, Portable Document Format (PDF) çıktısını alır ve PDF’yi uygulamanıza iletir. Bundan sonra kalan işlem sonrası adımları NextPDF üstlenir.

Paket küçük ve kapsamı nettir. Yerleşik bir işleyici içermez, LibreOffice’i başlatmaz ve bir tarayıcı çalıştırmaz. Her dönüştürme için bir Gotenberg uç noktasına tek bir çok parçalı HTTP isteği gönderilir. Bu uç noktayı siz işletirsiniz ve yapılandırmada köprüyü ona yönlendirirsiniz.

Elinizde .docx, .xlsx, .pptx, .odt, .ods veya .odp kaynak dosyalarınız olduğunda ve bir NextPDF işlem hattında PDF çıktısına ihtiyaç duyduğunuzda bu köprüyü kullanın. PDF oluştuktan sonra imzalama, PDF/A’ya dönüştürme, filigran ekleme ve birleştirme işlemlerini NextPDF veya nextpdf/premium üstlenir.

Köprünün bağlı olduğu bileşenler

Köprünün, PHP paketi olmayan tek bir çalışma zamanı bağımlılığı vardır: köprünün Hypertext Transfer Protocol Secure (HTTPS) üzerinden erişebileceği çalışan bir Gotenberg hizmeti.

Köprü, Gotenberg’i kurmaz, yönetmez veya denetlemez. Gotenberg’i kendiniz dağıtırsınız; yukarı akış projesi bir konteyner imajı yayımlar. Hizmetin kullanılabilirliğinden, kapasitesinden ve ağa açık olmasından siz sorumlusunuz.
Köprü, Gotenberg’in LibreOffice dönüştürme yolu ile iletişim kurar. İstek URL’si <apiUrl>/forms/libreoffice/convert olarak oluşturulur; burada <apiUrl>, sizin yapılandırdığınız temel URL’dir. Bu yol, köprünün desteklenen biçim kümesini tanımlar.
Sağlık denetimi, bir HTTP HEAD isteğini <apiUrl>/health adresine gönderir ve 500 değerinin altındaki herhangi bir durum kodunu kullanılabilir olarak değerlendirir.

Dönüştürme sizin işlettiğiniz bir hizmette çalıştığından, davranış çalıştırdığınız Gotenberg sürümüne bağlıdır. Köprü sabit bir çok parçalı istek gönderir ve yalnızca iki Gotenberg yolu varsayar: dönüştürme yolu (/forms/libreoffice/convert) ve sağlık yolu (/health). Dağıtım temeli için /integrations/gotenberg/install/ sayfasına, hizmetin sağlamlaştırılması için /integrations/gotenberg/security-and-operations/ sayfasına bakın.

Desteklenen belge biçimleri

Köprü yalnızca OfficeFormat türünde listelenen biçimleri dönüştürür. Her biçimi dosya uzantısından algılar. Eşleştirme büyük/küçük harfe duyarsızdır ve başta bir noktaya izin verilir. Ardından köprü her dosyayı sabit bir Multipurpose Internet Mail Extensions (MIME) türüyle Gotenberg’e gönderir:

Biçim	Uzantı	Gotenberg’e gönderilen MIME türü
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`

Bu liste eksiksizdir. Bu kümenin dışındaki bir uzantı için, herhangi bir ağ isteği yapılmadan önce bir ValueError oluşturulur; böylece köprü, tanımlayamadığı bir dönüştürmeyi asla denemez. Köprü, “her türlü Office dosyasını” veya “tüm belge biçimlerini” desteklediğini iddia etmez. Yukarıdaki altı biçimi destekler; çünkü kod yalnızca bu altısını tanır ve test paketi de yalnızca bu altısını sınar.

Eski ikili biçimler (.doc, .xls, .ppt), zengin metin (.rtf), düz metin, virgülle ayrılmış değerler (CSV) ve görüntü biçimleri köprünün tanıdığı kümenin parçası değildir. Gotenberg’in kendi LibreOffice yolu daha geniş bir girdi yelpazesini kabul edebilir. Köprü, biçim algılama, MIME türü ve sonuç meta verisi tutarlı ve doğrulanabilir kalsın diye kendisini bilerek listelenen kümeyle sınırlar.

Bir dönüştürmenin akışı

Bir dönüştürme tek, doğrusal bir geçiş halinde ilerler. Köprü, herhangi bir bayt süreç dışına çıkmadan önce her adımı doğrular:

Yapılandırma denetlenir. Boş bir Application Programming Interface (API) URL’si hemen bir dönüştürme istisnası oluşturur.
API URL’si doğrulanır. HTTPS gereklidir ve ana makine, özel ya da ayrılmış bir adresi gösteremesin diye çözümlenir ve denetlenir. Çözümlenen adres kümesi, daha sonra sabitlemek üzere yakalanır.
Girdi okunur (dosya dönüştürmelerinde, yol geçişini engellemek için yol önce kanonikleştirilir) ve uzantısı bir OfficeFormat değerine eşlenir.
Köprü, bayt uzunluğunu yapılandırılan en büyük değere göre denetler ve dosya adını yol geçişi dizileri, eğik çizgiler, boş baytlar ve denetim karakterleri açısından inceler.
Doğrulama ile bağlantı arasındaki boşluğu kapatmak için adres kümesi, istek hemen öncesinde yeniden denetlenir.
Köprü bir multipart/form-data gövdesi oluşturur ve yapılandırılmışsa bir taşıyıcı belirteçle birlikte bunu LibreOffice yoluna POST eder.
Köprü yanıtı ayrıştırır. Durum kodu 200 olmalı, Content-Type başlığı application/pdf içermeli ve gövde %PDF imzasıyla başlamalıdır. Yalnızca o zaman bir sonuç döndürülür.

1–7 adımlarındaki herhangi bir başarısızlık, türlenmiş bir istisna oluşturur. Köprü, kısmi veya denetlenmemiş bir sonuç döndürmez. İstisnaların tam listesi ve bunların tetikleyicileri /integrations/gotenberg/troubleshooting/ sayfasında listelenmiştir.

Geri aldığınız sonuç

Başarılı bir dönüştürme, bir sonuç nesnesi döndürür. Nesne, ham PDF baytlarını, dönüştürülen kaynak biçimini ve isteğe bağlı bir işleme süresi ölçümünü içerir. Ayrıca bir geçerlilik denetimi (%PDF ile başlayan, boş olmayan bir gövde) ve bir bayt boyutu erişimcisi sunar. Baytlar normal bir PDF akışıdır; bu nedenle bunları diske yazabilir, bir istemciye akış olarak iletebilir veya daha fazla işleme için bir NextPDF belgesine besleyebilirsiniz.

Köprünün sınırları

Köprü dönüştürür ve doğrular. Şunları yapmaz:

Çıktıyı imzalamaz, şifrelemez, doğrusallaştırmaz veya PDF/A biçimine dönüştürmez. Bu işlem sonrası işleri NextPDF çekirdeği veya nextpdf/premium üstlenir.
Başarısız istekler için yeniden deneme yapmaz, işi kuyruğa almaz veya sonuçları önbelleğe almaz. Bunlar uygulama düzeyindeki konulardır. /integrations/gotenberg/production-usage/ sayfası, bunların köprünün çevresine nasıl ekleneceğini gösterir.
Gotenberg hizmetinin yaşam döngüsünü yönetmez. Dağıtım ve işletim /integrations/gotenberg/security-and-operations/ sayfasında ele alınmıştır.

Sürümler ve işlem sonrası

Açık kaynak yazılım (OSS) çekirdeği, dönüştürülen PDF’yi olduğu gibi yazabilir. Dönüştürülen belgeyi imzalamanız, bir PDF/A arşivleme profili oluşturmanız veya bir filigran uygulamanız gerekiyorsa, bu yetenekleri nextpdf/premium paketi sağlar. Köprünün kendisi sürüme bağlı değildir: bir PDF üretir. Bu PDF ile ne yaptığınız, ticari bir sürüme ihtiyaç duyup duymadığınızı belirler.

Pro sürümünde kullanılabilen PDF Advanced Electronic Signatures (PAdES) temeli yalnızca B-B düzeyindedir. Uzun süreli doğrulama (LTV) profilleri (B-T, B-LT, B-LTA), Pro sürümünün parçası değildir ve bu köprü tarafından sağlanmaz. Şu çıkarımı yapmayın: bu paketin varlığı, zaman damgası veya LTV yeteneğinin bulunduğu anlamına gelmez.

Ayrıca bakınız

/integrations/gotenberg/install/ — paketi kurun ve temel bir Gotenberg dağıtımı yapın.
/integrations/gotenberg/configuration/ — her yapılandırma seçeneği, türü, varsayılanı ve etkisi.
/integrations/gotenberg/quickstart/ — ilk dönüştürmenizi çalıştırın.
/integrations/gotenberg/production-usage/ — köprüyü gerçek bir uygulamaya bağlayın.
/integrations/gotenberg/troubleshooting/ — istisna kataloğu ve her istisnanın anlamı.
/integrations/gotenberg/security-and-operations/ — güvenlik modeli ve bağımlı hizmetin güvenli biçimde nasıl işletileceği.
/integrations/gotenberg/boot-and-discovery/ — barındırıcı çatıların köprüyü nasıl keşfedip bağladığı.
/integrations/gotenberg/integration/ — NextPDF işlemesini hizmet üzerinden yürütün.