نظرة عامة على NextPDF Gotenberg

لمحة سريعة

⁨NextPDF Gotenberg⁩ جسر صغير بين ⁨NextPDF⁩ وخدمة ⁨Gotenberg⁩ خارجية. استخدمه عندما يتعذّر على ⁨NextPDF⁩ عرض مستند ⁨Office⁩ محليًّا. يرسل الجسر المستند إلى نسخة ⁨Gotenberg⁩ عبر بروتوكول نقل النصوص الفائقة (⁨HTTP⁩)، ويتلقّى ناتجًا بصيغة المستندات المحمولة (⁨PDF⁩)، ثم يسلّم ملف ⁨PDF⁩ إلى تطبيقك. ومن هناك يتولّى ⁨NextPDF⁩ بقية المعالجة اللاحقة.

الحزمة صغيرة ومباشرة. فهي لا تضمّن محرك عرض، ولا تُشغّل ⁨LibreOffice⁩، ولا تُشغّل متصفحًا. يستخدم كل تحويل طلب ⁨HTTP⁩ واحدًا متعدّد الأجزاء (⁨multipart⁩) إلى نقطة نهاية ⁨Gotenberg.⁩ أنت من يشغّل نقطة النهاية تلك ويوجّه الجسر إليها في الإعدادات.

استخدم هذا الجسر عندما تكون لديك ملفات مصدرية من نوع .docx أو .xlsx أو .pptx أو .odt أو .ods أو .odp وتحتاج إلى ناتج ⁨PDF⁩ ضمن مسار ⁨NextPDF.⁩ بعد إنشاء ملف ⁨PDF⁩، يتولّى ⁨NextPDF⁩ أو nextpdf/premium التوقيع والتحويل إلى ⁨PDF/A⁩ وإضافة العلامة المائية والدمج.

ما الذي يعتمد عليه الجسر

للجسر اعتماد واحد في وقت التشغيل، وليس حزمة ⁨PHP⁩: خدمة ⁨Gotenberg⁩ قيد التشغيل يستطيع الجسر الوصول إليها عبر بروتوكول نقل النصوص الفائقة الآمن (⁨HTTPS⁩).

• الجسر لا يثبّت ⁨Gotenberg⁩ ولا يديره ولا يراقبه. أنت من ينشر ⁨Gotenberg⁩ بنفسك، والمشروع المنبع ينشر صورة حاوية. وأنت المسؤول عن توافرها وسعتها وانكشافها على الشبكة.
• يتواصل الجسر مع مسار تحويل ⁨LibreOffice⁩ الخاص بـ ⁨Gotenberg.⁩ يُبنى عنوان ⁨URL⁩ للطلب على هيئة <apiUrl>/forms/libreoffice/convert، حيث <apiUrl> هو عنوان ⁨URL⁩ الأساسي الذي تضبطه. يحدّد هذا المسار مجموعة الصيغ التي يدعمها الجسر.
• يرسل فحص السلامة طلب ⁨HTTP⁩ من نوع HEAD إلى <apiUrl>/health ويعدّ أي حالة أقل من 500 متاحة.

لأن التحويل يجري في خدمة تشغّلها بنفسك، يعتمد السلوك على إصدار ⁨Gotenberg⁩ الذي تشغّله. يرسل الجسر طلبًا ثابتًا متعدّد الأجزاء، ولا يفترض في ⁨Gotenberg⁩ إلا مسارَين: مسار الوجهة (/forms/libreoffice/convert) ومسار فحص السلامة (/health). راجع /⁨integrations/gotenberg/install/⁩ للاطلاع على خط أساس النشر، و/⁨integrations/gotenberg/security-and-operations/⁩ لتعزيز أمان الخدمة.

صيغ المستندات المدعومة

يحوّل الجسر الصيغ المعدودة في نوعه OfficeFormat فقط. ويكتشف كل صيغة من امتداد الملف. المطابقة غير حسّاسة لحالة الأحرف، ويُسمح بوجود نقطة في البداية. بعد ذلك يرسل الجسر كل ملف إلى ⁨Gotenberg⁩ بنوع ثابت من امتدادات بريد الإنترنت متعدّدة الأغراض (⁨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⁩	odt	application/vnd.oasis.opendocument.text
جدول بيانات ⁨OpenDocument⁩	ods	application/vnd.oasis.opendocument.spreadsheet
عرض تقديمي ⁨OpenDocument⁩	odp	application/vnd.oasis.opendocument.presentation

هذه القائمة كاملة. أي امتداد خارج هذه المجموعة يُطلق ValueError قبل إجراء أي طلب شبكي، لذلك لا يحاول الجسر أبدًا تنفيذ تحويل لا يستطيع وصفه. لا يدّعي الجسر دعم “أي ملف ⁨Office⁩” أو “جميع صيغ المستندات”. فهو يدعم الصيغ الست المذكورة أعلاه لأن الكود لا يتعرّف إلا على تلك الست، ومجموعة الاختبارات لا تختبر إلا تلك الست.

الصيغ الثنائية القديمة (.doc و.xls و.ppt)، والنص المنسّق (.rtf)، والنص العادي، والقيم المفصولة بفواصل (⁨CSV⁩)، وصيغ الصور ليست جزءًا من المجموعة التي يتعرّف عليها الجسر. قد يقبل مسار ⁨LibreOffice⁩ الخاص بـ ⁨Gotenberg⁩ نطاقًا أوسع من المدخلات. لكن الجسر يقصر نفسه عمدًا على المجموعة المعدودة كي يبقى اكتشاف الصيغة ونوع ⁨MIME⁩ وبيانات النتيجة الوصفية متّسقة وقابلة للتحقّق.

كيف يجري التحويل

التحويل عملية خطّية تمر مرة واحدة. يتحقّق الجسر من كل خطوة قبل أن تغادر أي بايتات العملية:

1. يُفحص الإعداد. عنوان ⁨URL⁩ فارغ لواجهة برمجة التطبيقات (⁨API⁩) يفشل فورًا باستثناء تحويل.
2. يُتحقّق من عنوان ⁨URL⁩ لواجهة ⁨API. HTTPS⁩ مطلوب، ويُحلّ المضيف ويُفحص كي لا يشير إلى عنوان خاص أو محجوز. تُلتقط مجموعة العناوين المحلولة لتثبيتها لاحقًا.
3. يُقرأ المُدخل (في تحويلات الملفات، يُحوَّل المسار إلى صورته القانونية أولًا لمنع اجتياز المسارات)، ويُربط امتداده بنوع OfficeFormat.
4. يفحص الجسر طول البايتات مقابل الحد الأقصى المضبوط، ويفحص اسم الملف بحثًا عن متتاليات الاجتياز والشُّرَط المائلة والبايتات الصفرية وأحرف التحكّم.
5. تُفحص مجموعة العناوين مرة أخرى قبل الطلب مباشرةً لسدّ الفجوة بين التحقّق والاتصال.
6. يبني الجسر متن طلب من نوع multipart/form-data ويرسله بطريقة ⁨POST⁩ إلى مسار ⁨LibreOffice⁩، مع رمز حامل (⁨bearer token⁩) إن كان مضبوطًا.
7. يحلّل الجسر الاستجابة. يجب أن تكون الحالة 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/.⁩

الإصدارات والمعالجة اللاحقة

يمكن لنواة البرمجيات مفتوحة المصدر (⁨OSS⁩) أن تكتب ملف ⁨PDF⁩ المُحوَّل كما هو. إذا احتجت إلى توقيع المستند المُحوَّل، أو إنتاج ملف تعريف أرشفة ⁨PDF/A⁩، أو تطبيق علامة مائية، فإن حزمة nextpdf/premium تضيف تلك القدرات. الجسر نفسه محايد تجاه الإصدار: فهو يُنتج ملف ⁨PDF.⁩ ما تفعله بذلك الملف ⁨PDF⁩ هو ما يحدّد حاجتك إلى إصدار تجاري.

خط أساس التوقيعات الإلكترونية المتقدّمة لملفات ⁨PDF⁩ (⁨PAdES⁩) المتوفّر في إصدار ⁨Pro⁩ هو ⁨B-B⁩ فقط. ملفات تعريف التحقّق طويل الأمد (⁨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⁩ عبر الخدمة.