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

หน้านี้จะอธิบายวิธีส่งคำขออัปโหลดไปยัง 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 แสดงว่าการอัปโหลดสิ้นสุดลงแล้ว