อัปโหลดแบบกลับมาทำต่อได้

หน้านี้จะอธิบายวิธีส่งคำขออัปโหลดที่ดำเนินการต่อไปยัง Google Photos Library API ต่อผ่านโปรโตคอล REST โปรโตคอลนี้ช่วยให้คุณดำเนินการอัปโหลดต่อได้หลังจากการสื่อสารไม่สำเร็จขัดจังหวะการไหลของข้อมูล

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

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

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

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

เริ่มต้นเซสชันการอัปโหลดที่กลับมาทำงานอีกครั้งได้โดยการส่งคำขอ POST ไปยัง https://photoslibrary.googleapis.com/v1/uploads อัปโหลดไฟล์โดยใช้ URL สำหรับการอัปโหลดต่อได้ซึ่งแสดงในคำขอนี้

คำขอ POST ต้องมีส่วนหัวต่อไปนี้

ช่องส่วนหัว
Content-Length ตั้งค่าเป็น 0 เนื่องจากเนื้อหาของคำขอว่างเปล่า
X-Goog-Upload-Command ตั้งค่าเป็น start
X-Goog-Upload-Content-Type ตั้งค่าเป็นประเภท MIME ของไฟล์ เช่น image/jpeg
X-Goog-Upload-Protocol ตั้งค่าเป็น resumable
X-Goog-Upload-Raw-Size กําหนดเป็นจํานวนไบต์ทั้งหมดของข้อมูลไฟล์ที่จะโอน

ส่วนหัวคำขอ POST มีดังนี้

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

ขั้นตอนที่ 2: บันทึก URL ของเซสชัน

หากสำเร็จ คำขอ POST จะแสดงรหัสสถานะ HTTP 200 OK รวมถึงส่วนหัวต่อไปนี้

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

ช่องส่วนหัว x-goog-upload-chunk-granularity มีการจัดแนวไบต์และความละเอียดของขนาดสำหรับกลุ่มข้อมูลทั้งหมดที่ส่งโดยไคลเอ็นต์ หากการอัปโหลดทำเป็นหลายกลุ่ม การอัปโหลดทั้งหมดยกเว้นการอัปโหลดครั้งล่าสุดจะต้องเป็นจำนวนที่คูณด้วยค่านี้ กล่าวคือ จำนวนไบต์การอัปโหลดของไฟล์ต้องสอดคล้องกับค่านี้ ในข้อมูลโค้ดสุดท้าย คุณจะอัปโหลดไบต์ที่เหลือได้

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

ขั้นตอนที่ 3: อัปโหลดไฟล์

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

  1. ในคําขอเดียว โดยทั่วไปแล้ว แนวทางนี้ถือเป็นแนวทางที่ดีที่สุด เนื่องจากมีคำขอน้อยกว่า จึงมีประสิทธิภาพดีกว่า

  2. เป็นหลายกลุ่ม วิธีการนี้จะอัปโหลดในคำขอหลายรายการโดยแบ่งข้อมูลออกเป็นหลายกลุ่ม ระบบจะแบ่งข้อมูลเป็นกลุ่มๆ ทีละ x-goog-upload-chunk-granularity หากจำเป็น คุณจะลองส่งคำขอที่แบ่งส่วนนี้อีกครั้งได้

    ใช้แนวทางนี้ในกรณีต่อไปนี้

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

คำขอเดียว

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

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

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

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

  4. ส่งคำขอ

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

หากคำขอสำเร็จ คุณจะได้รับรหัสสถานะ HTTP 200 OK และโทเค็นการอัปโหลดในเนื้อหาการตอบกลับ สร้างรายการสื่อโดยใช้โทเค็นการอัปโหลดนี้

หลายกลุ่ม

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

  1. สร้างคำขอ POST ไปยัง URL ของเซสชันที่ดำเนินการต่อได้

  2. เพิ่มข้อมูลของข้อมูลไปยังเนื้อหาคำขอ

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

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

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

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

  5. ทำขั้นตอนเหล่านี้ซ้ำสำหรับแต่ละกลุ่มที่เหลืออยู่ในไฟล์

หากคำขอสำเร็จ คุณจะได้รับรหัสสถานะ HTTP 200 OK และโทเค็นการอัปโหลดในเนื้อหาการตอบกลับ สร้างรายการสื่อโดยใช้โทเค็นการอัปโหลดนี้

ตัวอย่าง

คำขอเดียว

ตัวอย่างต่อไปนี้แสดงคำขอที่กลับมาดำเนินการต่อได้เพื่ออัปโหลดไฟล์ JPEG ขนาด 3,039,417 ไบต์ในคำขอเดียว

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

การตอบกลับจะมี URL การอัปโหลดและขนาดข้อมูลที่จะอัปโหลดตามที่ต้องการ

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

คำขออัปโหลดครั้งสุดท้าย

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

หลายกลุ่ม

ตัวอย่างต่อไปนี้แสดงคำขอที่กลับมาดำเนินการต่อได้เพื่ออัปโหลดไฟล์ JPEG ขนาด 3,039,417 ไบต์เป็นหลายกลุ่มโดยใช้ URL เซสชันที่กลับมาดำเนินการต่อได้และความละเอียดของขนาดกลุ่มที่ยอมรับซึ่งได้รับในขั้นตอนก่อนหน้า ตัวอย่างนี้ใช้ขนาดของกลุ่มเป็น 262,144 ไบต์ ซึ่งแสดงผลในช่องส่วนหัว x-goog-upload-chunk-granularity เมื่อเริ่มต้นเซสชันการอัปโหลด โปรดทราบว่าการอัปโหลดแต่ละครั้งมีไบต์ที่อยู่ในจำนวนพหุคูณของ 262,144

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

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

การตอบกลับจะมี URL การอัปโหลดและขนาดข้อมูลที่จะอัปโหลดตามที่ต้องการ

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

กลุ่มแรก:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

ข้อมูลโค้ดที่ 2

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

ข้อมูลโค้ดล่าสุด:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

การอัปโหลดที่หยุดชะงักต่อ

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

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

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

การตอบกลับจากเซิร์ฟเวอร์จะมีรหัสสถานะ 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 แสดงว่าการอัปโหลดถูกยกเลิกแล้ว