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

หน้านี้จะอธิบายวิธีส่งคำขออัปโหลดที่กลับมาดำเนินการต่อได้อีกครั้งใน Street View Publish 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. ส่งคำขอ

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

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