หน้านี้ได้รับการแปลโดย Cloud Translation API

อัปโหลดรูปภาพด้วย API การเผยแพร่บริการเกมของ Play

Publishing API สำหรับบริการเกมของ Play ช่วยให้คุณอัปโหลดรูปภาพสำหรับทรัพยากรเกมได้

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

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

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

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

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

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

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

ตัวอย่าง: POST /upload/games/v1configuration/images/resourceId/imageType/imageType
URI ของทรัพยากรมาตรฐานสำหรับข้อมูลเมตา หากทรัพยากรมีฟิลด์ข้อมูล ระบบจะใช้ฟิลด์เหล่านั้นเพื่อจัดเก็บข้อมูลเมตาที่อธิบายไฟล์ที่อัปโหลด คุณใช้ URI นี้ได้เมื่อสร้างหรืออัปเดตค่าข้อมูลเมตา

ตัวอย่าง: POST /games/v1configuration/images/resourceId/imageType/imageType

อัปโหลดง่ายๆ

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

ไฟล์มีขนาดเล็กพอที่จะอัปโหลดอีกครั้งได้ทั้งไฟล์หากการเชื่อมต่อล้มเหลว
ไม่มีข้อมูลเมตาที่จะส่ง ซึ่งอาจเป็นจริงหากคุณวางแผนที่จะส่งข้อมูลเมตา สำหรับทรัพยากรนี้ในคำขอแยกต่างหาก หรือหากไม่รองรับหรือไม่มีข้อมูลเมตา หากต้องการใช้การอัปโหลดแบบง่าย ให้ส่งคำขอ POST หรือ PUT ไปยัง URI /upload ของเมธอด แล้วเพิ่มพารามิเตอร์การค้นหา uploadType=media เช่น

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

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

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

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

ตัวอย่างต่อไปนี้แสดงการใช้คำขออัปโหลดอย่างง่ายสำหรับ Play Games Services Publishing API

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

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

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

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

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

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

-Content-Type ตั้งค่าเป็น multipart/related และรวมสตริงขอบเขตที่คุณใช้เพื่อระบุส่วนต่างๆ ของคำขอ

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

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

คำขอที่มีข้อมูลหลายส่วนแต่ละส่วนต้องมีส่วนหัว Content-Type เพิ่มเติม ดังนี้

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

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

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

ตัวอย่างด้านล่างแสดงคำขออัปโหลดแบบหลายส่วนสำหรับ Publishing API ของบริการเกมของ Play

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

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

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

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

เริ่มเซสชันที่สามารถกลับมาดำเนินการต่อได้

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

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงวิธีเริ่มต้นเซสชันที่สามารถกลับมาทำงานต่อได้สำหรับ Publishing API ของบริการเกมของ Play

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?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/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

บันทึก URI ของเซสชันที่สามารถกลับมาทำงานต่อได้

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

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

คำตอบสำหรับคำขอในขั้นตอนที่ 1 มีดังนี้

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

อัปโหลดไฟล์

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

PUT session_uri

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

ตัวอย่าง: คำขออัปโหลดไฟล์ต่อได้

ต่อไปนี้คือคำขอที่สามารถอัปโหลดไฟล์ PNG ขนาด 2,000,000 ไบต์ทั้งหมดสำหรับตัวอย่างปัจจุบันได้

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

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 ไบต์

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

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

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

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

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

คำขอที่ส่งไบต์แรก 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 จากเซิร์ฟเวอร์ คุณจะต้องอัปโหลดต่อจากที่หยุดชะงัก หากต้องการอัปโหลดต่อจากที่หยุดไว้ ให้ทำดังนี้

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

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

ตัวอย่าง: อัปโหลดต่อหลังจากหยุดชะงัก

ขอสถานะการอัปโหลด คำขอต่อไปนี้ใช้ส่วนหัว Content-Range เพื่อระบุว่าตำแหน่งปัจจุบันในไฟล์ขนาด 2,000,000 ไบต์ ไม่ทราบ
```
PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000
```
แยกจำนวนไบต์ที่อัปโหลดไปแล้วออกจากคำตอบ การตอบกลับของเซิร์ฟเวอร์ ใช้ส่วนหัว Range เพื่อระบุว่าได้รับไบต์แรก ของไฟล์แล้ว 43 ไบต์ ใช้ค่าบนของส่วนหัว Range เพื่อ กำหนดจุดเริ่มต้นของการอัปโหลดต่อ
```
HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42
```
หมายเหตุ: การตอบกลับสถานะอาจเป็น201สร้างแล้วหรือ 200 OKหากอัปโหลดเสร็จสมบูรณ์ ซึ่งอาจเกิดขึ้นได้หากการเชื่อมต่อขาดหายไป หลังจากอัปโหลดไบต์ทั้งหมดแล้ว แต่ก่อนที่ไคลเอ็นต์จะได้รับการตอบกลับจาก เซิร์ฟเวอร์
อัปโหลดต่อจากจุดที่หยุดไว้ คำขอต่อไปนี้ จะอัปโหลดต่อโดยส่งไบต์ที่เหลือของไฟล์ เริ่มต้นที่ ไบต์ 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 แบบง่ายมีดังนี้

ส่งคำขอไปยัง API
ได้รับHTTP 503การตอบกลับ ซึ่งบ่งบอกว่าคุณควรลองส่งคำขออีกครั้ง
รอ 1 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
ได้รับHTTP 503การตอบกลับ ซึ่งบ่งบอกว่าคุณควรลองส่งคำขออีกครั้ง
รอ 2 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
ได้รับHTTP 503การตอบกลับ ซึ่งบ่งบอกว่าคุณควรลองส่งคำขออีกครั้ง
รอ 4 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับ HTTP 503 response ซึ่งบ่งบอกว่าคุณควรลองส่งคำขออีกครั้ง
รอ 8 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
รับ HTTP 503 response ซึ่งบ่งบอกว่าคุณควรลองส่งคำขออีกครั้ง
รอ 16 วินาที + random_number_milliseconds แล้วลองส่งคำขออีกครั้ง
หยุด รายงานหรือบันทึกข้อผิดพลาด

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

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