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

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

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

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

หากคุณส่งไฟล์ขนาดเล็กผ่านการเชื่อมต่อเครือข่ายที่เชื่อถือได้ คุณสามารถใช้การอัปโหลดง่ายๆ แทน

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

หลังจากได้รับ uploadUrl แล้ว คุณสามารถเริ่มเซสชันการอัปโหลดที่ดำเนินการต่อได้ โดยทำดังนี้

  1. สร้างคำขอ POST ไปยัง uploadUrl

  2. เพิ่มส่วนหัว HTTP ต่อไปนี้

    • X-Goog-Upload-Protocol: ตั้งเป็น resumable
    • X-Goog-Upload-Header-Content-Length: ตั้งค่าเป็นจำนวนไบต์รวมของข้อมูลไฟล์ ซึ่งจะโอนในคำขอที่ตามมา
    • X-Goog-Upload-Header-Content-Type: ตั้งค่าเป็นประเภท MIME ของข้อมูลไฟล์
    • X-Goog-Upload-Command: ตั้งเป็น start

  3. ส่งคำขอ

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

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

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

การบันทึก URL ของเซสชันที่กลับมาทำงานต่อได้จะอธิบายวิธีการจัดการการตอบกลับคำขอเพื่อเริ่มเซสชันการอัปโหลดที่กลับมาทำงานต่อได้

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

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

  • X-Goog-Upload-URL: URL ที่ไม่ซ้ำกันซึ่งต้องใช้เพื่อดำเนินการอัปโหลดผ่านคำขอที่เหลือทั้งหมดให้เสร็จสมบูรณ์

คัดลอกและบันทึก URL ของอินสแตนซ์ที่ดำเนินการต่อได้เพื่อให้คุณใช้สำหรับคำขอในลำดับต่อๆ ไปได้

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

ตัวอย่างต่อไปนี้แสดงการตอบกลับที่มี URL เซสชันที่กลับมาทำงานอีกครั้งได้และข้อกำหนดรายละเอียดของขนาด

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

กำลังอัปโหลดไฟล์

มี 2 วิธีในการอัปโหลดไฟล์ที่มีเซสชันที่สามารถดำเนินการต่อได้ ดังนี้

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

คำขอเดียว

วิธีอัปโหลดไฟล์ในคำขอเดียว

  1. สร้างคำขอ POST ไปยัง URL ของเซสชันที่กลับมาทำงานต่อได้
  2. เพิ่มข้อมูลของไฟล์ในเนื้อหาคำขอ

  3. เพิ่มส่วนหัว HTTP ต่อไปนี้

    • Content-Length: กำหนดเป็นจำนวนไบต์ในไฟล์
    • X-Goog-Upload-Command: ตั้งเป็น upload, finalize

  4. ส่งคำขอ

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

แบบเปียกหลายชิ้น

วิธีอัปโหลดไฟล์เป็นหลายรายการ

  1. สร้างคำขอ POST ไปยัง URL ของเซสชันที่กลับมาทำงานต่อได้
  2. เพิ่มข้อมูลของกลุ่มลงในเนื้อหาคำขอ สร้างส่วนเป็นพหุคูณของ 2 MiB (เมบิไบต์) ยกเว้นส่วนสุดท้ายที่เสร็จสิ้นการอัปโหลด ลดขนาดวิดีโอให้ได้มากที่สุดเพื่อให้การอัปโหลดเป็นไปอย่างมีประสิทธิภาพ

  3. เพิ่มส่วนหัว HTTP ต่อไปนี้

    • Content-Length: กำหนดจำนวนไบต์ในกลุ่ม
    • X-Goog-Upload-Command: ตั้งเป็น upload สำหรับกลุ่มสุดท้าย ให้ตั้งค่าเป็น upload, finalize
    • X-Goog-Upload-Offset: ตั้งค่าเป็นออฟเซ็ตที่ควรเขียนไบต์ โปรดทราบว่าต้องอัปโหลดไบต์ตามลำดับ

  4. ส่งคำขอ หากคำขออัปโหลดหยุดชะงักหรือคุณได้รับการตอบกลับจาก 5xx ให้ทำตามขั้นตอนในการดำเนินการอัปโหลดที่หยุดชะงักต่อ

  5. ทำซ้ำขั้นตอนที่ 1 ถึง 4 สำหรับแต่ละส่วนที่เหลือในไฟล์

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

คำขอเดียว

ตัวอย่างต่อไปนี้แสดงคำขอที่เรียกกลับมาดำเนินการต่อได้เพื่ออัปโหลดไฟล์ JPEG ทั้งไฟล์ 4,200,000 ไบต์ในคำขอเดียว โดยใช้ URL เซสชันที่กลับมาทำงานอีกครั้งได้จากขั้นตอนก่อนหน้า

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

หากคำขอประสบความสำเร็จ คุณจะได้รับรหัสสถานะ HTTP 200 OK

แบบเปียกหลายชิ้น

ตัวอย่างต่อไปนี้แสดงคำขอที่ดำเนินการต่อได้เพื่ออัปโหลดไฟล์ JPEG ขนาด 4,200,000 ไบต์ในหลายส่วน โดยใช้ URL เซสชันที่กลับมาทำงานต่อได้และรายละเอียดของขนาดที่ได้ในขั้นตอนก่อนหน้า ตัวอย่างนี้ใช้ขนาดกลุ่ม 2097000 ไบต์ ซึ่งเป็นผลคูณของ 2 MiB (เมบิไบต์)

กลุ่มแรก: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

กลุ่มที่ 2: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

กลุ่มสุดท้าย: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

การอัปโหลดที่หยุดชะงักกลับมาทำงานอีกครั้ง

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

  1. สร้างคำขอ POST ไปยัง URL ของเซสชันที่กลับมาทำงานต่อได้
  2. ตั้งค่า X-Goog-Upload-Command เป็น query
  3. ส่งคำขอ

เซิร์ฟเวอร์จะตอบกลับด้วยรหัสสถานะ HTTP 200 OK และขนาดปัจจุบันของการอัปโหลด ดังนี้

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

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

หากมีส่วนหัว X-Goog-Upload-Status ในการตอบกลับ HTTP ของคำสั่งคำค้นหาและค่าไม่ใช่ active แสดงว่าการอัปโหลดถูกยกเลิกไปแล้ว