การอัปโหลดรายการสื่อมี 2 ขั้นตอนดังนี้
- อัปโหลดไบต์ของไฟล์สื่อไปยังเซิร์ฟเวอร์ของ Google โดยใช้ปลายทาง uploads ซึ่งจะแสดงผลโทเค็นการอัปโหลดที่ระบุไบต์ที่อัปโหลด
- ใช้การเรียกใช้ batchCreate กับโทเค็นการอัปโหลดเพื่อสร้างรายการสื่อในบัญชี Google Photos ของผู้ใช้
ขั้นตอนเหล่านี้จะอธิบายกระบวนการอัปโหลดรายการสื่อรายการเดียว หากคุณอัปโหลดรายการสื่อหลายรายการ (ซึ่งเป็นไปได้สูงสำหรับแอปพลิเคชันเวอร์ชันที่ใช้งานจริง) โปรดอ่านแนวทางปฏิบัติแนะนำสำหรับการอัปโหลดเพื่อปรับปรุงประสิทธิภาพการอัปโหลด
ก่อนเริ่มต้น
ขอบเขตการให้สิทธิ์ที่จําเป็น
การอัปโหลดรายการสื่อไปยังคลังหรืออัลบั้มของผู้ใช้ต้องใช้ขอบเขต photoslibrary.appendonly ดูข้อมูลเพิ่มเติมเกี่ยวกับขอบเขตได้ที่ขอบเขตการให้สิทธิ์
ประเภทและขนาดไฟล์ที่ยอมรับ
คุณสามารถอัปโหลดไฟล์ประเภทที่แสดงในตารางนี้ได้
| ประเภทสื่อ | ประเภทไฟล์ที่ยอมรับ | ขนาดไฟล์สูงสุด |
|---|---|---|
| Photos | AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, ไฟล์ RAW บางประเภท | 200 MB |
| วิดีโอ | 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV | 20 GB |
ขั้นตอนที่ 1: การอัปโหลดไบต์
อัปโหลดไบต์ไปยัง Google โดยใช้คำขออัปโหลด คำขออัปโหลดที่ดำเนินการสำเร็จจะแสดงโทเค็นการอัปโหลดในรูปแบบสตริงข้อความดิบ ใช้โทเค็นการอัปโหลดเหล่านี้เพื่อสร้างรายการสื่อด้วยการเรียก batchCreate
REST
ใส่ช่องต่อไปนี้ในส่วนหัวของคำขอ POST
| ฟิลด์ส่วนหัว | |
|---|---|
Content-type |
ตั้งค่าเป็น application/octet-stream |
X-Goog-Upload-Content-Type |
แนะนำ ตั้งค่าเป็นประเภท MIME ของไบต์ที่คุณอัปโหลด
ประเภท MIME ทั่วไป ได้แก่ image/jpeg,
image/png และ image/gif
|
X-Goog-Upload-Protocol |
ตั้งค่าเป็น raw |
ส่วนหัวคำขอ POST มีดังนี้
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-type: application/octet-stream X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: raw
ในเนื้อหาคำขอ ให้ใส่ไบนารีของไฟล์ดังนี้
media-binary-data
หากคำขอ POST นี้สำเร็จ ระบบจะแสดงโทเค็นการอัปโหลดในรูปแบบสตริงข้อความดิบเป็นเนื้อหาการตอบกลับ หากต้องการสร้างรายการสื่อ ให้ใช้สตริงข้อความเหล่านี้ในคําเรียก batchCreate
upload-token
ขนาดไฟล์ที่แนะนำสำหรับรูปภาพคือน้อยกว่า 50 MB ไฟล์ที่มีขนาดใหญ่กว่า 50 MB มีแนวโน้มที่จะเกิดปัญหาด้านประสิทธิภาพ
Google Photos Library API รองรับการอัปโหลดต่อได้ การอัปโหลดที่กลับมาดำเนินการต่อได้ช่วยให้คุณแบ่งไฟล์สื่อออกเป็นหลายส่วนและอัปโหลดทีละส่วนได้
ขั้นตอนที่ 2: การสร้างรายการสื่อ
หลังจากอัปโหลดไบต์ของไฟล์สื่อแล้ว คุณจะสร้างไฟล์เหล่านั้นเป็นรายการสื่อใน Google Photos โดยใช้โทเค็นการอัปโหลดได้ โทเค็นการอัปโหลดจะใช้ได้ 1 วันหลังจากที่สร้าง ระบบจะเพิ่มรายการสื่อลงในคลังภาพของผู้ใช้เสมอ รายการสื่อจะเพิ่มลงในอัลบั้มที่แอปของคุณสร้างขึ้นได้เท่านั้น ดูข้อมูลเพิ่มเติมได้ที่ขอบเขตการให้สิทธิ์
หากต้องการสร้างรายการสื่อใหม่ ให้เรียกใช้ mediaItems.batchCreate โดยระบุรายการ newMediaItems newMediaItem แต่ละรายการจะมีโทเค็นการอัปโหลดที่ระบุไว้ใน simpleMediaItem และคำอธิบายที่ไม่บังคับซึ่งแสดงต่อผู้ใช้
ช่องคำอธิบายมีอักขระได้ไม่เกิน 1,000 ตัวและควรมีเฉพาะข้อความที่มีความหมายซึ่งสร้างโดยผู้ใช้ เช่น "ทริปสวนสาธารณะของเรา" หรือ "อาหารเย็นวันหยุด" อย่าใส่ข้อมูลเมตา เช่น ชื่อไฟล์ แท็กแบบเป็นโปรแกรม หรือข้อความอื่นๆ ที่สร้างขึ้นโดยอัตโนมัติ
หากต้องการประสิทธิภาพที่ดีที่สุด ให้ลดจำนวนการเรียก mediaItems.batchCreate ที่ต้องดำเนินการโดยรวมรายการสื่อหลายรายการไว้ในการเรียกครั้งเดียว รอจนกว่าคำขอก่อนหน้าจะเสร็จสิ้นเสมอ ก่อนที่จะเรียกใช้ครั้งต่อๆ ไปสำหรับผู้ใช้รายเดิม
คุณสามารถสร้างรายการสื่อรายการเดียวหรือหลายรายการในคลังภาพของผู้ใช้ได้ โดยระบุคำอธิบายและโทเค็นการอัปโหลดที่เกี่ยวข้อง ดังนี้
REST
ต่อไปนี้คือส่วนหัวของคำขอ POST
POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate Content-type: application/json Authorization: Bearer oauth2-token
เนื้อความของคำขอควรระบุรายการ newMediaItems
{
"newMediaItems": [
{
"description": "item-description",
"simpleMediaItem": {
"fileName": "filename",
"uploadToken": "upload-token"
}
}
, ...
]
}คุณยังระบุ albumId และ albumPosition เพื่อแทรกรายการสื่อที่ตำแหน่งที่เจาะจงในอัลบั้มได้อีกด้วย
REST
{
"albumId": "album-id",
"newMediaItems": [
{
"description": "item-description",
"simpleMediaItem": {
"fileName": "filename",
"uploadToken": "upload-token"
}
}
, ...
],
"albumPosition": {
"position": "after-media-item",
"relativeMediaItemId": "media-item-id"
}
}โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดตําแหน่งในอัลบั้มที่หัวข้อเพิ่มการเสริมข้อมูล
คำตอบในการสร้างรายการ
การเรียกใช้ mediaItems.batchCreate จะแสดงผลลัพธ์สำหรับรายการสื่อแต่ละรายการที่คุณพยายามสร้าง รายการ newMediaItemResults จะระบุสถานะและรวม uploadToken ของคําขอ รหัสสถานะที่ไม่เท่ากับ 0 บ่งบอกถึงข้อผิดพลาด
REST
หากสร้างรายการสื่อทั้งหมดเรียบร้อยแล้ว คำขอจะแสดงสถานะ HTTP 200 OK หากสร้างรายการสื่อบางรายการไม่ได้ คำขอจะแสดงสถานะ HTTP 207 MULTI-STATUS เพื่อบ่งบอกว่าดำเนินการสำเร็จบางส่วน
{
"newMediaItemResults": [
{
"uploadToken": "upload-token",
"status": {
"message": "Success"
},
"mediaItem": {
"id": "media-item-id",
"description": "item-description",
"productUrl": "https://photos.google.com/photo/photo-path",
"mimeType": "mime-type",
"mediaMetadata": {
"width": "media-width-in-px",
"height": "media-height-in-px",
"creationTime": "creation-time",
"photo": {}
},
"filename": "filename"
}
},
{
"uploadToken": "upload-token",
"status": {
"code": 13,
"message": "Internal error"
}
}
]
}หากเพิ่มรายการสำเร็จแล้ว ระบบจะแสดงผล mediaItem ที่มี mediaItemId, productUrl และ mediaMetadata ดูข้อมูลเพิ่มเติมได้ที่เข้าถึงรายการสื่อ
หากรายการสื่อเป็นวิดีโอ คุณต้องประมวลผลรายการนั้นก่อน mediaItem
มี status ภายใน mediaMetadata ซึ่งอธิบายสถานะการประมวลผลของไฟล์วิดีโอ ไฟล์ที่อัปโหลดใหม่จะแสดงสถานะ PROCESSING ก่อน ก่อนที่จะREADYสำหรับการใช้งาน โปรดดูรายละเอียดที่หัวข้อเข้าถึงรายการสื่อ
หากพบข้อผิดพลาดระหว่างการโทรนี้ โปรดทำตามแนวทางปฏิบัติแนะนำและส่งคำขออีกครั้ง คุณอาจต้องการติดตามรายการที่เพิ่มสำเร็จ เพื่อแทรกรูปภาพลงในอัลบั้มในตำแหน่งที่ถูกต้องเมื่อส่งคำขอครั้งต่อไป ดูข้อมูลเพิ่มเติมได้ที่สร้างอัลบั้ม
ระบบจะแสดงผลลัพธ์ตามลำดับเดียวกับที่ส่งโทเค็นการอัปโหลด
แนวทางปฏิบัติแนะนำสำหรับการอัปโหลด
แนวทางปฏิบัติแนะนำและแหล่งข้อมูลต่อไปนี้จะช่วยปรับปรุงประสิทธิภาพโดยรวมในการอัปโหลด
- ทําตามแนวทางปฏิบัติแนะนําในการลองอีกครั้งและการจัดการข้อผิดพลาด โดยคำนึงถึงประเด็นต่อไปนี้
- ข้อผิดพลาด
429รายการอาจเกิดขึ้นเมื่อโควต้าของคุณหมดหรือคุณถูกจำกัดอัตราการโทรมากเกินไปสำหรับการโทรเร็วเกินไป โปรดตรวจสอบว่าคุณไม่ได้เรียกใช้batchCreateสำหรับผู้ใช้รายเดียวกันจนกว่าคำขอก่อนหน้าจะเสร็จสมบูรณ์ - ข้อผิดพลาด
429จะต้องรออย่างน้อย30sวินาทีก่อนลองอีกครั้ง ใช้กลยุทธ์ Exponential Backoff เมื่อลองส่งคำขออีกครั้ง - ข้อผิดพลาด
500เกิดขึ้นเมื่อเซิร์ฟเวอร์พบข้อผิดพลาด เมื่ออัปโหลด ปัญหานี้อาจเกิดจากมีการเรียกใช้การเขียนหลายครั้ง (เช่นbatchCreate) สําหรับผู้ใช้รายเดียวกันในเวลาเดียวกัน ตรวจสอบรายละเอียดของคำขอและอย่าโทรหาbatchCreateพร้อมกัน
- ข้อผิดพลาด
- ใช้ขั้นตอนการอัปโหลดที่กลับมาดำเนินการต่อได้เพื่อให้การอัปโหลดมีประสิทธิภาพมากขึ้นในกรณีที่เครือข่ายขัดข้อง ซึ่งจะช่วยลดการใช้แบนด์วิดท์ด้วยการอนุญาตให้คุณกลับมาดำเนินการอัปโหลดที่ดำเนินการไปแล้วบางส่วนต่อได้ ซึ่งสำคัญเมื่ออัปโหลดจากอุปกรณ์เคลื่อนที่ของลูกค้า หรือเมื่ออัปโหลดไฟล์ขนาดใหญ่
นอกจากนี้ ให้ลองใช้เคล็ดลับต่อไปนี้สำหรับแต่ละขั้นตอนของกระบวนการอัปโหลด ซึ่งได้แก่ การอัปโหลดไบต์ แล้วสร้างรายการสื่อ
การอัปโหลดไบต์
- การอัปโหลดไบต์ (เพื่อเรียกโทเค็นการอัปโหลด) สามารถทำได้พร้อมกัน
- ตั้งค่าประเภท MIME ที่ถูกต้องในส่วนหัว
X-Goog-Upload-Content-Typeสำหรับการเรียกใช้การอัปโหลดแต่ละครั้งเสมอ
การสร้างรายการสื่อ
อย่าโทรออกพร้อมกันกับ
batchCreateสำหรับผู้ใช้รายเดียว- สําหรับผู้ใช้แต่ละราย ให้โทรหา
batchCreateตามลําดับ (แบบอนุกรม) - สำหรับผู้ใช้หลายคน ให้เรียก
batchCreateสำหรับผู้ใช้แต่ละรายทีละคนเสมอ เรียกผู้ใช้ที่แตกต่างกันพร้อมกันเท่านั้น
- สําหรับผู้ใช้แต่ละราย ให้โทรหา
รวมจำนวน
NewMediaItemsให้มากที่สุด ในการโทรหาbatchCreateแต่ละครั้งเพื่อลดจำนวนการโทรทั้งหมดที่คุณต้องโทร คุณใส่รายการได้สูงสุด 50 รายการตั้งค่าข้อความคำอธิบายที่มีความหมาย ซึ่งผู้ใช้สร้างไว้ อย่าใส่ข้อมูลเมตา เช่น ชื่อไฟล์ แท็กแบบเป็นโปรแกรม หรือข้อความอื่นๆ ที่สร้างขึ้นโดยอัตโนมัติในช่องคำอธิบาย
ตัวอย่างคำแนะนำแบบทีละขั้น
ตัวอย่างนี้ใช้ Pseudocode ในทุกขั้นตอนของการอัปโหลดรายการสื่อสำหรับผู้ใช้หลายคน เป้าหมายคือเพื่ออธิบายทั้ง 2 ขั้นตอนของกระบวนการอัปโหลด (การอัปโหลดไบต์ดิบและการสร้างรายการสื่อ) รวมถึงอธิบายแนวทางปฏิบัติแนะนำในการสร้างการผสานรวมการอัปโหลดที่มีประสิทธิภาพและยืดหยุ่น
ขั้นตอนที่ 1: อัปโหลดไบต์ดิบ
ก่อนอื่นให้สร้างคิวเพื่ออัปโหลดไบต์ดิบสำหรับรายการสื่อจากผู้ใช้ทั้งหมด ติดตาม uploadToken แต่ละรายการที่แสดงต่อผู้ใช้ โปรดจำประเด็นสำคัญต่อไปนี้
- จำนวนเธรดการอัปโหลดพร้อมกันจะขึ้นอยู่กับสภาพแวดล้อมการทํางาน
- ลองจัดเรียงคิวการอัปโหลดใหม่ตามต้องการ เช่น คุณอาจจัดลำดับความสำคัญของการอัปโหลดตามจำนวนการอัปโหลดที่เหลืออยู่ต่อผู้ใช้ ความคืบหน้าโดยรวมของผู้ใช้ หรือข้อกำหนดอื่นๆ
ซูโดโค้ด
CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
WHILE uploadQueue is not empty
POP uploadQueue
UPLOAD file for user
GET uploadToken
CHECK and HANDLE errors
STORE uploadToken for user in uploadTokensQueue
ENDขั้นตอนที่ 2: สร้างรายการสื่อ
ในขั้นตอนที่ 1 คุณสามารถอัปโหลดไบต์หลายรายการจากผู้ใช้หลายคนพร้อมกันได้ แต่ในขั้นตอนที่ 2 คุณจะเรียกใช้ผู้ใช้แต่ละรายได้ครั้งละ 1 รายเท่านั้น
ซูโดโค้ด
// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
// Calls can be made in parallel for different users,
// but only make a single call per user at a time.
START new thread for (this) user if there is no thread yet
POP 50 uploadTokens from uploadTokensQueue for user
CALL mediaItems.batchCreate with uploadTokens
WAIT UNTIL batchCreate call has completed
CHECK and HANDLE errors (retry as needed)
DONE.ทำตามกระบวนการนี้จนกว่าการเรียกใช้การอัปโหลดและการสร้างสื่อทั้งหมดจะเสร็จสมบูรณ์