อัปโหลดสื่อ

ฟีเจอร์การอัปโหลดสื่อช่วยให้ Campaign Manager 360 API จัดเก็บข้อมูลในระบบคลาวด์และทําให้เซิร์ฟเวอร์พร้อมใช้งาน ชนิดของข้อมูลที่สามารถอัปโหลดได้แก่ ภาพถ่าย วิดีโอ ไฟล์ PDF ไฟล์ซิป หรือข้อมูลประเภทอื่นๆ

ตัวอย่างที่ให้ไว้ในเอกสารนี้แสดงการใช้การอัปโหลดสื่อสําหรับ Farm API ที่สมมติขึ้น อย่างไรก็ตาม แนวคิดเดียวกันนี้ก็ใช้กับ Campaign Manager 360 API ได้เช่นกัน

ตัวเลือกในการอัปโหลด

Campaign Manager 360 API ช่วยให้คุณอัปโหลดข้อมูลไบนารีบางประเภทหรือสื่อได้ ลักษณะเฉพาะของข้อมูลที่คุณอัปโหลดสามารถระบุได้ในหน้าอ้างอิงสําหรับวิธีการใดๆ ที่สนับสนุนการอัปโหลดสื่อ:

• ขนาดไฟล์สูงสุดที่อัปโหลดได้: ปริมาณข้อมูลสูงสุดที่เก็บไว้ได้ด้วยวิธีนี้
• ประเภท MIME ของสื่อที่ยอมรับ: ประเภทข้อมูลไบนารีที่จัดเก็บโดยใช้วิธีนี้

คุณสามารถส่งคําขออัปโหลดด้วยวิธีใดวิธีหนึ่งต่อไปนี้ ระบุวิธีการที่คุณใช้กับพารามิเตอร์คําขอ uploadType

• การอัปโหลดอย่างง่าย: uploadType=media หากต้องการโอนไฟล์ขนาดเล็ก เช่น 5 MB หรือน้อยกว่า
• การอัปโหลดหลายส่วน: uploadType=multipart หากต้องการโอนไฟล์และข้อมูลเมตาที่เล็กลงอย่างเร็ว ให้โอนไฟล์ที่มีข้อมูลเมตาซึ่งอธิบายไว้ในคําขอเดียว
• การอัปโหลดที่ดําเนินการต่อได้: uploadType=resumable สําหรับการโอนที่น่าเชื่อถือ โดยเฉพาะไฟล์ขนาดใหญ่ เมื่อใช้วิธีนี้ คุณจะใช้คําขอที่เริ่มโดยเซสชัน ซึ่งจะใส่ข้อมูลเมตาหรือไม่ก็ได้ วิธีนี้เหมาะกับการใช้กับแอปพลิเคชันส่วนใหญ่ เนื่องจากจะใช้ได้กับไฟล์ขนาดเล็กที่คําขอ HTTP เพิ่มเติม 1 รายการต่อการอัปโหลดด้วย

ในการอัปโหลดสื่อ คุณจะใช้ URI พิเศษ ในความเป็นจริง วิธีการที่สนับสนุนการอัปโหลดสื่อมีปลายทาง URI สองแห่ง ดังนี้:

• URI สําหรับ /upload สําหรับสื่อ รูปแบบของปลายทางการอัปโหลดคือ URI ทรัพยากรมาตรฐานที่มีคํานําหน้า "/upload" ใช้ URI นี้เมื่อโอนข้อมูลสื่อ

  เช่น POST /upload/farm/v1/animals

• URI ทรัพยากรมาตรฐานสําหรับข้อมูลเมตา หากทรัพยากรมีช่องข้อมูลใดๆ อยู่ ช่องเหล่านั้นจะใช้เพื่อจัดเก็บข้อมูลเมตาที่อธิบายเกี่ยวกับไฟล์ที่อัปโหลด คุณใช้ URI นี้เมื่อสร้างหรืออัปเดตค่าข้อมูลเมตาได้

  ตัวอย่าง: POST /farm/v1/animals

อัปโหลดได้ง่าย

วิธีการอัปโหลดไฟล์ที่ง่ายที่สุดคือสร้างคําขออัปโหลดที่เรียบง่าย ตัวเลือกนี้เป็นตัวเลือกที่ดีเมื่อ:

• ไฟล์มีขนาดเล็กพอที่จะอัปโหลดใหม่อีกครั้งได้ในกรณีที่การเชื่อมต่อล้มเหลว
• ไม่มีข้อมูลเมตาที่จะส่ง กรณีนี้อาจเป็นจริงหากคุณวางแผนที่จะส่งข้อมูลเมตาสําหรับทรัพยากรนี้ในคําขอแยกต่างหาก หรือหากไม่มีข้อมูลเมตาที่รองรับหรือไม่พร้อมใช้งาน

หากต้องการใช้การอัปโหลดแบบง่าย ให้ส่งคําขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=media เช่น

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

ส่วนหัวของ HTTP ที่จะใช้เมื่อสร้างคําขออัปโหลดอย่างง่ายมีดังนี้

• Content-Type ตั้งค่าเป็นประเภทข้อมูลสื่อการอัปโหลดที่ยอมรับวิธีหนึ่ง ตามที่ระบุไว้ในข้อมูลอ้างอิงของ API
• Content-Length กําหนดเป็นจํานวนไบต์ที่คุณกําลังอัปโหลด ไม่จําเป็นหากคุณใช้การเข้ารหัสการโอนเป็นกลุ่ม

ตัวอย่าง: การอัปโหลดอย่างง่าย

ตัวอย่างต่อไปนี้แสดงคําขออัปโหลดอย่างง่ายสําหรับ Farm API ที่สมมติขึ้น

POST /upload/farm/v1/animals?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

หากคําขอประสบความสําเร็จ เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ HTTP 200 OK พร้อมด้วยข้อมูลเมตา:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

การอัปโหลดหลายส่วน

หากคุณมีข้อมูลเมตาที่ต้องการส่งไปพร้อมกับข้อมูลที่จะอัปโหลด คุณสามารถส่งคําขอ multipart/related รายการเดียวได้ ตัวเลือกนี้เหมาะสําหรับหากข้อมูลที่คุณส่งมีขนาดเล็กพอที่จะอัปโหลดได้อย่างเต็มรูปแบบหากเชื่อมต่อไม่สําเร็จ

หากต้องการใช้การอัปโหลดหลายส่วน ให้ส่งคําขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=multipart เช่น

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

ส่วนหัว HTTP ระดับบนสุดที่จะใช้เมื่อส่งคําขอการอัปโหลดหลายส่วน ได้แก่

• Content-Type กําหนดเป็นแบบหลายส่วน/เกี่ยวข้อง และใส่สตริงของขอบเขตที่ใช้ในการระบุส่วนต่างๆ ของคําขอ
• Content-Length ตั้งค่าเป็นจํานวนรวมของไบต์ในส่วนเนื้อหาของคําขอ ส่วนของสื่อของคําขอต้องน้อยกว่าขนาดไฟล์สูงสุดที่ระบุไว้สําหรับวิธีนี้

เนื้อหาของคําขอมีรูปแบบเป็นเนื้อหาประเภท multipart/related [RFC2387] และมี 2 ส่วน ส่วนที่ระบุด้วยสตริงขอบเขต และสตริงขอบเขตสุดท้ายตามด้วยเครื่องหมายขีดกลาง 2 ขีด

แต่ละส่วนของคําขอที่มีหลายส่วนจําเป็นต้องมีส่วนหัว Content-Type เพิ่มเติม:

1. ส่วนข้อมูลเมตา: ต้องมาก่อน และ Content-Type ต้องตรงกับรูปแบบข้อมูลเมตาที่ยอมรับรูปแบบใดรูปแบบหนึ่ง
2. ส่วนสื่อ: ต้องมาก่อนได้ และ Content-Type ต้องตรงกับประเภท MIME ของสื่อที่ยอมรับ 1 ประเภท

ดูข้อมูลอ้างอิงของ API สําหรับรายการประเภท MIME ของสื่อที่ยอมรับและขีดจํากัดขนาดสําหรับไฟล์ที่อัปโหลดแต่ละรายการ

หมายเหตุ: หากต้องการสร้างหรืออัปเดตส่วนข้อมูลเมตาเท่านั้น โดยไม่ต้องอัปโหลดข้อมูลที่เกี่ยวข้อง ให้ส่งคําขอ POST หรือ PUT ไปยังปลายทางของทรัพยากรมาตรฐาน โดยทําดังนี้ https://www.googleapis.com/farm/v1/animals

ตัวอย่าง: การอัปโหลดหลายส่วน

ตัวอย่างด้านล่างแสดงคําขออัปโหลดหลายส่วนสําหรับ Farm API ที่สมมติขึ้น

POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

หากคําขอประสบความสําเร็จ เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ HTTP 200 OK พร้อมกับข้อมูลเมตาทั้งหมด:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

การอัปโหลดที่ดําเนินการต่อได้

หากต้องการอัปโหลดไฟล์ข้อมูลให้มีความน่าเชื่อถือมากขึ้น คุณสามารถใช้โปรโตคอลการอัปโหลดที่ดําเนินการต่อได้ โปรโตคอลนี้ช่วยให้คุณดําเนินการอัปโหลดต่อได้หลังจากการสื่อสารล้มเหลวซึ่งขัดจังหวะการรับส่งข้อมูล ซึ่งมีประโยชน์อย่างยิ่งหากคุณโอนไฟล์ขนาดใหญ่ และมีโอกาสที่จะหยุดชะงักของเครือข่ายหรือการส่งข้อมูลอื่นๆ ที่มีปริมาณสูง เช่น เมื่ออัปโหลดจากแอปไคลเอ็นต์บนอุปกรณ์เคลื่อนที่ นอกจากนี้ยังช่วยลดการใช้แบนด์วิดท์ในกรณีที่เครือข่ายทํางานล้มเหลว เนื่องจากคุณไม่ต้องรีสตาร์ทไฟล์ขนาดใหญ่ตั้งแต่ต้น

ขั้นตอนในการใช้การอัปโหลดที่ดําเนินการต่อได้มีดังนี้

1. เริ่มเซสชันที่ดําเนินการต่อได้ ส่งคําขอเริ่มต้นไปยัง URI การอัปโหลดที่มีข้อมูลเมตา หากมี
2. บันทึก URI ของเซสชันที่กลับมาทํางานต่อ บันทึก URI เซสชันที่แสดงผลเมื่อตอบกลับคําขอเริ่มต้น คุณจะใช้ URI นี้สําหรับคําขอที่เหลือในเซสชันนี้
3. อัปโหลดไฟล์ ส่งไฟล์สื่อไปยัง URI ของเซสชันที่กลับมาทํางานอีกครั้ง

นอกจากนี้ แอปที่ใช้การอัปโหลดที่ดําเนินการต่อได้ต้องมีโค้ดเพื่ออัปโหลดต่อที่หยุดชะงัก หากการอัปโหลดหยุดชะงัก ให้ดูปริมาณข้อมูลที่ได้รับ แล้วอัปโหลดต่อจากจุดนั้น

หมายเหตุ: URI การอัปโหลดจะหมดอายุหลังจากผ่านไป 1 สัปดาห์

ขั้นตอนที่ 1: เริ่มเซสชันกลับมาทํางานอีกครั้ง

หากต้องการเริ่มการอัปโหลดที่ดําเนินการต่อได้ ให้ส่งคําขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=resumable เช่น

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

สําหรับคําขอที่เริ่มต้นนี้ เนื้อหาจะว่างเปล่าหรือมีเพียงข้อมูลเมตาเท่านั้น คุณจะโอนเนื้อหาจริงของไฟล์ที่ต้องการอัปโหลดในคําขอที่ตามมา

ใช้ส่วนหัว HTTP ต่อไปนี้กับคําขอเริ่มต้น

• X-Upload-Content-Type ตั้งค่าเป็นประเภท MIME ของสื่อของข้อมูลที่อัปโหลดที่จะโอนในคําขอที่ตามมา
• X-Upload-Content-Length กําหนดจํานวนไบต์ของข้อมูลการอัปโหลดที่จะโอนในคําขอที่ตามมา หากไม่ทราบความยาวขณะที่ส่งคําขอ คุณละเว้นส่วนหัวนี้ได้
• หากระบุข้อมูลเมตา: Content-Type ตั้งค่าตามประเภทข้อมูลของข้อมูลเมตา
• Content-Length กําหนดเป็นจํานวนไบต์ที่ระบุในเนื้อหาของคําขอเริ่มต้นนี้ ไม่จําเป็นหากคุณใช้การเข้ารหัสการโอนเป็นกลุ่ม

ดูข้อมูลอ้างอิงของ API สําหรับรายการประเภท MIME ของสื่อที่ยอมรับและขีดจํากัดขนาดสําหรับไฟล์ที่อัปโหลดแต่ละรายการ

ตัวอย่าง: คําขอเริ่มเซสชันที่สามารถดําเนินการต่อได้

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มเซสชันที่กลับมาทํางานอีกครั้งสําหรับ Farm API ที่สมมติขึ้น

POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "Llama"
}

หมายเหตุ: สําหรับคําขออัปเดตที่ดําเนินการต่อได้เริ่มต้นโดยไม่มีข้อมูลเมตา ให้ปล่อยเนื้อหาของคําขอว่างไว้และตั้งค่าส่วนหัว Content-Length เป็น 0

ส่วนถัดไปจะอธิบายถึงวิธีจัดการการตอบกลับ

ขั้นตอนที่ 2: บันทึก URI ของเซสชันที่ดําเนินการต่อได้

หากคําขอเริ่มต้นเซสชันสําเร็จ เซิร์ฟเวอร์ API จะตอบสนองด้วยรหัสสถานะ HTTP 200 OK นอกจากนี้ ระบบยังมีส่วนหัว Location ที่ระบุ URI ของเซสชันที่กลับมาทํางานอีกครั้ง ส่วนหัว Location ดังที่แสดงในตัวอย่างด้านล่างมีส่วนที่เป็นพารามิเตอร์การค้นหา upload_id ซึ่งระบุรหัสการอัปโหลดที่ไม่ซ้ํากันเพื่อใช้สําหรับเซสชันนี้

ตัวอย่าง: การเริ่มเซสชันต่อที่ดําเนินการต่อได้

นี่คือคําตอบสําหรับคําขอในขั้นตอนที่ 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

ค่าของส่วนหัว Location ดังที่แสดงในการตอบสนองตัวอย่างด้านบนคือ URI เซสชันที่คุณจะใช้เป็นปลายทาง HTTP สําหรับการอัปโหลดไฟล์จริงหรือค้นหาสถานะการอัปโหลด

คัดลอกและบันทึก URI ของเซสชันเพื่อให้ใช้สําหรับคําขอที่ตามมาได้

ขั้นตอนที่ 3: อัปโหลด

หากต้องการอัปโหลดไฟล์ ให้ส่งคําขอ PUT ไปยัง URI การอัปโหลดที่คุณได้รับในขั้นตอนก่อนหน้า รูปแบบของคําขออัปโหลดคือ:

PUT session_uri

ส่วนหัว HTTP ที่จะใช้เมื่อส่งคําขอการอัปโหลดไฟล์ที่ทํางานต่อได้รวมถึง Content-Length ตั้งค่าจํานวนไบต์เป็นไบต์ที่คุณกําลังอัปโหลดในคําขอนี้ ซึ่งโดยทั่วไปจะเป็นขนาดไฟล์อัปโหลด

ตัวอย่าง: คําขออัปโหลดไฟล์ที่ดําเนินการต่อได้

ต่อไปนี้เป็นคําขอที่สามารถดําเนินการต่อได้เพื่ออัปโหลดไฟล์ JPEG 2,000,000 ไบต์สําหรับตัวอย่างปัจจุบัน

PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

bytes 0-1999999

หากคําขอประสบความสําเร็จ เซิร์ฟเวอร์จะตอบกลับด้วย HTTP 201 Created รวมถึงข้อมูลเมตาที่เชื่อมโยงกับทรัพยากรนี้ หากคําขอแรกของเซสชันที่ดําเนินการต่อได้เดิมคือ PUT และต้องอัปเดตทรัพยากรที่มีอยู่ การตอบกลับทรัพยากรจะเป็น 200 OK รวมถึงข้อมูลเมตาที่เชื่อมโยงกับทรัพยากรนี้

หากคําขออัปโหลดถูกขัดจังหวะหรือได้รับการตอบกลับด้วย HTTP 503 Service Unavailable หรือ 5xx จากเซิร์ฟเวอร์ ให้ทําตามขั้นตอนที่ระบุไว้ในส่วนทําให้การอัปโหลดที่ดําเนินการต่อกลับมาทํางานอีกครั้ง  

---

การอัปโหลดไฟล์เป็นกลุ่ม

เมื่อใช้การอัปโหลดที่ดําเนินการต่อได้ คุณจะสามารถแบ่งไฟล์ออกเป็นกลุ่มๆ และส่งคําขอเป็นชุดเพื่ออัปโหลดแต่ละส่วนตามลําดับ นี่ไม่ใช่วิธีการที่แนะนํา เนื่องจากมีค่าใช้จ่ายที่เกี่ยวข้องกับคําขอเพิ่มเติมและโดยทั่วไปไม่จําเป็นต้องใช้ อย่างไรก็ตาม คุณอาจต้องใช้การแบ่งช่องเพื่อลดปริมาณข้อมูลที่โอนในคําขอเดียว ซึ่งจะเป็นประโยชน์เมื่อมีการจํากัดเวลาที่แน่นอนสําหรับแต่ละคําขอ เช่นเดียวกับบางคลาสของคําขอ Google App Engine นอกจากนี้ เครื่องมือยังช่วยให้คุณทําสิ่งต่างๆ เช่น ระบุความคืบหน้าในการอัปโหลดของเบราว์เซอร์เดิมที่ไม่มีการสนับสนุนความคืบหน้าการอัปโหลดโดยค่าเริ่มต้น

ขยายเพื่อดูข้อมูลเพิ่มเติม

หากอัปโหลดข้อมูลเป็นส่วนๆ คุณจําเป็นต้องใช้ส่วนหัว Content-Range ควบคู่กับส่วนหัว Content-Length ที่จําเป็นในการอัปโหลดไฟล์แบบเต็ม ดังนี้

• Content-Length ตั้งค่าเป็นขนาดกลุ่มหรืออาจน้อยกว่านี้ ดังเช่นในกรณีของคําขอล่าสุด
• Content-Range: ตั้งค่าเพื่อแสดงให้เห็นว่าไบต์ใดในไฟล์ที่คุณกําลังอัปโหลด ตัวอย่างเช่น Content-Range: bytes 0-524287/2000000 แสดงให้เห็นว่าคุณกําลังให้พื้นที่ 524,288 ไบต์แรก (256 x 1024 x 2) ในไฟล์ 2,000,000 ไบต์

การจํากัดขนาดไฟล์รูป: ไฟล์แต่ละไฟล์ต้องมีขนาด 256 KB (256 x 1024 ไบต์) มากกว่า ยกเว้นส่วนของไฟล์ที่การอัปโหลดสมบูรณ์ หากคุณใช้การแบ่งส่วนไฟล์ คุณควรลดขนาดไฟล์ให้ใหญ่ที่สุดเท่าที่จะทําได้เพื่อให้การอัปโหลดมีประสิทธิภาพ

ตัวอย่าง: คําขออัปโหลดไฟล์แบบต่อเรียงต่อกัน

คําขอที่ส่ง 524,288 ไบต์แรกอาจมีลักษณะเช่นนี้

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

หากคําขอประสบความสําเร็จ เซิร์ฟเวอร์จะตอบสนองด้วย 308 Resume Incomplete พร้อมกับส่วนหัวของ Range ที่ระบุจํานวนไบต์ทั้งหมดที่เก็บไว้แล้ว ดังนี้

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

ใช้ค่าด้านบนที่ส่งคืนในส่วนหัว Range เพื่อกําหนดจุดเริ่มต้นของกลุ่ม ดําเนินการต่อทีละ PUT ไฟล์จนกว่าจะอัปโหลดครบทั้งไฟล์

หากคําขอ PUT ของกลุ่มถูกขัดจังหวะ หรือได้รับการตอบสนองของ HTTP 503 Service Unavailable หรือ 5xx อื่นจากเซิร์ฟเวอร์ ให้ทําตามขั้นตอนที่ระบุไว้ในส่วนดําเนินการอัปโหลดที่หยุดชะงัก แต่แทนที่จะอัปโหลดไฟล์ที่เหลือ เพียงอัปโหลดกลุ่มต่อไปจากจุดนั้น

หมายเหตุสําคัญ:

• อย่าลืมใช้ส่วนหัว Range ในการตอบกลับเพื่อกําหนดตําแหน่งที่จะเริ่มต้นส่วนต่อไป โปรดอย่าทึกทักเอาว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมดที่ส่งในคําขอก่อนหน้า
• URI การอัปโหลดแต่ละรายการมีอายุการใช้งานที่แน่นอนและหมดอายุในที่สุด (ภายใน 1 วันโดยประมาณ หากไม่มีการใช้งาน) ด้วยเหตุนี้ จะเป็นการดีที่สุดที่จะเริ่มต้นการอัปโหลดที่กลับมาทํางานต่อได้ทันทีที่คุณได้รับ URI ของการอัปโหลด และเพื่อให้การอัปโหลดที่กลับมาทํางานอีกครั้งทันทีหลังจากเกิดการขัดข้อง
• หากคุณส่งคําขอที่มีรหัสเซสชันการอัปโหลดที่หมดอายุแล้ว เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ 404 Not Found เมื่อเกิดข้อผิดพลาดที่ไม่สามารถกู้คืนได้ในเซสชันการอัปโหลด เซิร์ฟเวอร์จะส่งคืนรหัสสถานะ 410 Gone ในกรณีเหล่านี้ คุณต้องเริ่มการอัปโหลดที่กลับมาทํางานใหม่ได้ รับ URI การอัปโหลดใหม่ และเริ่มการอัปโหลดตั้งแต่ต้นโดยใช้ปลายทางใหม่

เมื่ออัปโหลดไฟล์ทั้งหมดเรียบร้อยแล้ว เซิร์ฟเวอร์จะตอบสนองด้วย HTTP 201 Created พร้อมกับข้อมูลเมตาที่เชื่อมโยงกับทรัพยากรนี้ หากคําขอนี้อัปเดตเอนทิตีที่มีอยู่แทนที่จะสร้างเอนทิตีใหม่ โค้ดตอบกลับ HTTP สําหรับการอัปโหลดที่เสร็จสมบูรณ์จะเป็น 200 OK

---

ดําเนินการอัปโหลดที่หยุดชะงักต่อ

หากคําขออัปโหลดถูกยกเลิกก่อนที่จะได้รับการตอบกลับหรือหากคุณได้รับการตอบกลับ HTTP 503 Service Unavailable จากเซิร์ฟเวอร์ คุณจะต้องกลับมาอัปโหลดต่อ โดยทำดังนี้

1. สถานะคําขอ ค้นหาสถานะปัจจุบันของการอัปโหลดโดยส่งคําขอ PUT ที่ว่างเปล่าไปยัง URI การอัปโหลด สําหรับคําขอนี้ ส่วนหัว HTTP ควรมีส่วนหัว Content-Range ที่ระบุว่าไม่ทราบไฟล์ปัจจุบันในไฟล์ เช่น ตั้งค่า Content-Range เป็น */2000000 หากความยาวไฟล์รวมของคุณคือ 2,000,000 หากไม่ทราบขนาดเต็มของไฟล์ ให้ตั้งค่า Content-Range เป็น */*

   หมายเหตุ: คุณขอสถานะระหว่างไฟล์กลุ่มได้ ไม่ใช่แค่ในกรณีที่การอัปโหลดขัดข้อง ซึ่งจะเป็นประโยชน์ เช่น ในกรณีที่คุณต้องการแสดงตัวบ่งชี้ความคืบหน้าในการอัปโหลดของเบราว์เซอร์เดิม

2. รับจํานวนไบต์ที่อัปโหลด ประมวลผลการตอบสนองจากคําค้นหาสถานะ เซิร์ฟเวอร์จะใช้ส่วนหัว Range ในการตอบกลับเพื่อระบุไบต์ที่ได้รับจนถึงปัจจุบัน ตัวอย่างเช่น ส่วนหัว Range ของ 0-299999 แสดงว่าได้รับ 300,000 ไบต์แรกของไฟล์แล้ว
3. อัปโหลดข้อมูลที่เหลือ สุดท้ายนี้ เมื่อคุณทราบแล้วว่าจะดําเนินการต่อที่ใด ให้ส่งข้อมูลที่เหลือหรือกลุ่มปัจจุบัน โปรดทราบว่าคุณต้องจัดการกับข้อมูลที่เหลือเป็นส่วนๆ แยกกัน ไม่ว่าจะกรณีใด คุณจึงต้องส่งส่วนหัว Content-Range เมื่อทําการอัปโหลดต่อ

ตัวอย่าง: การอัปโหลดที่อัปโหลดต่อ

1) ขอสถานะการอัปโหลด

คําขอต่อไปนี้ใช้ส่วนหัว Content-Range เพื่อระบุว่าระบบไม่รู้จักตําแหน่งปัจจุบันในไฟล์ 2,000,000 ไบต์

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) แยกจํานวนไบต์ที่อัปโหลดนับตั้งแต่คําตอบ

การตอบสนองของเซิร์ฟเวอร์ใช้ส่วนหัว Range เพื่อระบุว่าได้รับ 43 ไบต์แรกของไฟล์จนถึงตอนนี้ ใช้ค่าด้านบนของส่วนหัว Range เพื่อเริ่มตําแหน่งที่จะอัปโหลดต่อ

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

หมายเหตุ: อาจเป็นไปได้ว่าการตอบกลับสถานะอาจเป็น 201 Created หรือ 200 OK หากการอัปโหลดเสร็จสมบูรณ์ กรณีนี้อาจเกิดขึ้นถ้าการเชื่อมต่อเสียหายหลังจากอัปโหลดไบต์ทั้งหมด แต่ก่อนที่ไคลเอ็นต์ได้รับการตอบกลับจากเซิร์ฟเวอร์

3) อัปโหลดต่อจากจุดที่ทําค้างไว้

คําขอต่อไปนี้จะดําเนินการอัปโหลดต่อโดยส่งไบต์ที่เหลือของไฟล์โดยเริ่มที่ไบต์ 43

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

แนวทางปฏิบัติแนะนำ

ขณะที่อัปโหลดสื่อ คุณควรคํานึงถึงแนวทางปฏิบัติที่ดีที่สุดบางประการที่เกี่ยวข้องกับการจัดการข้อผิดพลาด

• อัปโหลดต่อหรือลองการอัปโหลดที่ล้มเหลวอีกครั้งเนื่องจากการเชื่อมต่อหยุดชะงักหรือมีข้อผิดพลาดใดๆ เกี่ยวกับ 5xx รวมถึง
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• ใช้กลยุทธ์ Exponential Backoff หากเซิร์ฟเวอร์แสดงข้อผิดพลาด 5xx เมื่อกลับมาดําเนินการต่อหรือลองส่งคําขออัปโหลดอีกครั้ง ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นได้หากเซิร์ฟเวอร์ทํางานหนักเกินไป Exponential Backoff สามารถช่วยหลีกเลี่ยงปัญหาเหล่านี้ได้ในช่วงที่มีการขอเข้ามามากหรือมีการเข้าชมเครือข่ายสูง
• คําขอประเภทอื่นๆ ไม่ควรได้รับการจัดการโดย Exponential Backoff แต่คุณยังลองใหม่ได้จํานวนหนึ่ง ให้ลองซ้ําจํานวนครั้งที่คําขอเหล่านี้ลองอีกครั้ง ตัวอย่างเช่น รหัสอาจจํากัดให้ไม่เกิน 10 ครั้งก่อนที่จะรายงานข้อผิดพลาด
• แก้ไขข้อผิดพลาด 404 Not Found และ 410 Gone เมื่อทําการอัปโหลดที่ดําเนินการต่อได้โดยการเริ่มการอัปโหลดตั้งแต่ต้นตั้งแต่ต้น

Exponential Backoff

Exponential Backoff เป็นกลยุทธ์การจัดการข้อผิดพลาดมาตรฐานสําหรับแอปพลิเคชันเครือข่ายที่ไคลเอ็นต์จะลองดําเนินการตามคําขอที่ล้มเหลวเป็นระยะๆ เป็นเวลานาน หากคําขอมีปริมาณมากหรือการจราจรของข้อมูลในเครือข่ายจํานวนมากทําให้เซิร์ฟเวอร์แสดงผลข้อผิดพลาด การย้อนกลับแบบทวีคูณอาจเป็นกลยุทธ์ที่ดีในการจัดการข้อผิดพลาดเหล่านั้น ในทางกลับกัน วิธีนี้ไม่ใช่กลยุทธ์ที่เกี่ยวข้องกับการจัดการกับข้อผิดพลาดที่ไม่เกี่ยวข้องกับปริมาณเครือข่ายหรือเวลาในการตอบสนอง เช่น ข้อมูลรับรองการให้สิทธิ์ที่ไม่ถูกต้อง หรือข้อผิดพลาดไม่พบไฟล์

การใช้ Exponential Backoff อย่างเหมาะสมจะช่วยเพิ่มประสิทธิภาพของการใช้แบนด์วิดท์ ลดจํานวนคําขอที่ต้องใช้เพื่อให้ได้รับการตอบกลับที่สําเร็จ และเพิ่มอัตราการส่งข้อมูลของคําขอในสภาพแวดล้อมแบบพร้อมกัน

ขั้นตอนสําหรับการนํา Exponential Backoff แบบง่ายมีดังนี้

1. ส่งคําขอไปยัง API
2. ได้รับการตอบกลับ HTTP 503 ซึ่งระบุว่าคุณต้องการลองส่งคําขออีกครั้ง
3. รอ 1 วินาที +andom_number_milliseconds แล้วลองอีกครั้ง
4. ได้รับการตอบกลับ HTTP 503 ซึ่งระบุว่าคุณต้องการลองส่งคําขออีกครั้ง
5. รอ 2 วินาที +andom_number_milliseconds แล้วลองอีกครั้ง
6. ได้รับการตอบกลับ HTTP 503 ซึ่งระบุว่าคุณต้องการลองส่งคําขออีกครั้ง
7. รอ 4 วินาที +andom_number_milliseconds แล้วลองอีกครั้ง
8. ได้รับการตอบกลับ HTTP 503 ซึ่งระบุว่าคุณต้องการลองส่งคําขออีกครั้ง
9. รอ 8 วินาที +andom_number_milliseconds แล้วลองอีกครั้ง
10. ได้รับการตอบกลับ HTTP 503 ซึ่งระบุว่าคุณต้องการลองส่งคําขออีกครั้ง
11. รอ 16 วินาที +andom_number_milliseconds แล้วลองอีกครั้ง
12. หยุด รายงานหรือบันทึกข้อผิดพลาด

ในขั้นตอนด้านบนแบบสุ่ม_number_millisecondsเป็นจํานวนแบบสุ่มของมิลลิวินาทีที่น้อยกว่าหรือเท่ากับ 1000 ซึ่งเป็นสิ่งจําเป็น เนื่องจากการดีเลย์แบบสุ่มเล็กๆ น้อยๆ จะช่วยกระจายภาระงานได้สม่ําเสมอมากขึ้นและหลีกเลี่ยงการประทับตราเซิร์ฟเวอร์ ต้องกําหนดค่าของandom_number_milliseconds เมื่อมีการรอแต่ละครั้ง

หมายเหตุ: การรอจะเท่ากับ (2 ^ n) +andom_number_milliseconds โดย n คือจํานวนเต็มที่เพิ่มขึ้นในทางเดียวกันซึ่งกําหนดเป็น 0 ในตอนแรก จํานวนเต็ม n จะเพิ่มขึ้น 1 สําหรับแต่ละการทําซ้ํา (แต่ละคําขอ)

อัลกอริทึมจะมีการตั้งค่าให้สิ้นสุดเมื่อ n คือ 5 เพดานนี้จะป้องกันไม่ให้ลูกค้าลองซ้ําไปเรื่อยๆ และทําให้เกิดความล่าช้าทั้งหมดประมาณ 32 วินาทีก่อนที่คําขอจะถูกพิจารณาว่าเป็น "ข้อผิดพลาดที่ไม่สามารถกู้คืนได้" การดําเนินการซ้ําในจํานวนที่มากขึ้นเป็นสิ่งที่ยอมรับได้ โดยเฉพาะอย่างยิ่งหากกําลังดําเนินการอัปโหลดเป็นเวลานาน แต่อย่าลืมจํากัดความล่าช้าในการดําเนินการอีกครั้งตามความเหมาะสม เช่น น้อยกว่า 1 นาที

คําแนะนําไลบรารีของไคลเอ็นต์ API

• .NET
• Java
• PHP
• Python
• Ruby