การฝังรูปภาพผ่าน NextPDF Connect

ภาพรวมโดยย่อ

ฝังรูปภาพลงในไฟล์ Portable Document Format (PDF) ผ่าน NextPDF Connect โดยใช้เส้นทางไฟล์ที่เซิร์ฟเวอร์อ่านได้ หรือ data URI แบบ base64 อินไลน์เป็นแหล่งที่มา คุณใช้ create_pdf, add_image และ output_pdf ซึ่งทั้งหมดเป็นเครื่องมือใน Core ของ NextPDF โดย NextPDF จะวาดรูปภาพเป็น image XObject ที่วาดด้วยตัวดำเนินการ Do (ISO 32000-2 §8.9)

การติดตั้ง

composer require nextpdf/server

หลังจากผูกทรานสปอร์ตแล้ว NextPDF รองรับรูปแบบแรสเตอร์ PNG, JPEG และ GIF

ภาพรวมเชิงแนวคิด

add_image รับ source และประมวลผลค่าตามลำดับคงที่นี้:

Data URI — สตริงที่ขึ้นต้นด้วย data: โดย NextPDF จะถอดรหัสชนิด Multipurpose Internet Mail Extensions (MIME) และเพย์โหลด base64 ไปยังไฟล์ชั่วคราว ฝังไฟล์นั้น แล้วลบไฟล์ชั่วคราว
Raw base64 — NextPDF ถอดรหัสสตริง base64 แบบยาวและถือว่าเป็น PNG
File path — NextPDF ถือว่าค่าอื่นทั้งหมดเป็นเส้นทางในระบบไฟล์ที่ กระบวนการเซิร์ฟเวอร์ ต้องอ่านได้

รูปภาพจะปรากฏที่ตำแหน่ง x/y ในหน่วยของผู้ใช้ (ค่าเริ่มต้นคือมิลลิเมตร) หากส่งเฉพาะ width NextPDF จะคำนวณความสูงเพื่อรักษาอัตราส่วนภาพ หากส่งทั้ง width และ height NextPDF จะปรับขนาดรูปภาพให้ตรงกับขนาดที่ระบุพอดี ออบเจ็กต์ที่ฝังเป็นออบเจ็กต์ภายนอกที่วาดลงในเนื้อหาหน้า (ISO 32000-2 §8.8)

ส่วนติดต่อ API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชัน	ปลอดภัย
`add_image`	ฝังรูปภาพจากเส้นทางหรือ data URI	ควรระวัง
`output_pdf`	เรนเดอร์และส่งคืน PDF	ต้องได้รับอนุมัติ / ตรวจทาน (base64)

เอกสารแค็ตตาล็อกเครื่องมือเป็นแค็ตตาล็อกหลักสำหรับอ้างอิง เครื่องมือที่ใช้ได้ขึ้นอยู่กับระดับที่ติดตั้ง

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

create_pdf (A4 แนวตั้ง, ชื่อเรื่อง) → document_id
add_image โดยตั้ง source เป็นเส้นทางสัมบูรณ์, x, y, width
add_image โดยตั้ง source เป็น URI แบบ data:image/png;base64,... และระบุ width และ height อย่างชัดเจน
output_pdf → base64

ตัวอย่างโค้ด — การใช้งานจริง

ใช้ data URI สำหรับรูปภาพที่โฮสต์สร้างขึ้นในหน่วยความจำ เช่น การเรนเดอร์แผนภูมิหรือภาพหน้าจอ ใช้เส้นทางไฟล์สำหรับแอสเซตที่มีอยู่แล้วบนเซิร์ฟเวอร์ และใช้เส้นทางสัมบูรณ์เสมอ เส้นทางสัมพัทธ์จะถูกตีความเทียบกับไดเรกทอรีทำงานของ เซิร์ฟเวอร์ ซึ่งโดยทั่วไปไม่ใช่ของโฮสต์ ก่อนดำเนินการต่อ โปรดยืนยันว่าการตอบกลับจาก add_image รายงานว่ารูปภาพอยู่บนหน้าที่คาดไว้

กรณีขอบและข้อควรระวัง

ไม่พบเส้นทาง เส้นทางไฟล์ที่ไม่มีอยู่จะคืนข้อผิดพลาดว่าไม่พบรูปภาพ
รูปแบบที่ไม่รองรับ NextPDF ปฏิเสธ SVG, BMP และ WebP โปรดแปลงรูปภาพล่วงหน้า
base64 / data URI ที่ผิดรูปแบบ เพย์โหลดที่ไม่ถูกต้องหรือ data URI ที่ขาดเครื่องหมายจุลภาคคั่นจะคืนข้อผิดพลาดในการถอดรหัส
รูปภาพขนาดเกิน รูปภาพที่ใหญ่กว่าหน้าจะถูกตัดที่ขอบ ไม่ใช่ถูกปฏิเสธ ให้คำนวณ width/height เทียบกับขนาดหน้าหลังหักระยะขอบ (A4 แนวตั้งคือ 210×297 มม.)

ประสิทธิภาพ

ขนาดไฟล์ผลลัพธ์เพิ่มขึ้นตามเนื้อหารูปภาพ รูปภาพขนาดเล็กสองรูปโดยทั่วไปอยู่ที่ 10–50 KB งบประมาณสำหรับการฝังรูปภาพกว้างกว่างบประมาณแบบข้อความอย่างเดียว หน้านี้ใช้ structural เป็นโปรไฟล์

หมายเหตุด้านความปลอดภัย

โหมดเส้นทางไฟล์อ่านจากระบบไฟล์ของเซิร์ฟเวอร์ด้วยสิทธิ์ของกระบวนการเซิร์ฟเวอร์ จึงต้องจำกัดว่าโฮสต์ส่งเส้นทางใดได้บ้าง อย่าให้ผู้เรียกที่ไม่น่าเชื่อถือชี้ source ไปยังไฟล์ใดๆบนเซิร์ฟเวอร์ได้ตามอำเภอใจ โหมด base64 นำไบต์มาแบบอินไลน์ จึงหลีกเลี่ยงการเปิดเผยเส้นทางบนเซิร์ฟเวอร์

ความสอดคล้อง

ข้อความระบุ	ข้อกำหนด	ข้อกำหนดย่อย	รหัสอ้างอิง (reference_id)
รูปภาพคือ image XObject ที่ตัวดำเนินการ `Do` วาดขึ้น	ISO 32000-2	§8.9
รูปภาพเป็นออบเจ็กต์ภายนอกที่วาดลงในเนื้อหาหน้า	ISO 32000-2	§8.8

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — เครื่องมือทั้งหมดรวมอยู่ใน Core

ความพร้อมใช้งานของทรานสปอร์ต

ทรานสปอร์ต	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	เพย์โหลด base64 ขนาดใหญ่จะทำให้เฟรม stdio มีขนาดใหญ่ขึ้น
REST	ใช่	สำหรับแอสเซตขนาดใหญ่ควรเลือกใช้ multipart หรือเส้นทางบนเซิร์ฟเวอร์
gRPC	ใช่	แบบ unary; ขีดจำกัดขนาดข้อความมีผลกับ base64 แบบอินไลน์

ระดับความเสี่ยง HITL

create_pdf อยู่ในระดับ Safe, add_image อยู่ในระดับ Caution และ output_pdf อยู่ในระดับ Approval Required — ในโหมด base64 จะลดระดับเป็น Review การอ่านในโหมดเส้นทางเกิดขึ้นฝั่งเซิร์ฟเวอร์และไม่ได้ถูกควบคุมแยกต่างหาก จึงควรจำกัดที่ชั้นนโยบาย (ระดับความเสี่ยง HITL)

ซอง JSON ของเกตยืนยัน

ผลลัพธ์ base64 อยู่ในตำแหน่งนี้:

{ "allowed": true }