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

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

ตัวอย่างต่อไปนี้แสดงการตอบกลับที่มี 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 แสดงว่าการอัปโหลดสิ้นสุดลงแล้ว