สร้าง PDF ฉบับแรกของคุณด้วย NextPDF Connect

ภาพรวมโดยสังเขป

สูตรนี้แสดงขั้นตอนที่สั้นที่สุดจากเซสชันว่างเปล่าไปเป็น PDF ที่เรนเดอร์แล้วด้วย NextPDF Connect คุณสร้างเอกสาร A4 หน้าเดียว เพิ่มหัวเรื่องและหัวเรื่องรอง จากนั้นส่งคืนไฟล์เป็น base64 เครื่องมือ Core ที่ใช้มีสามรายการ ได้แก่ create_pdf, add_text และ output_pdf คุณไม่จำเป็นต้องใช้ฟอนต์ รูปภาพ หรือระดับผลิตภัณฑ์ที่มีใบอนุญาต

ทรานสปอร์ตของ Connect ส่งการเรียกเครื่องมือแต่ละครั้งเป็นคำขอ และส่งคืนผลลัพธ์ของเครื่องมือเป็นการตอบกลับ เลเยอร์ทรานสปอร์ตเป็นอิสระจากผลลัพธ์ที่เครื่องมือรายงาน (PSR-18 §p2)

การติดตั้ง

ติดตั้ง NextPDF Server และตั้งค่าทรานสปอร์ต:

composer require nextpdf/server

รันเซิร์ฟเวอร์ด้วยทรานสปอร์ตที่โฮสต์ของคุณคาดหวัง ได้แก่ Model Context Protocol ผ่าน stdio, REST หรือ gRPC ดู ความพร้อมใช้งานของทรานสปอร์ต ด้านล่าง เครื่องมือในสูตรนี้เป็นเครื่องมือ Core ซึ่งมาพร้อมกับเซิร์ฟเวอร์ คุณจึงไม่จำเป็นต้องใช้แพ็กเกจ Pro หรือ Enterprise

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

เซสชัน Connect เป็นที่เก็บเอกสารฝั่งเซิร์ฟเวอร์ที่ใช้ document_id เป็นคีย์ create_pdf เปิดเซสชันและส่งคืน id การเรียกเครื่องมือครั้งถัดๆ ไปจะใช้ id นั้น เอกสารเริ่มต้นด้วยหน้าว่างหนึ่งหน้า page tree เป็นโครงสร้างที่ตัวอ่านใช้เข้าถึงแต่ละหน้า (ISO 32000-2 §7.7.3) ตามค่าเริ่มต้น output_pdf จะเรนเดอร์เซสชันออกเป็น PDF แล้วทำลายเซสชันเพื่อคืนหน่วยความจำ

เมื่อคุณเรียก add_text โดยไม่ระบุ x หรือ y อย่างชัดเจน ข้อความจะไหลเข้าสู่ตำแหน่งโดยอัตโนมัติ ข้อความจะเริ่มที่เคอร์เซอร์ปัจจุบัน จากนั้นเคอร์เซอร์จะเลื่อนต่อไปหลังการเรียกแต่ละครั้ง

พื้นผิว API

รีจิสทรีของเครื่องมือจะแก้ชื่อเครื่องมือเหล่านี้เมื่อเซิร์ฟเวอร์เริ่มทำงาน ชื่อที่แสดงในที่นี้คือชื่อโปรโตคอลของรีจิสทรี แคตตาล็อกอ้างอิงคือ tool catalog ที่รวมไว้แล้ว เครื่องมือที่พร้อมใช้งานขึ้นอยู่กับระดับที่ติดตั้ง แต่ทั้งสามรายการนี้มีอยู่ใน Core เสมอ

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชันเอกสาร	ปลอดภัย
`add_text`	เขียนข้อความลงในเอกสาร	ใช้ความระมัดระวัง
`output_pdf`	เรนเดอร์และส่งคืน PDF	ต้องได้รับอนุมัติ (โหมดไฟล์) / ตรวจทาน (base64)

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

โฮสต์เรียกเครื่องมือสามครั้งตามลำดับ:

เรียก create_pdf ด้วย page_size: "A4", orientation: "portrait" พร้อมชื่อเรื่องและผู้สร้างเอกสาร เซิร์ฟเวอร์ส่งคืน document_id
เรียก add_text ด้วย document_id นั้น พร้อมข้อความหัวเรื่อง font_size ขนาดใหญ่ width: 0 (ความกว้างเต็มของเนื้อหา) และ alignment: "center"
เรียก output_pdf ด้วย document_id เมื่อไม่ระบุ file_path เซิร์ฟเวอร์จะส่งคืน PDF เป็น base64 และทำลายเซสชัน

ต่อไปนี้คืออ็อบเจ็กต์อาร์กิวเมนต์ create_pdf แบบขั้นต่ำ:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

การตอบกลับมี document_id จำนวนหน้า และเรขาคณิตของหน้า ให้ถือว่า id เป็นค่าทึบแสง และอย่าอนุมานความหมายจาก id นั้น

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

ผู้เรียกในการใช้งานจริงจะตรวจสอบการตอบกลับแต่ละครั้งก่อนเรียกครั้งถัดไป ผู้เรียกจะไม่นำ document_id กลับมาใช้ซ้ำหลังจาก output_pdf ทำลายเซสชันไปแล้ว

create_pdf — ยืนยันว่าการตอบกลับมี document_id หากเซิร์ฟเวอร์ส่งคืนข้อผิดพลาดว่าเกินขีดจำกัดเซสชัน ให้ปล่อยเซสชันที่ไม่ได้ใช้แล้วลองอีกครั้ง
add_text (หัวเรื่อง) — ยืนยันว่าการตอบกลับส่งคืน position
add_text (หัวเรื่องรอง) — ใช้ font_size ที่เล็กกว่า เคอร์เซอร์จะอยู่ต่อจากขอบล่างของหัวเรื่อง
output_pdf — อ่านฟิลด์ base64 แล้วถอดรหัสเป็นไบต์ แฟล็ก destroyed ยืนยันว่าเซสชันหายไปแล้ว

ไฟล์จะถูกส่งกลับมาแบบอินไลน์ (โหมด base64) จึงไม่มีผลข้างเคียงต่อระบบไฟล์และไม่มีด่านอนุมัติจากมนุษย์ ดู ระดับความเสี่ยง HITL

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

เซสชันที่ถูกทำลาย หลังจาก output_pdf ทำงานด้วยค่าเริ่มต้น destroy: true แล้ว document_id จะไม่ถูกต้องอีกต่อไป การเรียกใดๆ ในภายหลังที่ใช้ id นั้นจะส่งคืนข้อผิดพลาดเอกสารที่ไม่รู้จัก ให้สร้างเซสชันใหม่แทน
ขนาดหน้าที่ไม่รู้จัก เซิร์ฟเวอร์ปฏิเสธ page_size ที่ไม่รู้จัก และส่งคืนข้อผิดพลาดที่ชัดเจน ใช้ขนาดที่เอกสารระบุไว้ (A3, A4, A5, A6, Letter, Legal, Tabloid)
ข้อความว่างเปล่า text ที่ว่างเปล่าจะสร้างรายการที่มีความกว้างเป็นศูนย์ ไม่ใช่ข้อผิดพลาด ตรวจสอบอินพุตก่อนเรียก
ขีดจำกัดเซสชัน ที่เก็บข้อมูลในหน่วยความจำจำกัดจำนวนเซสชันที่ทำงานพร้อมกัน ปล่อยเซสชันโดยเร็วด้วย output_pdf

ประสิทธิภาพ

หน้าเดียวที่มีเฉพาะข้อความเรนเดอร์ได้ดีภายในงบประมาณของหน้านี้ และโดยปกติเอาต์พุตมีขนาด 1–3 KB สูตรนี้ใช้โปรไฟล์การทำซ้ำแบบเรนเดอร์สองครั้ง structural PDF มี /ID ในส่วนท้าย (trailer) และมีไทม์สแตมป์ที่เปลี่ยนไปในแต่ละครั้งที่รัน ดังนั้นการเปรียบเทียบแบบโครงสร้างหลังนอร์มัลไลซ์จึงเป็นวิธีที่แม่นยำ

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

เส้นทาง base64 ไม่มีผลข้างเคียงต่อระบบไฟล์ เส้นทางเอาต์พุตแบบไฟล์มีผลข้างเคียงดังกล่าว และถูกกำกับด้วยด่านควบคุม ดูส่วน HITL ให้ถือว่า base64 ที่ส่งคืนมาเป็นเนื้อหาเอกสาร ไม่ใช่ช่องทางที่เชื่อถือได้ ค่านี้คือไบต์ที่เครื่องมือสร้างขึ้นทุกประการ

ความสอดคล้องตามมาตรฐาน

ข้อความระบุ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
ทรานสปอร์ตส่งคำขอและรับการตอบกลับโดยไม่ขึ้นกับผลลัพธ์	PSR-18	§p2
เข้าถึงหน้าต่างๆ ได้ผ่าน page tree ของเอกสาร	ISO 32000-2	§7.7.3

สูตรนี้อธิบายวิธีที่เซิร์ฟเวอร์สร้างเอาต์พุต แต่ไม่ได้กำหนดความสอดคล้องตามโปรไฟล์

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

ไม่เกี่ยวข้อง — เครื่องมือทั้งสามรายการเป็น Core

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

ทรานสปอร์ต	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	การเรียกเครื่องมือจับคู่กับ MCP `tools/call`
REST	ใช่	เครื่องมือแต่ละรายการเป็นการดำเนินการ REST ผลลัพธ์คือเนื้อหาของการตอบกลับ
gRPC	ใช่	เครื่องมือแต่ละรายการเป็นการเรียกแบบ unary

ผลลัพธ์ของเครื่องมือเหมือนกันในทุกทรานสปอร์ต ต่างกันเพียงรูปแบบการห่อหุ้ม (framing) เท่านั้น ผลลัพธ์ที่ไม่สำเร็จยังคงเป็นการตอบกลับปกติ ไม่ใช่ความล้มเหลวของทรานสปอร์ต (PSR-18 §p2)

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

เซิร์ฟเวอร์จัดการเรียกเครื่องมือแต่ละครั้งไว้ในลำดับระดับความเสี่ยงแบบมีมนุษย์ร่วมในกระบวนการ (HITL) ได้แก่ ปลอดภัย (0) → ใช้ความระมัดระวัง (1) → ตรวจทาน (2) → ต้องได้รับอนุมัติ (3) create_pdf อยู่ในระดับปลอดภัย และ add_text อยู่ในระดับใช้ความระมัดระวัง output_pdf อยู่ในระดับต้องได้รับอนุมัติ แต่ใน โหมด base64 (ไม่มี file_path) จะลดระดับเป็นตรวจทานและทำงานโดยไม่ต้องมีการยืนยันจากมนุษย์ การเขียนลงไฟล์จะคงระดับไว้ที่ต้องได้รับอนุมัติ ดู output-approval และ เอกสารอ้างอิงระดับความเสี่ยง HITL

ซองข้อมูล JSON ของด่านยืนยัน

สูตรนี้ทำงานในโหมด base64 ดังนั้นด่านยืนยันจะส่งคืนซองข้อมูลอนุญาต:

{ "allowed": true }

ซองข้อมูลคำท้าทาย (allowed: false พร้อมสตริง challenge และ token แบบใช้ครั้งเดียว) มีอธิบายไว้ใน output-approval