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

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

หมายเหตุ: URL ของเซสชันที่ดำเนินการต่อได้จะหมดอายุหลังจากผ่านไป 7 วัน

ขั้นตอนที่ 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 ซึ่งบ่งชี้ว่าการอัปโหลดมี ถูกสิ้นสุดการใช้งานแล้ว