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

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

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

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

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

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

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

• การอัปโหลดอย่างง่าย: uploadType=media สำหรับการโอนอย่างรวดเร็ว ไฟล์ขนาดเล็กกว่า เช่น ไม่เกิน 5 MB

• การอัปโหลดหลายส่วน: uploadType=multipart สำหรับความรวดเร็ว โอนไฟล์ขนาดเล็กและข้อมูลเมตา จะโอนไฟล์พร้อมกับข้อมูลเมตา ที่อธิบายทุกอย่างได้ ในคำขอเดียว

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

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

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

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

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

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

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

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

• ไฟล์มีขนาดเล็กพอที่จะอัปโหลดอีกครั้งได้ หากการเชื่อมต่อ ล้มเหลว

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงการใช้คำขออัปโหลดอย่างง่ายสำหรับ Play 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ไปยังเมธอด /upload URI และเพิ่มพารามิเตอร์การค้นหา uploadType=multipart เช่น

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

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

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

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

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

แต่ละส่วนของคำขอที่มีหลายส่วนต้องมีส่วนหัวประเภทเนื้อหาเพิ่มเติมดังนี้

• ส่วนข้อมูลเมตา: ต้องมาก่อนและประเภทเนื้อหาต้องตรงกับรูปแบบข้อมูลเมตาที่ยอมรับรูปแบบใดรูปแบบหนึ่ง

• ส่วนสื่อ: ต้องมาเป็นอันดับ 2 และประเภทเนื้อหาต้องตรงกับประเภท MIME ของสื่อที่ยอมรับวิธีหนึ่ง

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

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

ตัวอย่างด้านล่างแสดงคำขออัปโหลดหลายส่วนของ 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
}

อัปโหลดต่อได้

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

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

1. เริ่มเซสชันที่กลับมาทำงานต่อได้ ส่งคำขอเริ่มต้นไปยัง URI การอัปโหลดที่มีข้อมูลเมตา หากมี

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

3. ส่งไฟล์สื่อไปยัง 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-Length ที่จำเป็นสำหรับการอัปโหลดไฟล์แบบเต็ม

• Content-Length กำหนดเป็นขนาดกลุ่มหรืออาจน้อยกว่านั้น เนื่องจากอาจเป็นกรณีสำหรับคำขอล่าสุด

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

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

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

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/png
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 หากคุณไม่ทราบขนาดเต็มไฟล์ ให้ตั้งค่า ช่วงเนื้อหาเป็น */*

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

3. อัปโหลดข้อมูลที่เหลือ และสุดท้าย ตอนนี้คุณก็ทราบแล้วว่า ให้ส่งข้อมูลที่เหลือหรือกลุ่มปัจจุบัน โปรดทราบว่าคุณต้องดำเนินการดังนี้ ข้อมูลที่เหลือแยกเป็นส่วนๆ ในทั้ง 2 กรณี คุณจึงต้องส่ง Content-Rangeเมื่ออัปโหลดต่อ

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

1. ขอสถานะการอัปโหลด คำขอต่อไปนี้ใช้ช่วงเนื้อหา เพื่อระบุว่าตำแหน่งปัจจุบันในไฟล์ขนาด 2,000,000 ไบต์คือ ไม่รู้จัก

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

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

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

1. อัปโหลดต่อจากจุดที่ค้างไว้ คำขอต่อไปนี้ ทำให้การอัปโหลดกลับมาทำงานอีกครั้งโดยการส่งไบต์ที่เหลือของไฟล์ โดยเริ่มต้นที่ไบต์ 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 วินาที + สุ่มตัวเลข_จำนวนมิลลิวินาที แล้วลองส่งคำขออีกครั้ง
6. ได้รับการตอบกลับ HTTP 503 ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
7. โปรดรอ 4 วินาที + สุ่มตัวเลข_มิลลิวินาที แล้วลองส่งคำขออีกครั้ง
8. รับ HTTP 503 response ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
9. โปรดรอ 8 วินาที + สุ่มตัวเลข_จำนวนมิลลิวินาที แล้วลองส่งคำขออีกครั้ง
10. รับ HTTP 503 response ซึ่งบ่งชี้ว่าคุณควรลองส่งคำขออีกครั้ง
11. โปรดรอ 16 วินาที + สุ่มตัวเลข_มิลลิวินาที แล้วลองส่งคำขออีกครั้ง
12. หยุด รายงานหรือบันทึกข้อผิดพลาด

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

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

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

• .NET

• Java

• PHP

• Python

• Ruby