อัปโหลดสื่อ

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

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

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

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

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

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

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

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

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

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

• URL ทรัพยากรมาตรฐานสำหรับข้อมูลเมตา หากทรัพยากรมี ช่องข้อมูลเหล่านี้จะใช้ในการจัดเก็บข้อมูลเมตาที่อธิบายถึงการอัปโหลด คุณสามารถใช้ 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. ส่วนสื่อ: ต้องมาเป็นอันดับ 2 และ Content-Type ต้องตรงกับประเภท MIME ของสื่อที่ยอมรับวิธีหนึ่ง

โปรดดูข้อมูลอ้างอิง 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 ของเซสชันที่ส่งคืนในการตอบกลับคำขอเริ่มต้น เพราะคุณจะใช้สำหรับคำขอที่เหลือในเซสชันนี้
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. อัปโหลดข้อมูลที่เหลือ สุดท้าย เมื่อคุณทราบตําแหน่งที่จะส่งคําขอต่อแล้ว ให้ส่งข้อมูลที่เหลือหรือข้อมูลส่วนที่เป็นปัจจุบัน โปรดทราบว่าคุณต้องจัดการข้อมูลที่เหลือแยกเป็นส่วนๆ ในทั้ง 2 กรณี คุณจึงต้องส่งส่วนหัว 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 ที่ใช้อย่างเหมาะสมจะเพิ่มประสิทธิภาพการใช้แบนด์วิดท์ ลดจำนวนคำขอที่จําเป็นต่อการตอบกลับที่ประสบความสําเร็จ และเพิ่มปริมาณงานของคําขอในสภาพแวดล้อมแบบพร้อมกันให้สูงสุด

ขั้นตอนในการใช้ Exponential Backoff แบบง่ายมีดังนี้

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

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

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

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

คู่มือไลบรารีของไคลเอ็นต์ API

• .NET
• Java
• PHP
• Python
• Ruby