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

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