คุณได้สร้างเอนด์พอยต์ที่รับไฟล์ ผู้ใช้อัปโหลดรูปโปรไฟล์ไปยัง POST /avatars หรือแอปของคุณพุช PDF ที่ลงนามแล้วไปยัง POST /documents เส้นทางนี้ทำงานได้ในความคิดของคุณ ตอนนี้คุณต้องพิสูจน์ว่ามันทำงานได้ผ่าน HTTP: เลือกไฟล์จริงแนบไปกับช่องฟอร์ม ส่งคำขอ และตรวจสอบการตอบกลับ
นี่คือจุดที่เครื่องมือ API จำนวนมากมีความซับซ้อน การอัปโหลดไฟล์ใช้ multipart/form-data ไม่ใช่ JSON ดังนั้นคุณจึงไม่สามารถวางบอดี้แล้วกดส่งได้ คุณต้องมีตัวสร้างคำขอที่เข้าใจช่องไฟล์ และตัวรันการทดสอบที่สามารถค้นหาไฟล์ได้เมื่อการทดสอบทำงานในภายหลัง Apidog จัดการได้ทั้งสองอย่าง และคู่มือนี้จะอธิบายเส้นทางทั้งหมด: การส่งไฟล์อัปโหลดเดียว การส่งไฟล์พร้อมกับ JSON การยืนยันการตอบกลับ และส่วนที่ซื่อสัตย์ที่ไม่มีใครเตือนคุณ นั่นคือสิ่งที่เกิดขึ้นเมื่อขั้นตอนการอัปโหลดเดียวกันนั้นทำงานแบบไร้ส่วนหัวใน Runner หรือ CLI และไม่พบไฟล์ หากคุณต้องการข้อมูลพื้นฐานเกี่ยวกับรูปแบบก่อน บทความพื้นฐานเกี่ยวกับ การอัปโหลดไฟล์ใน API ครอบคลุมวิธีการจัดโครงสร้างคำขอแบบ multipart ข้อมูลอ้างอิง FormData ของ MDN เป็นคู่มือที่ดีสำหรับฝั่งเบราว์เซอร์
multipart/form-data คืออะไร และเหตุใดการอัปโหลดจึงต้องใช้
เนื้อหาคำขอ API สามารถมีได้หลายรูปแบบ ในส่วน Body ของคำขอใน Apidog คุณสามารถเลือก form-data, x-www-form-urlencoded, JSON, XML, raw หรือ binary ส่วนใหญ่แล้วคุณจะเลือกใช้ JSON แต่การอัปโหลดไฟล์เป็นข้อยกเว้น
ประเภทเนื้อหา form-data แมปกับเฮดเดอร์ Content-Type: multipart/form-data เป็นรูปแบบที่สร้างขึ้นสำหรับการอัปโหลดไฟล์พร้อมกับข้อมูลอื่น ๆ แทนที่จะเป็นข้อมูลก้อนเดียว เนื้อหาจะถูกแบ่งออกเป็นส่วน ๆ แต่ละส่วนมีชื่อและเนื้อหาของตัวเอง ส่วนหนึ่งสามารถเป็นสตริงธรรมดา เช่น คำบรรยาย ส่วนอื่นสามารถเป็นไบต์ดิบของรูปภาพ นั่นคือเหตุผลที่การอัปโหลดรูปภาพและเมทาดาตาของมันสามารถเดินทางได้ในคำขอเดียวกัน
ลูกพี่ลูกน้องที่ใกล้เคียงคือ x-www-form-urlencoded ดูเหมือนกันในตัวแก้ไข โดยเป็นคู่คีย์-ค่าที่ส่งในเนื้อหา แต่มีไว้สำหรับฟอร์มง่ายๆ ที่ไม่มีไฟล์ หากเอนด์พอยต์ของคุณรับไฟล์ form-data คือสิ่งที่คุณต้องการ ใช้ x-www-form-urlencoded เฉพาะเมื่อทุกฟิลด์เป็นสเกลาร์สั้น ๆ และไม่มีไบต์เกี่ยวข้อง
ใน form-data, Apidog แสดงแต่ละพารามิเตอร์เป็นคู่คีย์-ค่า และทุกพารามิเตอร์มีประเภท: string, integer, file และอื่น ๆ ประเภทต่อพารามิเตอร์นี้คือเคล็ดลับทั้งหมด ตั้งค่าฟิลด์เป็น file และ Apidog จะถือว่าค่าของมันเป็นไฟล์ที่จะแนบแทนที่จะเป็นข้อความที่จะส่ง
ส่งไฟล์อัปโหลดเดียวและยืนยันการตอบกลับ
สมมติว่าคุณกำลังทดสอบ POST /avatars ซึ่งรับหนึ่งฟิลด์คือ avatar ที่มีรูปภาพ และคืนค่า JSON พร้อม URL ที่จัดเก็บไว้ นี่คือขั้นตอนการทำงาน
1. เปิดส่วน Body และเลือก form-data. ในเอนด์พอยต์ของคุณหรือคำขอใหม่ ตั้งค่าเมธอดเป็น POST และ URL ไปยังเส้นทาง avatars ของคุณ เปิดแท็บ Body และเลือกประเภท Body แบบ form-data Apidog จะตั้งค่า Content-Type: multipart/form-data ให้คุณ
2. เพิ่มพารามิเตอร์ไฟล์และตั้งค่าประเภทเป็น file. เพิ่มพารามิเตอร์ที่มีคีย์ avatar ถัดจากคีย์ ให้ใช้ตัวเลือกประเภทเพื่อเปลี่ยนประเภทจาก string เป็น file ช่องค่าจะเปลี่ยนเป็นตัวเลือกไฟล์แทนกล่องข้อความ
3. คลิก Upload และเลือกไฟล์ในเครื่อง. คลิก Upload ที่แถว avatar และเลือกรูปภาพจากเครื่องของคุณ เช่น jane-profile.png Apidog จะบันทึกพาธไปยังไฟล์นั้น
4. ส่งคำขอ. กด Send Apidog จะอ่านไฟล์จากพาธในเครื่องที่จัดเก็บไว้ สร้างเนื้อหา multipart และส่งไป สิ่งที่ควรรู้ล่วงหน้า: Apidog ส่งไฟล์ในคำขอ แต่ไม่ได้จัดเก็บไฟล์ไว้ในคลาวด์ จะบันทึกเฉพาะพาธในเครื่องเท่านั้น ไม่ใช่ไบต์ รายละเอียดนั้นสำคัญในภายหลัง ดังนั้นโปรดจำไว้
การเรียกที่สำเร็จจะคืนค่ากลับมาในลักษณะนี้:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. ยืนยันการตอบกลับ. การส่งที่คืนค่า 200 ไม่ได้เป็นการทดสอบที่ผ่านด้วยตัวมันเอง เพิ่มการยืนยันเพื่อให้การตรวจสอบเป็นจริง ใน Apidog คุณเพิ่มสิ่งเหล่านี้เป็นการยืนยันหลังคำขอที่เอนด์พอยต์หรือขั้นตอนสถานการณ์ โดยทั่วไปคุณต้องการยืนยันสถานะและว่าเนื้อหามี URL ที่ใช้งานได้:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
สิ่งเหล่านี้จะแมปโดยตรงกับ UI การยืนยันของ Apidog: หนึ่งการยืนยันเกี่ยวกับรหัสสถานะ, หนึ่งการยืนยันเกี่ยวกับ $.avatarUrl ที่มีอยู่ของ JSONPath, หนึ่งการยืนยันเกี่ยวกับ $.contentType หากคุณยังใหม่กับการยืนยัน คู่มือ การยืนยัน API แสดงชุดโอเปอเรเตอร์ทั้งหมดและวิธีที่ JSONPath กำหนดเป้าหมายฟิลด์
สำหรับการตรวจสอบความเป็นจริงอย่างรวดเร็วนอกเครื่องมือ การอัปโหลดเดียวกันใน curl จะมีลักษณะดังนี้:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
แฟล็ก -F เป็นวิธีของ curl ในการสร้างส่วน multipart และ @ บอกให้มันอ่านเนื้อหาไฟล์ พารามิเตอร์ไฟล์ form-data ของ Apidog ทำสิ่งเดียวกันด้วยตัวเลือกแทนที่จะใช้แฟล็ก
ส่งไฟล์และ JSON พร้อมกัน
เอนด์พอยต์จริงไม่ค่อยรับไฟล์เปล่า POST /documents อาจต้องการไฟล์พร้อมกับเมทาดาตา: ชื่อเรื่อง หมวดหมู่ หรืออาจเป็นอาร์เรย์แท็ก คุณมีสองวิธีที่ชัดเจนในการทำสิ่งนี้ในคำขอ multipart เดียว
กรณีที่ง่ายคือฟิลด์สเกลาร์ เพิ่มพารามิเตอร์ form-data เพิ่มเติมถัดจากฟิลด์ไฟล์ของคุณและปล่อยไว้เป็น string หรือ integer สตริง title สตริง category ไฟล์ file ที่ตั้งค่าประเภทเป็น file ทั้งสามสิ่งนี้จะเดินทางไปในคำขอเดียวกัน
เมื่อเมทาดาตามีโครงสร้าง เช่น ออบเจกต์ซ้อนกันหรืออาร์เรย์ คุณจะส่งมันเป็น JSON ภายในส่วนสตริง เพิ่มพารามิเตอร์ form-data ที่ชื่อ metadata คงประเภทของมันเป็น string และวาง JSON ลงในค่าโดยตรง:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
ดังนั้นคำขอจึงมีสองส่วน: file (ประเภท file) ที่บรรจุ q3-invoice.pdf และ metadata (ประเภท string) ที่บรรจุ JSON นั้น เซิร์ฟเวอร์จะอ่านไฟล์จากส่วนหนึ่งและแยกวิเคราะห์ JSON จากอีกส่วนหนึ่ง API สาธารณะหลายแห่งรับการอัปโหลดด้วยวิธีนี้เช่นกัน; เอกสารการอัปโหลดไฟล์ของ Stripe เป็นตัวอย่างที่ดีของเอนด์พอยต์ multipart จริงที่จับคู่ส่วนไฟล์กับฟิลด์ธรรมดา รูปแบบนี้เป็นที่แพร่หลายมากจนผู้ใช้ Postman ก็พบเช่นกัน; หากคุณกำลังย้ายข้อมูล บทแนะนำเกี่ยวกับ การอัปโหลดไฟล์และข้อมูล JSON ใน Postman จะแมปได้อย่างชัดเจนกับฟิลด์ form-data ของ Apidog
ต้องการแนบไฟล์มากกว่าหนึ่งไฟล์หรือไม่? เพิ่มพารามิเตอร์อื่นที่มีประเภท file คำขอ POST /documents ที่รับไฟล์หลักและภาพย่อจะได้รับสองแถวไฟล์คือ file และ thumbnail แต่ละแถวมีปุ่ม Upload ของตัวเอง ไม่มีโหมดหลายไฟล์พิเศษ; คุณเพียงแค่เพิ่มพารามิเตอร์ประเภทไฟล์จนกว่าคุณจะครอบคลุมทุกส่วนที่เอนด์พอยต์คาดหวัง
เปลี่ยนคำขอให้เป็นสถานการณ์ทดสอบที่ทำซ้ำได้
การส่งครั้งเดียวพิสูจน์ว่าเอนด์พอยต์ทำงานได้หนึ่งครั้ง หากต้องการตรวจจับข้อผิดพลาด คุณต้องการการอัปโหลดภายในสถานการณ์ทดสอบที่บันทึกไว้ซึ่งทำงานตามต้องการหรือตามกำหนดเวลา เชื่อมโยงขั้นตอน: อัปโหลดอวาตาร์, บันทึก id ที่ส่งคืน, จากนั้นเรียก GET /users/{id} และยืนยันว่า URL ของอวาตาร์ยังคงอยู่
สร้างสิ่งนี้ในลักษณะเดียวกับที่คุณสร้างคำขอเดียว จากนั้นบันทึกเป็นขั้นตอนในสถานการณ์ คู่มือ วิธีเขียนสถานการณ์ทดสอบด้วย Apidog ครอบคลุมการเชื่อมโยงขั้นตอนและการส่งค่าระหว่างขั้นตอน เมื่อการอัปโหลดอยู่ในสถานการณ์แล้ว คุณสามารถรันมันกับ staging ในทุกการปรับใช้ เพิ่มสาขาตามเงื่อนไขด้วย ตรรกะตามเงื่อนไขในสถานการณ์ทดสอบ API หรือตั้งเวลาด้วย การทดสอบ API ตามกำหนดเวลา
ทุกสิ่งที่กล่าวมาข้างต้นทำงานได้ดีบนเครื่องของคุณ เพราะเครื่องของคุณมีไฟล์ ข้อสันนิษฐานนั้นคือสิ่งที่พังลงในขั้นตอนต่อไป
กับดัก: การอัปโหลดที่ทำงานในที่อื่น
นี่คือส่วนที่เส้นทางแห่งความสุขซ่อนไว้ Apidog จัดเก็บพาธไฟล์ ไม่ใช่ไฟล์ ในแล็ปท็อปของคุณสิ่งนั้นมองไม่เห็น เพราะพาธจะแก้ไขไปที่ไฟล์จริงทุกครั้ง ทันทีที่ขั้นตอนเดียวกันรันบนเครื่องอื่น พาธนั้นจะชี้ไปที่ไม่มีอะไร
คุณจะพบสิ่งนี้ในสองที่
การทำงานร่วมกันเป็นทีม. เมื่อเพื่อนร่วมทีมเปิดคำขอ POST /avatars ของคุณ พวกเขาจะเห็นพารามิเตอร์ไฟล์และพาธที่คุณเลือก เช่น /Users/jane/pics/jane-profile.png พวกเขาสามารถเห็นคำขอได้ แต่ไม่สามารถส่งได้ เพราะไฟล์นั้นอยู่บนดิสก์ของคุณ ไม่ใช่ของพวกเขา พาธเป็นแบบโลคัลเฉพาะกับเครื่องที่เลือกมัน
การรันด้วย Runner และ CLI. นี่คือสิ่งที่น่าปวดหัวในการทำงานอัตโนมัติ สถานการณ์การอัปโหลดของคุณผ่านการทดสอบในเครื่อง คุณตั้งกำหนดเวลาไว้ใน Runner หรือเรียกใช้จาก CLI แต่ขั้นตอนการอัปโหลดไฟล์กลับล้มเหลว ไม่มีการยืนยันของคุณผิดพลาด ตัวรันไม่สามารถหาไฟล์ที่พาธที่แล็ปท็อปของคุณบันทึกไว้ได้ เพราะพาธนั้นไม่มีอยู่บนโฮสต์ของตัวรัน
การแก้ไขเป็นผลมาจากสาเหตุ ไฟล์ต้องมีอยู่บนเครื่องที่ทำการส่ง และพาธของขั้นตอนต้องชี้ไปที่นั่น
สำหรับ Runner: Runner จะอ่านไฟล์จากไดเรกทอรีโฮสต์ที่ถูกเมาท์เข้าไปในโวลุ่มของมัน คุณตั้งค่าการเมาท์นั้นเมื่อคุณปรับใช้ Runner โดยใช้แฟล็ก -v คัดลอกไฟล์อัปโหลดของคุณลงในไดเรกทอรีโฮสต์ที่เมาท์ไว้ จากนั้นเปิดรายละเอียดขั้นตอนการอัปโหลดไฟล์ในสถานการณ์ คลิกปุ่ม Batch Edit ที่มุมบนขวา และแทนที่ค่าของฟิลด์ไฟล์ด้วยพาธภายในไดเรกทอรีของ Runner เช่น:
/opt/runner/jane-profile.png
สำหรับ CLI: รูปแบบเดียวกัน วางไฟล์บนเครื่อง CLI จากนั้นใช้ Batch Edit บนขั้นตอนเพื่อชี้พาธไปยังตำแหน่งนั้น เช่น:
/opt/apidog/runner/jane-profile.png
สะอาดกว่าการฮาร์ดโค้ด: ใช้ตัวแปร. แทนที่จะระบุพาธที่ชัดเจนในขั้นตอน ให้แทนที่ค่าด้วยตัวแปรและตั้งค่าของตัวแปรเป็นพาธไฟล์จริงสำหรับแต่ละสภาพแวดล้อม จากนั้นสถานการณ์เดียวกันจะทำงานบนแล็ปท็อปของคุณ, Runner และ CI โดยไม่ต้องแก้ไขขั้นตอนทุกครั้ง คุณชี้ตัวแปรไปที่ /Users/jane/pics/jane-profile.png ในเครื่องและ /opt/runner/jane-profile.png บน Runner และขั้นตอนเองก็ไม่เคยเปลี่ยนแปลง
ข้อกำหนดเบื้องต้นหนึ่งที่ควรระบุให้ชัดเจน: Runner เข้าถึงไฟล์โฮสต์ที่อยู่ภายใต้ไดเรกทอรีที่คุณเมาท์ด้วย -v ในเวลาที่ปรับใช้เท่านั้น หากไฟล์ของคุณไม่ได้อยู่ภายใต้การเมาท์นั้น ก็จะไม่มีพาธใดหาเจอ นั่นเป็นรายละเอียดการตั้งค่าการปรับใช้ ไม่ใช่ข้อจำกัดของแผนงาน เอกสาร Apidog เกี่ยวกับคำขออัปโหลดไฟล์ อธิบายขั้นตอนการเมาท์และการแก้ไขเป็นกลุ่ม หากคุณต้องการเวอร์ชันที่เป็นทางการ
ทำงานเวิร์กโฟลว์อัตโนมัติด้วย Apidog CLI
เมื่อสถานการณ์การอัปโหลดของคุณถูกบันทึกแล้ว คุณสามารถรันมันแบบ headless ใน CI ได้ ติดตั้ง CLI และยืนยันตัวตน:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
จากนั้นรันสถานการณ์ที่บันทึกไว้ด้วย id โดยชี้ไปยังสภาพแวดล้อม:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
ที่นี่ -t คือ id ของสถานการณ์ทดสอบ, -e คือ id ของสภาพแวดล้อม, และ -r คือผู้รายงาน (ใช้ cli, html, หรือ junit โดยคั่นด้วยเครื่องหมายจุลภาคสำหรับหลายตัว) CLI จะรันสถานการณ์ที่บันทึกไว้ของคุณจากโปรเจกต์คลาวด์และรายงานผลผ่าน/ล้มเหลวด้วยรหัสทางออก ซึ่งเป็นสิ่งที่ช่วยให้มันควบคุมไปป์ไลน์ได้ รายละเอียดการตั้งค่าอยู่ใน คู่มือการติดตั้ง Apidog CLI
คำเตือนที่ซื่อสัตย์หนึ่งข้อ และเป็นข้อเดียวกันจากส่วนที่แล้ว: สถานการณ์ที่มีขั้นตอนการอัปโหลดไฟล์จำเป็นต้องมีไฟล์อยู่บนเครื่อง CLI และพาธของขั้นตอนต้องชี้ไปที่นั่น วางไฟล์บน Runner จากนั้น Batch Edit พาธ (หรือใช้ตัวแปร) ก่อนการรัน หากข้ามขั้นตอนนี้ ขั้นตอนการอัปโหลดจะล้มเหลวในการหาไฟล์ แม้ว่าส่วนที่เหลือของสถานการณ์จะทำงานได้ดี สำหรับการตั้งค่า CI ที่สมบูรณ์ยิ่งขึ้น รวมถึงการส่งอินพุตต่อแถว โปรดดู การทดสอบที่ขับเคลื่อนด้วยข้อมูลด้วย Apidog CLI
คำถามที่พบบ่อย
เหตุใดเพื่อนร่วมทีมของฉันจึงส่งคำขออัปโหลดไฟล์ของฉันไม่ได้? Apidog จัดเก็บพาธไฟล์ในเครื่อง ไม่ใช่ไฟล์เอง และไม่เคยอัปโหลดไฟล์ไปยังคลาวด์ เพื่อนร่วมทีมของคุณจะเห็นคำขอและพาธที่คุณเลือก แต่พาธนั้นชี้ไปที่ไฟล์บนดิสก์ของคุณ ไม่ใช่ของพวกเขา ให้พวกเขาคัดลอกไฟล์ลงในเครื่องของตนเองและชี้ฟิลด์ไปยังพาธของพวกเขา กลไกเดียวกันนี้อธิบายได้ว่าเหตุใด การทดสอบตามกำหนดเวลา และงานของ Runner จึงต้องมีไฟล์อยู่ในตำแหน่งที่ทำงาน
ฉันจะส่ง JSON พร้อมกับไฟล์ในคำขอเดียวกันได้อย่างไร? คงประเภทเนื้อหาเป็น form-data เพิ่มฟิลด์ไฟล์ของคุณที่มีประเภท file จากนั้นเพิ่มพารามิเตอร์อื่นที่มีประเภท string และวาง JSON ลงในค่าของมัน เซิร์ฟเวอร์จะได้รับทั้งสองส่วนในคำขอ multipart เดียวกัน: ไฟล์ในส่วนหนึ่ง สตริง JSON ในอีกส่วนหนึ่ง นี่คือวิธีมาตรฐานในการแนบเมทาดาตาเข้ากับการอัปโหลด
ฉันควรใช้พาธใดสำหรับไฟล์ใน Runner? ใช้พาธภายในไดเรกทอรีโฮสต์ที่คุณเมาท์เข้าสู่โวลุ่มของ Runner ด้วยแฟล็ก -v ในเวลาที่ปรับใช้ ตัวอย่างเช่น /opt/runner/yourfile.jpg คัดลอกไฟล์เข้าไปในไดเรกทอรีที่เมาท์ไว้ จากนั้นเปิดขั้นตอน คลิก Batch Edit และตั้งค่าฟิลด์เป็นพาธนั้น ค่าเทียบเท่าสำหรับ CLI คือ /opt/apidog/runner/yourfile.jpg
มีขีดจำกัดขนาดไฟล์หรือรายการประเภทไฟล์ที่อนุญาตหรือไม่? พฤติกรรมการอัปโหลดใน Apidog เกี่ยวข้องกับการสร้างคำขอและการอ่านไฟล์จากที่ใด ขีดจำกัดจริงเกี่ยวกับขนาดและประเภทมาจาก API ที่คุณกำลังทดสอบ ดังนั้นควรตรวจสอบกฎการตรวจสอบความถูกต้องของเซิร์ฟเวอร์ของคุณเองและเขียนการยืนยันกับการตอบกลับที่ส่งคืนสำหรับไฟล์ที่มีขนาดใหญ่เกินไปหรือไฟล์ที่ถูกปฏิเสธ
ฉันควรใช้ form-data หรือ x-www-form-urlencoded สำหรับการอัปโหลด? ใช้ form-data มันแมปกับ multipart/form-data และถูกสร้างมาเพื่อส่งไฟล์ x-www-form-urlencoded มีไว้สำหรับฟอร์มง่ายๆ ที่มีฟิลด์สเกลาร์สั้นๆ และไม่มีไฟล์ ดังนั้นจะไม่ส่งรูปภาพหรือ PDF ของคุณไป
สรุป
การทดสอบการอัปโหลดไฟล์มีสองประเด็นหลัก: สร้างคำขอ multipart ให้ถูกต้อง และตรวจสอบให้แน่ใจว่าไฟล์เข้าถึงได้ไม่ว่าจะรันการทดสอบที่ใด ใน Apidog คุณตั้งค่า Body เป็น form-data เปลี่ยนประเภทฟิลด์ของคุณเป็น file คลิก Upload เพิ่ม JSON ใดๆ เป็นส่วนสตริง จากนั้นส่งและยืนยัน เมื่อคุณย้ายสถานการณ์เดียวกันไปยัง Runner หรือ CLI ให้เตรียมไฟล์ไว้บนเครื่องนั้นและเปลี่ยนพาธด้วย Batch Edit หรือตัวแปร และการรันอัตโนมัติจะทำงานเหมือนกับการรันในเครื่องของคุณ
ต้องการลองใช้กับเอนด์พอยต์ของคุณเองหรือไม่? ดาวน์โหลด Apidog ชี้คำขอ form-data ไปยังเส้นทางการอัปโหลดของคุณ และดูการตอบกลับที่กลับมา เริ่มต้นได้ฟรี ไม่ต้องใช้บัตรเครดิต