หน้านี้จะอธิบายวิธีส่งคำขออัปโหลดไปยัง 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 วิธีดังนี้
- ในคำขอเดียว โดยปกติวิธีนี้จะดีที่สุด เนื่องจากต้องการคำขอน้อยกว่า จึงมีประสิทธิภาพมากกว่า
-
แบ่งเป็นหลายๆ ส่วน ในวิธีนี้ การอัปโหลดจะเกิดขึ้นในคำขอหลายรายการด้วยการแบ่งข้อมูลออกเป็นส่วนๆ ข้อมูลจะแบ่งเป็นส่วนพหุคูณของ
x-goog-upload-chunk-granularity
หากจำเป็น คุณลองส่งคำขอที่แบ่งเป็นส่วนๆ อีกครั้งได้ใช้วิธีการนี้ในกรณีต่อไปนี้
- คุณต้องลดจำนวนข้อมูลที่โอนในคำขอเดียว คุณอาจต้องทำขั้นตอนนี้เมื่อมีขีดจำกัดเวลาที่แน่นอนสำหรับคำขอแต่ละรายการ
- คุณต้องระบุตัวบ่งชี้ที่กำหนดเองเพื่อแสดงความคืบหน้าของการอัปโหลด
- คุณต้องทราบว่าเมื่อใดที่สามารถทิ้งข้อมูลได้อย่างปลอดภัย
คำขอเดียว
วิธีอัปโหลดไฟล์ในคำขอเดียว
- สร้างคำขอ
POST
ไปยัง URL ของเซสชันที่กลับมาทำงานอีกครั้งได้ - เพิ่มข้อมูลของไฟล์ในเนื้อหาคำขอ
เพิ่มส่วนหัว HTTP ต่อไปนี้
Content-Length
: กำหนดจำนวนไบต์ในไฟล์X-Goog-Upload-Command
: ตั้งค่าเป็นupload, finalize
ส่งคำขอ
หากคำขออัปโหลดหยุดชะงักหรือคุณได้รับการตอบกลับ 5xx
ให้ทำตามขั้นตอนในการดำเนินการอัปโหลดที่หยุดชะงักต่อ
หากคำขอสำเร็จ คุณจะได้รับรหัสสถานะ HTTP 200 OK
และโทเค็นการอัปโหลดในเนื้อหาการตอบสนอง
สร้างรายการสื่อโดยใช้โทเค็นการอัปโหลดนี้
หลายชิ้น
หากต้องการอัปโหลดไฟล์เป็นกลุ่มหลายรายการ ให้ทำดังนี้
- สร้างคำขอ
POST
ไปยัง URL ของเซสชันที่กลับมาทำงานอีกครั้งได้ -
เพิ่มข้อมูลของกลุ่มลงในเนื้อหาคำขอ
สร้างกลุ่มอื่นๆ เป็นพหุคูณของขนาดกลุ่มที่ยอมรับ จำกัดกลุ่มให้ใหญ่ที่สุดเท่าที่จะเป็นไปได้เพื่อให้การอัปโหลดเป็นไปอย่างมีประสิทธิภาพ
-
เพิ่มส่วนหัว HTTP ต่อไปนี้
Content-Length
: กำหนดจำนวนไบต์ในกลุ่มX-Goog-Upload-Command
: ตั้งค่าเป็นupload
สำหรับกลุ่มสุดท้าย ให้ตั้งค่าเป็นupload, finalize
X-Goog-Upload-Offset
: ตั้งค่าเป็นออฟเซ็ตที่ควรเขียนไบต์ โปรดทราบว่าคุณต้องอัปโหลดไบต์ตามลำดับ การชดเชยแรกคือ0
- ส่งคำขอ
หากคำขออัปโหลดหยุดชะงักหรือคุณได้รับการตอบกลับ
5xx
ให้ทำตามขั้นตอนในการดำเนินการอัปโหลดที่หยุดชะงักต่อ - ทำขั้นตอนข้างต้นซ้ำกับแต่ละส่วนที่เหลืออยู่ในไฟล์
หากคำขอสำเร็จ คุณจะได้รับรหัสสถานะ 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
แสดงว่าการอัปโหลดสิ้นสุดลงแล้ว