เอกสารอ้างอิง NextPDF Connect API

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

หน้านี้เป็นเอกสารอ้างอิงระดับสัญลักษณ์สำหรับเซิร์ฟเวอร์ NextPDF Connect (nextpdf/server) โดยแสดงเครื่องมือแต่ละรายการตามชื่อที่ลงทะเบียนและคลาสที่นำไปใช้งาน พร้อมจัดทำเอกสารบริการ gRPC NextPDFConnect รวมถึงเมท็อด Remote Procedure Call (RPC) และข้อความคำขอและการตอบกลับ นอกจากนี้ยังกำหนดสัญญาด้านการยืนยันตัวตน ข้อผิดพลาด และขีดจำกัดอัตราที่ทรานสปอร์ตทุกตัวใช้ร่วมกัน

เซิร์ฟเวอร์เปิดเผยรีจิสทรีเครื่องมือชุดเดียวผ่านทรานสปอร์ตสามแบบ ได้แก่ Model Context Protocol (MCP) ผ่านอินพุตและเอาต์พุตมาตรฐาน, Representational State Transfer (REST) Application Programming Interface (API) และ gRPC ทรานสปอร์ตแต่ละแบบมีเอกสารรายละเอียดระดับไวร์แยกเป็นของตัวเอง ดู ทรานสปอร์ต MCP ทรานสปอร์ต REST และ ทรานสปอร์ต gRPC หน้านี้รวบรวมสัญลักษณ์ที่ทรานสปอร์ตเหล่านั้นรองรับ

ชื่อเครื่องมือ คลาส และระดับความเสี่ยงอ่านจากการนำเครื่องมือไปใช้งานใน src/Tools/ จำนวนเครื่องมือที่การดีพลอยเปิดเผยเป็นคุณสมบัติระดับรันไทม์ ดู แค็ตตาล็อกเครื่องมือ ส่วน การบูตและการค้นพบ อธิบายการแปลงระดับ

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

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

ทรานสปอร์ต	จุดเข้าใช้งาน	รูปแบบไวร์	การยืนยันตัวตน
MCP	bin/nextpdf-mcp	JavaScript Object Notation Remote Procedure Call (JSON-RPC) 2.0 ผ่าน stdio	ขอบเขตกระบวนการของระบบปฏิบัติการ (ไม่มี API key)
REST	bin/nextpdf-server	HTTP, OpenAPI 3.1	Bearer API key ใน Authorization เฮดเดอร์
gRPC	bin/nextpdf-grpc	Protocol Buffers แพ็กเกจ nextpdf.connect.v1	Bearer token ใน authorization เมทาดาทาของการเรียก

เมื่อใช้ MCP คุณเรียกเครื่องมือด้วย tools/call พร้อมชื่อเครื่องมือที่ลงทะเบียน เมื่อใช้ REST และ gRPC คุณเข้าถึงความสามารถของเอนจินชุดเดียวกันผ่านพื้นผิว render operation และ capability ดู ทรานสปอร์ต REST สำหรับตารางเส้นทาง และ ทรานสปอร์ต gRPC สำหรับตาราง RPC

การยืนยันตัวตนและระดับความเสี่ยง

การยืนยันตัวตนด้วย API key

ทรานสปอร์ต REST และ gRPC ต้องใช้ bearer API key สำหรับทุกคำขอ ยกเว้นการตรวจสอบสุขภาพที่ไม่ต้องยืนยันตัวตน คีย์อยู่ในรูปแบบ npk_live_{kid}_{secret} โดย kid เป็นตัวระบุยาวแปดอักขระสำหรับค้นหาเรกคอร์ด และส่วน secret เก็บค่าเอนโทรปี เซิร์ฟเวอร์จัดเก็บเฉพาะ SHA-256 digest ของคีย์ และเปรียบเทียบโทเค็นที่นำเสนอแบบเวลาคงที่ ดังนั้นคีย์ที่ไม่ถูกต้องจึงไม่รั่วไหลข้อมูลผ่านการจับเวลา REST อ่านโทเค็นจากเฮดเดอร์ Authorization: Bearer … ส่วน gRPC อ่านโทเค็นเดียวกันจากเมทาดาทาของการเรียก authorization ทรานสปอร์ต MCP stdio ไม่มี API key เนื่องจากเป็นกระบวนการย่อยในเครื่องที่ไคลเอนต์ผู้เรียกใช้งานเชื่อถือ ความปลอดภัยและการดำเนินงาน จัดทำเอกสารโมเดลการยืนยันตัวตนฉบับสมบูรณ์

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

เครื่องมือแต่ละตัวประกาศระดับความเสี่ยงหนึ่งรายการจากสี่ระดับที่จัดลำดับไว้ ซึ่งกำหนดโดย enum RiskLevel ใน src/Config/RiskLevel.php ของโค้ดเซิร์ฟเวอร์

ระดับ	กรณีของ enum	ค่า	ผลกระทบ
Safe	RiskLevel::Safe	0	อ่านอย่างเดียว ไม่มีผลข้างเคียง ดำเนินการได้อัตโนมัติ
Caution	RiskLevel::Caution	1	สร้างหรือแก้ไขสถานะในหน่วยความจำ ดำเนินการได้อัตโนมัติ บันทึกเพื่อการตรวจสอบ
Review	RiskLevel::Review	2	สร้างเอาต์พุตที่อาจถูกนำไปใช้ในทางที่ผิด ดำเนินการได้อัตโนมัติ บันทึกเพื่อการตรวจสอบ
ApprovalRequired	RiskLevel::ApprovalRequired	3	ทำลายข้อมูล มีผลทางกฎหมาย หรือสำคัญต่อความเป็นส่วนตัว ต้องมีการยืนยันจากมนุษย์

ความเสี่ยงที่มีผลจริงของเครื่องมือมาจากสองแหล่งเท่านั้น ได้แก่ การประกาศ riskLevel() ของเครื่องมือเอง และการกำหนดค่าเสริมโดยผู้ดำเนินการ ซึ่งทำได้เพียงเพิ่มความเสี่ยงเท่านั้น ไม่สามารถลดความเสี่ยงของเครื่องมือ ApprovalRequired ได้ ดู ระดับความเสี่ยง HITL และ การกำหนดค่า ประกอบ

ลำดับการใช้โทเค็นอนุมัติ

เมื่อคุณเรียกเครื่องมือ ApprovalRequired โดยไม่มีโทเค็นที่ถูกต้อง ConfirmationGate (src/Mcp/ConfirmationGate.php) จะคืนโทเค็นคำท้าทายแบบใช้ครั้งเดียวแทนการเรียกใช้เครื่องมือ เอเจนต์ส่งคำท้าทายต่อให้มนุษย์ จากนั้นเรียกเครื่องมือเดิมอีกครั้งพร้อมโทเค็นที่ออกให้ในอาร์กิวเมนต์ _confirmation_token โทเค็นผูกกับชื่อเครื่องมือ nonce แบบสุ่ม และเวลาคงอยู่ (TTL) 300 วินาที โทเค็นไม่ผูกกับอาร์กิวเมนต์ และไม่ใช่ข้อมูลรับรองสำหรับการยืนยันตัวตน เมื่อใช้ REST bearer API key ยังคงทำหน้าที่ยืนยันตัวตนของคำขอ และเกตเดียวกันจะทำงานในตัวดำเนินการเครื่องมือร่วมก่อนการดำเนินการที่ต้องผ่านเกต เมื่อใช้ gRPC เกตเดียวกันจะทำงานก่อนส่งต่อการดำเนินการ กลไกคำท้าทายและโทเค็นเหมือนกันในทุกทรานสปอร์ต

เครื่องมือและเอนด์พอยต์

ตารางนี้จัดทำเอกสารเครื่องมือแต่ละรายการตามชื่อเครื่องมือที่ลงทะเบียน (คอลัมน์ Symbol) และคลาสที่นำไปใช้งาน เครื่องมือจัดกลุ่มตามระดับและหมวดหมู่ คลาส Abstract Syntax Tree (AST) และ mutation ทั้งหมดอยู่ภายใต้ src/Tools/Ast และ src/Tools/Ast/Mutation คลาส extraction อยู่ภายใต้ src/Tools/Extraction ส่วนคลาสที่เหลืออยู่ภายใต้ src/Tools/Core

เครื่องมือเอกสารหลัก

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
create_pdf	page_size (ค่าเริ่มต้น A4), orientation (portrait/landscape), title, author ไม่มีรายการใดจำเป็น	สร้างเอกสารในหน่วยความจำที่มีหนึ่งหน้า ตั้งค่าเมทาดาทาเมื่อระบุไว้	JSON พร้อม document_id, page_count, page_size, orientation ในผลลัพธ์	คืนผลลัพธ์ข้อผิดพลาดพร้อมข้อความจากเอนจินเมื่อเกิดความล้มเหลว	คลาส CreatePdfTool ความเสี่ยง RiskLevel::Caution ระดับ core document_id ที่คืนกลับมาจะถูกส่งต่อไปยังการดำเนินการถัดไปทุกครั้ง
add_page	document_id (จำเป็น) ขนาดหน้าและการวางแนวเป็นทางเลือก	เพิ่มหนึ่งหน้าต่อท้ายเอกสาร	JSON พร้อมจำนวนหน้าใหม่	ผลลัพธ์ข้อผิดพลาดเมื่อ document_id ไม่เป็นที่รู้จัก	คลาส AddPageTool ความเสี่ยง RiskLevel::Caution ระดับ core
add_text	document_id (จำเป็น), text (จำเป็น) ตำแหน่งและสไตล์เป็นทางเลือก	เพิ่มข้อความในเอกสาร	JSON สรุปสถานะของเอกสาร	ผลลัพธ์ข้อผิดพลาดเมื่อ document_id ไม่เป็นที่รู้จัก	คลาส AddTextTool ความเสี่ยง RiskLevel::Caution ระดับ core
add_image	document_id (จำเป็น), source (จำเป็น: พาธไฟล์หรือ base64) การจัดวางเป็นทางเลือก	เพิ่มรูปภาพจากพาธหรือข้อมูล base64	JSON สรุปสถานะของเอกสาร	ผลลัพธ์ข้อผิดพลาดเมื่อ source อ่านไม่ได้ หรือ document_id ไม่เป็นที่รู้จัก	คลาส AddImageTool ความเสี่ยง RiskLevel::Caution ระดับ core
add_table	document_id (จำเป็น), html (จำเป็น)	เรนเดอร์ตาราง Hypertext Markup Language (HTML) ลงในเอกสาร	JSON สรุปสถานะของเอกสาร	ผลลัพธ์ข้อผิดพลาดเมื่อมาร์กอัปไม่ถูกต้อง หรือ document_id ไม่เป็นที่รู้จัก	คลาส AddTableTool ความเสี่ยง RiskLevel::Caution ระดับ core
set_font	document_id (จำเป็น), family (จำเป็น) ขนาดและสไตล์เป็นทางเลือก	ตั้งค่าฟอนต์สำหรับการดำเนินการข้อความที่ตามมา	JSON ยืนยันฟอนต์ที่ใช้งานอยู่	ผลลัพธ์ข้อผิดพลาดเมื่อฟอนต์ไม่เป็นที่รู้จัก หรือ document_id ไม่เป็นที่รู้จัก	คลาส SetFontTool ความเสี่ยง RiskLevel::Caution ระดับ core
output_pdf	document_id (จำเป็น), file_path (ทางเลือก), destroy (ค่าเริ่มต้น true)	ทำเอกสารให้เสร็จสมบูรณ์ เขียนไปยัง file_path หรือคืนค่า base64 เมื่อไม่ได้ระบุ และทำลายเอกสารตามค่าเริ่มต้น	JSON พร้อม file_path และ file_size หรือ base64 และ file_size ในผลลัพธ์	ผลลัพธ์ข้อผิดพลาดเมื่อ document_id ไม่เป็นที่รู้จัก ความล้มเหลวด้านการจำกัดพาธเมื่อเขียนนอกไดเรกทอรีฐาน	คลาส OutputPdfTool ความเสี่ยง RiskLevel::ApprovalRequired ระดับ core การเขียนไฟล์ต้องผ่านเกตยืนยัน ส่วนโหมด base64 ไม่ผ่านเกต
preview_layout	document_id (จำเป็น)	คืนสรุปเค้าโครงโดยไม่เรนเดอร์ PDF สุดท้าย	JSON สรุปเค้าโครง	ผลลัพธ์ข้อผิดพลาดเมื่อ document_id ไม่เป็นที่รู้จัก	คลาส PreviewLayoutTool ความเสี่ยง RiskLevel::Safe ระดับ core
parse_pdf	document_id (จำเป็น)	ตรวจสอบเมทาดาทาเชิงโครงสร้าง ได้แก่ จำนวนหน้า ฟอนต์ รูปภาพ การเข้ารหัสลับ และ Info Dictionary	JSON เมทาดาทาเชิงโครงสร้าง	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารผิดรูปแบบ	คลาส ParsePdfTool ความเสี่ยง RiskLevel::Safe ระดับ core ลงทะเบียนเฉพาะเมื่อ NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED เป็น true หรือ 1 เท่านั้น

เครื่องมือวินิจฉัยหลัก

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
diagnostic.doctor	ไม่มี	เรียกใช้การตรวจสอบสุขภาพและคืนข้อมูลวินิจฉัยสภาพแวดล้อมแบบมีโครงสร้าง	JSON รายงานสภาพแวดล้อม	ผลลัพธ์ข้อผิดพลาดเมื่อการตรวจสอบภายในล้มเหลว	คลาส DiagnosticDoctorTool ความเสี่ยง RiskLevel::Safe ระดับ core ไม่ต้องการเอกสารและไม่ต้องการการยืนยัน
diagnostic.capabilities	ไม่มี	แสดงรายการความสามารถพร้อมข้อมูลระดับและสถานะ	JSON รายการความสามารถ	ผลลัพธ์ข้อผิดพลาดเมื่อเกิดความล้มเหลวภายใน	คลาส DiagnosticCapabilitiesTool ความเสี่ยง RiskLevel::Safe ระดับ core
diagnostic.inspect	document_id (จำเป็น)	ตรวจสอบ PDF และคืนเมทาดาทาเชิงโครงสร้าง	JSON เมทาดาทาเชิงโครงสร้าง	ผลลัพธ์ข้อผิดพลาดเมื่อ document_id ไม่เป็นที่รู้จัก	คลาส DiagnosticInspectTool ความเสี่ยง RiskLevel::Safe ระดับ core
diagnostic.verify	document_id (จำเป็น) โปรไฟล์ PDF/A หรือ PDF/UA เป็นทางเลือก	ตรวจสอบความสมบูรณ์เชิงโครงสร้าง และตรวจสอบ PDF/A หรือ PDF/UA เป็นทางเลือกโดยสร้างกระบวนการย่อย VeraPDF	JSON รายงานการตรวจสอบ	ผลลัพธ์ข้อผิดพลาดเมื่อกระบวนการย่อยล้มเหลว หมดเวลา หรืออินพุตใหญ่เกินไป	คลาส DiagnosticVerifyTool ความเสี่ยง RiskLevel::Caution ระดับ core อินพุตถูกจำกัดไว้ที่ 50 เมบิไบต์ (MiB)

เครื่องมือบาร์โค้ดหลัก

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
generate_barcode	payload (จำเป็น), format (ตัวอย่างเช่น QR Code, DataMatrix)	สร้างเมทริกซ์โมดูลบาร์โค้ดสองมิติจาก payload	JSON เมทริกซ์โมดูล	ผลลัพธ์ข้อผิดพลาดเมื่อ format ไม่รองรับ หรือ payload ไม่ถูกต้อง	คลาส BarcodeTool ความเสี่ยง RiskLevel::Caution ระดับ core BarcodeTool ลงทะเบียนเฉพาะเมื่อรีจิสทรี encoder barcode ของ core มีอยู่ใน nextpdf/core ที่ติดตั้งไว้ ชื่อเครื่องมือที่ลงทะเบียนคือ generate_barcode

เครื่องมือความเป็นส่วนตัว Enterprise

เครื่องมือเหล่านี้ห่อหุ้มคลาสความเป็นส่วนตัวของ Enterprise และลงทะเบียนภายใต้ระดับ Enterprise เฉพาะเมื่อคลาสเหล่านั้นออโตโหลดได้ เครื่องมือเหล่านี้ทำงานกับเนื้อหาแบบข้อความล้วน

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
redact_pdf	content (จำเป็น) ตัวเลือกการตรวจจับเป็นทางเลือก	ลบข้อมูลส่วนบุคคลที่ระบุตัวตนได้ (PII) จากเนื้อหาแบบข้อความล้วนแบบทำลายข้อมูล โดยใช้เอนจินการลบของ Enterprise	JSON พร้อมเนื้อหาที่ลบแล้วและแฮช SHA-256	ผลลัพธ์ข้อผิดพลาดเมื่อไม่มีคลาส Enterprise หรือการตรวจจับล้มเหลว	คลาส RedactPdfTool ความเสี่ยง RiskLevel::Review ระดับ enterprise
deidentify_pdf	content (จำเป็น), strategy (redact หรือ suppress)	ใช้กลยุทธ์การลบการระบุตัวตนอย่างเป็นระบบกับเนื้อหาแบบข้อความล้วนโดยใช้ตัวลบการระบุตัวตนของ Enterprise	JSON พร้อมเนื้อหาที่ลบการระบุตัวตนแล้ว	ผลลัพธ์ข้อผิดพลาดเมื่อไม่มีคลาส Enterprise	คลาส DeIdentifyPdfTool ความเสี่ยง RiskLevel::Review ระดับ enterprise
zone_redact_pdf	content (จำเป็น), zones (หน้าพร้อมรายการสี่เหลี่ยมผืนผ้าที่ปรับมาตรฐานแล้ว)	ใช้การลบโซนตามพิกัดโดยใช้เอนจินการลบของ Enterprise	JSON พร้อมเนื้อหาที่ลบแล้ว	ผลลัพธ์ข้อผิดพลาดเมื่อโซนไม่ถูกต้อง หรือไม่มีคลาส Enterprise	คลาส ZoneRedactionTool ความเสี่ยง RiskLevel::Review ระดับ enterprise

เครื่องมืออ่าน Abstract syntax tree (AST)

เครื่องมือเหล่านี้มาพร้อมกับเซิร์ฟเวอร์ ลงทะเบียนภายใต้ระดับ Pro และควบคุมด้วย NEXTPDF_AST_TOOLS_ENABLED (เปิดใช้งานตามค่าเริ่มต้น) เครื่องมือทุกตัวอ่านอย่างเดียว

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
get_document_ast	pdf_data (จำเป็น)	สร้าง AST เชิงความหมาย ซึ่งเป็นทรีโหนดเต็มพร้อมจุดยึดการอ้างอิงสำหรับองค์ประกอบเชิงโครงสร้างทุกรายการ	JSON ทรีโหนดพร้อม ETag สำหรับการควบคุมการทำงานพร้อมกัน	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารผิดรูปแบบ	คลาส GetDocumentAstTool ความเสี่ยง RiskLevel::Safe ระดับ pro
get_ast_node	pdf_data (จำเป็น), node_id (จำเป็น)	ดึงโหนด AST เดียวและโหนดลูกทั้งหมด	JSON โหนดพร้อมโหนดลูก	ผลลัพธ์ข้อผิดพลาดเมื่อ node_id ไม่เป็นที่รู้จัก	คลาส GetAstNodeTool ความเสี่ยง RiskLevel::Safe ระดับ pro
get_ast_diff	original_pdf_data (จำเป็น), modified_pdf_data (จำเป็น)	เปรียบเทียบโครงสร้างของเอกสารสองฉบับโดยเทียบ AST เชิงความหมาย	JSON โหนดที่เพิ่ม ลบ และเปลี่ยนแปลง	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารอินพุตผิดรูปแบบ	คลาส GetAstDiffTool ความเสี่ยง RiskLevel::Safe ระดับ pro
search_ast_nodes	pdf_data (จำเป็น) ตัวกรองประเภท ดัชนีหน้า และข้อความเป็นทางเลือก	ค้นหาโหนด AST ตามประเภท ดัชนีหน้า หรือเนื้อหาข้อความ	JSON รายการแบบราบของโหนดที่ตรงกันพร้อมโหนดลูกระดับตื้น	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารผิดรูปแบบ	คลาส SearchAstNodesTool ความเสี่ยง RiskLevel::Safe ระดับ pro
extract_cited_text	pdf_data (จำเป็น), headings_only เป็นทางเลือก	ดึงบล็อกข้อความพร้อมจุดยึดการอ้างอิง (หน้า กรอบขอบเขต ความเชื่อมั่น)	JSON บล็อกข้อความที่อ้างอิง	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารผิดรูปแบบ	คลาส ExtractCitedTextTool ความเสี่ยง RiskLevel::Safe ระดับ pro หมวดหมู่ ast ของเครื่องมือ
extract_cited_tables	pdf_data (จำเป็น)	ดึงบล็อกตารางพร้อมจุดยึดการอ้างอิง คืนเมทริกซ์เซลล์ที่เรียงตามแถวต่อโหนด Table	JSON เมทริกซ์ตารางพร้อมจุดยึด	ผลลัพธ์ข้อผิดพลาดเมื่อเอกสารผิดรูปแบบ	คลาส ExtractCitedTablesTool ความเสี่ยง RiskLevel::Safe ระดับ pro หมวดหมู่ extraction ของเครื่องมือ

เครื่องมือ AST mutation

เครื่องมือเหล่านี้มาพร้อมกับเซิร์ฟเวอร์ ลงทะเบียนภายใต้ระดับ Pro และควบคุมด้วย NEXTPDF_MUTATION_TOOLS_ENABLED (เปิดใช้งานตามค่าเริ่มต้น) เครื่องมือทั้งสี่รายการเป็น ApprovalRequired และใช้การควบคุมการทำงานพร้อมกันแบบ optimistic (OCC) ผ่าน ETag

สัญลักษณ์ (Symbol)	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
apply_ast_mutations	pdf_data, etag, idempotency_key, mutations (จำเป็นทั้งหมด)	ใช้ชุด mutation แบบ atomic แล้วเล่นซ้ำผลลัพธ์ที่แคชไว้สำหรับ idempotency_key ที่ซ้ำกัน	JSON พร้อม PDF ที่ผ่าน mutation และ ETag ใหม่	ความขัดแย้ง OCC เมื่อ ETag ล้าสมัย ข้อผิดพลาดด้านการตรวจสอบเมื่อ mutation ผิดรูปแบบ	คลาส ApplyAstMutationsTool ความเสี่ยง RiskLevel::ApprovalRequired ระดับ pro
delete_ast_node	pdf_data, node_id, etag (จำเป็นทั้งหมด)	ลบโหนดในโหมดโอเวอร์เลย์ (เนื้อหาต้นฉบับถูกปิดทับ ไม่ได้ถูกลบทางกายภาพ)	JSON พร้อม PDF ที่ถูกแก้ไขและ ETag ใหม่	ความขัดแย้ง OCC เมื่อ ETag ล้าสมัย ข้อผิดพลาดเมื่อ node_id ไม่เป็นที่รู้จัก	คลาส DeleteAstNodeTool ความเสี่ยง RiskLevel::ApprovalRequired ระดับ pro
insert_ast_node	pdf_data, parent_node_id, position, etag, node (จำเป็นทั้งหมด)	แทรกโหนดใหม่เป็นโหนดลูกของโหนดแม่ที่ตำแหน่งที่ระบุ	JSON พร้อม PDF ที่ถูกแก้ไขและ ETag ใหม่	ความขัดแย้ง OCC เมื่อ ETag ล้าสมัย ข้อผิดพลาดด้านการตรวจสอบเมื่อโหนดผิดรูปแบบ	คลาส InsertAstNodeTool ความเสี่ยง RiskLevel::ApprovalRequired ระดับ pro
update_ast_node	pdf_data, node_id, etag, updates (จำเป็นทั้งหมด)	อัปเดตเนื้อหาข้อความของโหนด	JSON พร้อม PDF ที่ถูกแก้ไขและ ETag ใหม่	ความขัดแย้ง OCC เมื่อ ETag ล้าสมัย ข้อผิดพลาดเมื่อ node_id ไม่เป็นที่รู้จัก	คลาส UpdateAstNodeTool ความเสี่ยง RiskLevel::ApprovalRequired ระดับ pro

สคีมาคำขอและการตอบกลับ

ทรานสปอร์ต gRPC กำหนดสคีมาแบบมีชนิดสำหรับเซิร์ฟเวอร์ในแพ็กเกจ Protocol Buffers nextpdf.connect.v1 ใน proto/nextpdf/connect/v1/*.proto บริการและข้อความของบริการเป็นสัญลักษณ์สคีมาอย่างเป็นทางการ

บริการ NextPDFConnect

บริการ NextPDFConnect เปิดเผย RPC แบบ unary และ server-streaming สัญลักษณ์สคีมาคือชื่อเมท็อด RPC และข้อความคำขอและการตอบกลับที่เมท็อดเหล่านั้นรองรับ

RPC	ข้อความคำขอ	ข้อความการตอบกลับ	รูปแบบ
Render	RenderRequest	RenderResponse	Unary เรนเดอร์แบบ stateless และซิงโครนัส
RenderStream	RenderRequest	RenderChunk (stream)	Server-streaming ส่งผลการเรนเดอร์เป็นชังก์ที่เรียงลำดับแล้ว
SubmitJob	SubmitJobRequest	JobResponse	Unary ส่งงานเรนเดอร์แบบอะซิงโครนัส
GetJobStatus	GetJobStatusRequest	JobResponse	Unary สำรวจสถานะของงาน
GetJobResult	GetJobResultRequest	RenderResponse	Unary ดาวน์โหลดผลลัพธ์ที่เสร็จสมบูรณ์
GetJobResultStream	GetJobResultRequest	RenderChunk (stream)	Server-streaming ดาวน์โหลดผลลัพธ์ที่เสร็จสมบูรณ์เป็นชังก์
CancelJob	CancelJobRequest	JobResponse	Unary ยกเลิกหรือลบงาน
CreateSession	CreateSessionRequest	SessionResponse	Unary สร้างเซสชันสำหรับการสร้างเอกสาร
GetSession	GetSessionRequest	SessionResponse	Unary รับเมทาดาทาของเซสชัน
DestroySession	DestroySessionRequest	DestroySessionResponse	Unary ทำลายเซสชันและเอกสารของเซสชัน
SessionOperation	SessionOperationRequest	SessionResponse	Unary ดำเนินการกับเอกสารของเซสชัน
SessionRender	SessionRenderRequest	RenderResponse	Unary เรนเดอร์เอกสารของเซสชันเป็น PDF
SessionRenderStream	SessionRenderRequest	RenderChunk (stream)	Server-streaming เรนเดอร์เอกสารของเซสชันเป็นชังก์
ExecuteCapability	CapabilityRequest	CapabilityResponse	Unary ดำเนินการความสามารถที่ควบคุมตามระดับ
GetCapabilities	GetCapabilitiesRequest	GetCapabilitiesResponse	Unary แสดงรายการความสามารถสำหรับไคลเอนต์ที่ยืนยันตัวตนแล้ว
HealthCheck	HealthCheckRequest	HealthCheckResponse	Unary การตรวจสอบสภาพการทำงาน
ReadinessCheck	ReadinessCheckRequest	ReadinessCheckResponse	Unary การตรวจสอบความพร้อม

สัญลักษณ์ข้อความ

ข้อความคำขอและการตอบกลับเป็นสัญลักษณ์เชิงโครงสร้างของสคีมา ข้อความเรนเดอร์ ได้แก่ RenderRequest, RenderResponse และ RenderChunk แบบสตรีม รองรับขนาดหน้า การวางแนว การดำเนินการที่เรียงลำดับ และไบต์ PDF ผลลัพธ์ ข้อความงาน ได้แก่ SubmitJobRequest, GetJobStatusRequest, GetJobResultRequest, CancelJobRequest และ JobResponse ซึ่งจำลองวงจรชีวิตของงานแบบอะซิงโครนัส โดยเก็บเมทาดาทาของงานไว้ในข้อความ JobData ข้อความเซสชัน ได้แก่ CreateSessionRequest, SessionResponse, GetSessionRequest, DestroySessionRequest, DestroySessionResponse, SessionOperationRequest และ SessionRenderRequest ซึ่งจำลองวงจรชีวิตของเซสชันแบบ stateful โดยเก็บเมทาดาทาของเซสชันไว้ในข้อความ SessionData ข้อความความสามารถ ได้แก่ CapabilityRequest, CapabilityResponse, GetCapabilitiesRequest และ GetCapabilitiesResponse รองรับการส่งต่อและการสำรวจการดำเนินการที่ควบคุมตามระดับ ข้อความระบบ ได้แก่ HealthCheckRequest, HealthCheckResponse, ReadinessCheckRequest และ ReadinessCheckResponse รองรับสถานะ liveness และ readiness

ไฟล์ .proto ที่จัดส่งมาเป็นสัญญาระดับไวร์อย่างเป็นทางการ ดูเอกสารอ้างอิงของทรานสปอร์ต gRPC ได้ที่ ทรานสปอร์ต gRPC ประกอบ

โมเดลข้อผิดพลาด

เซิร์ฟเวอร์รายงานความล้มเหลวผ่านกลไกข้อผิดพลาดเนทีฟของแต่ละทรานสปอร์ต ทรานสปอร์ตแต่ละตัวคงเงื่อนไขเชิงตรรกะเดียวกันไว้ ต่างกันเฉพาะวิธีเข้ารหัส

MCP

ข้อผิดพลาด MCP เป็นอ็อบเจกต์ข้อผิดพลาด JSON-RPC 2.0 เมท็อดที่ไม่รู้จักจะคืน method-not-found (-32601) ข้อความที่ไม่ใช่ JSON-RPC ที่ถูกต้องจะคืน invalid-request (-32600) อินพุตที่แยกวิเคราะห์ไม่ได้จะคืน parse-error (-32700) เครื่องมือที่ล้มเหลวจะคืนการตอบกลับ JSON-RPC ที่สำเร็จ โดยเนื้อหาทำเครื่องหมายว่าเป็นข้อผิดพลาด แทนที่จะคืนข้อผิดพลาดระดับทรานสปอร์ต เพื่อให้เอเจนต์อ่านข้อความได้ คำท้าทายการยืนยันสำหรับเครื่องมือ ApprovalRequired ก็เป็นการตอบกลับที่สำเร็จเช่นกัน ไม่ใช่ข้อผิดพลาด

REST

REST ใช้รหัสสถานะ Hypertext Transfer Protocol (HTTP) ตามความหมายที่ RFC 9110 กำหนด 200 ส่งผลลัพธ์ 400 ถูกคืนเมื่อฟิลด์คำขอไม่ผ่านการตรวจสอบรูปแบบ 401 ถูกคืนเมื่อไม่มี API key ที่ถูกต้องส่งมา พร้อมเฮดเดอร์คำท้าทาย WWW-Authenticate: Bearer 403 ถูกคืนเมื่อระดับของคีย์ที่ถูกต้องไม่มีสิทธิ์ในการดำเนินการ 404 ถูกคืนเมื่อเส้นทางที่ควบคุมตามระดับไม่ได้ลงทะเบียนเนื่องจากไม่มีแพ็กเกจของเส้นทางนั้น เนื้อหาข้อผิดพลาดที่เครื่องอ่านได้เป็นเอกสาร Problem Details ตาม RFC 9457 ให้บริการด้วยมีเดียไทป์ application/problem+json และ Uniform Resource Identifier (URI) type ที่คงที่สำหรับแต่ละเงื่อนไข ความล้มเหลวด้านการตรวจสอบระดับฟิลด์จะแสดงไว้ในเนื้อหา เพื่อเสริมการป้องกัน path traversal document_id ที่ไม่ตรงกับรูปแบบ doc_[a-f0-9]{24} จะถูกปฏิเสธด้วย 400 ก่อนที่เครื่องมือจะทำงาน ทรานสปอร์ต REST จัดทำเอกสารไปป์ไลน์มิดเดิลแวร์และตารางเส้นทางของ REST

gRPC

gRPC ใช้รหัสสถานะ gRPC มาตรฐาน โทเค็นที่ขาดหาย ผิดรูปแบบ ไม่รู้จัก ถูกปิดใช้งาน หรือหมดอายุ จะทำให้การเรียกล้มเหลวด้วย UNAUTHENTICATED แทนที่จะเป็นสถานะ HTTP รายละเอียดข้อผิดพลาดแบบสมบูรณ์สะท้อนรูปแบบ Problem Details ของ REST และบรรจุไว้ในรายละเอียดสถานะ gRPC ดังนั้น URI type ของข้อผิดพลาดจึงสอดคล้องกันในทุกทรานสปอร์ต

ดูเพิ่มเติมที่ RFC 9110 (HTTP Semantics) สำหรับความหมายของรหัสสถานะ และ RFC 9457 (Problem Details for HTTP APIs) สำหรับรูปแบบเนื้อหาข้อผิดพลาด

• RFC 9110: https://www.rfc-editor.org/rfc/rfc9110
• RFC 9457: https://www.rfc-editor.org/rfc/rfc9457

ขีดจำกัดอัตราและโควตา

ทรานสปอร์ต REST ใช้การจำกัดอัตราต่อที่อยู่ Internet Protocol (per-IP) และต่อไคลเอนต์ในไปป์ไลน์มิดเดิลแวร์ พร้อมขีดจำกัดขนาดเนื้อหา ขีดจำกัด payload ตามระดับ และเวลาหมดต่อคำขอ เพดานเหล่านี้เป็นค่าการกำหนดค่า ไม่ใช่ค่าคงที่ที่กำหนดตายตัวในโค้ด:

• เพดาน payload ต่อระดับ (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit) และเวลาหมดที่ตรงกันมีผลกับ REST ตามระดับของคีย์ที่ยืนยันตัวตนแล้ว ดู การกำหนดค่า ประกอบ
• ที่เก็บเอกสารในหน่วยความจำถูกจำกัดด้วย max_documents (ค่าเริ่มต้น 50) และ document_ttl (ค่าเริ่มต้น 1800 วินาที)
• สถานะการจำกัดอัตราและ idempotency เป็นแบบต่อ worker เว้นแต่จะกำหนดค่า NEXTPDF_REDIS_HOST สำหรับที่เก็บแบบใช้ร่วมกัน ดู การดีพลอย ประกอบ

เมื่อใช้ที่เก็บการจำกัดอัตราและ idempotency ร่วมกัน การส่งงานแบบอะซิงโครนัสที่เหมือนกันซ้ำจะถูกขจัดความซ้ำซ้อนด้วย idempotency_key ทรานสปอร์ต MCP จัดการคำขอทีละรายการผ่านไปป์ และขจัดความซ้ำซ้อนของ id ของคำขอที่ซ้ำกันจากบัฟเฟอร์ขนาด 64 รายการ แทนการใช้การจำกัดอัตราเครือข่าย

หมายเหตุการพัฒนา

• อ่านชื่อเครื่องมือ คลาส และระดับความเสี่ยงจากซอร์สภายใต้ src/Tools/ อย่าสมมติว่าจำนวนรวมเป็นค่าตายตัว สอบถามเซิร์ฟเวอร์ที่กำลังทำงานอยู่เพื่อรับจำนวนอย่างเป็นทางการ ตามที่แสดงใน แค็ตตาล็อกเครื่องมือ ประกอบ
• สร้าง gRPC client stub ใหม่จากไฟล์ proto/nextpdf/connect/v1/*.proto ที่จัดส่งมา แพ็กเกจและเนมสเปซคือ nextpdf.connect.v1 อย่าแก้ไขคลาสข้อความที่สร้างขึ้นด้วยมือ
• เครื่องมือ ApprovalRequired ตอบกลับด้วยคำท้าทายการยืนยันในการเรียกครั้งแรก สร้างเส้นทางลองใหม่ — ส่งคำท้าทายต่อ แล้วเรียกอีกครั้งด้วย _confirmation_token — ก่อนนำส่งการผสานรวมที่ขับเคลื่อน output_pdf หรือเครื่องมือ mutation ใดก็ตาม
• เส้นทางหรือความสามารถที่ควบคุมตามระดับซึ่งไม่ได้ติดตั้งไว้ไม่ใช่ความล้มเหลวด้านการยืนยันตัวตน REST คืน 404 สำหรับเส้นทางที่ไม่มี และ gRPC ExecuteCapability รายงานว่าการดำเนินการนั้นไม่พร้อมใช้งาน ให้ถือว่าการไม่มีระดับ Pro หรือ Enterprise เป็นการทำงานที่คาดหวังได้ ไม่ใช่ความผิดพลาด
• เก็บ API key ไว้นอกการควบคุมเวอร์ชันของซอร์ส โหลดคีย์จากไฟล์ลับ และเลือกใช้ที่เก็บคีย์แบบไฟล์ที่โหลดใหม่อัตโนมัติ เพื่อให้หมุนเวียนคีย์ได้โดยไม่ต้องรีสตาร์ต ดู ความปลอดภัยและการดำเนินงาน ประกอบ

ดูเพิ่มเติม

• คู่มือนักพัฒนา — สถาปัตยกรรม วงจรชีวิต จุดขยาย และเช็คลิสต์การทดสอบ
• แค็ตตาล็อกเครื่องมือ — ชุดเครื่องมือหลักที่ผ่านการตรวจสอบและจำนวนตามระดับรันไทม์
• ระดับความเสี่ยง HITL — โมเดลความเสี่ยงและคำท้าทายการยืนยัน
• ทรานสปอร์ต MCP · ทรานสปอร์ต REST · ทรานสปอร์ต gRPC — รายละเอียดระดับไวร์ต่อทรานสปอร์ต
• ความปลอดภัยและการดำเนินงาน — การยืนยันตัวตน ความปลอดภัยของทรานสปอร์ต และโมเดลภัยคุกคาม