การอัปโหลดรายการสื่อมี 2 ขั้นตอน ดังนี้
- อัปโหลดไบต์ของไฟล์สื่อไปยังเซิร์ฟเวอร์ของ Google โดยใช้ปลายทางการอัปโหลด การดำเนินการนี้จะแสดงโทเค็นการอัปโหลดซึ่งระบุไบต์ที่อัปโหลด
- ใช้การเรียกใช้batchCreate กับโทเค็นการอัปโหลดเพื่อสร้างรายการสื่อในบัญชี Google Photos ของผู้ใช้
ขั้นตอนเหล่านี้จะระบุขั้นตอนการอัปโหลดสื่อรายการเดียว หากคุณอัปโหลดรายการสื่อหลายรายการ (มีแนวโน้มอย่างมากสำหรับแอปพลิเคชันเวอร์ชันที่ใช้งานจริง) โปรดอ่านแนวทางปฏิบัติแนะนำสำหรับการอัปโหลดเพื่อปรับปรุงประสิทธิภาพการอัปโหลด
ก่อนเริ่มต้น
ขอบเขตการให้สิทธิ์ที่จำเป็น
การอัปโหลดรายการสื่อไปยังคลังหรืออัลบั้มของผู้ใช้ต้องใช้ขอบเขต photoslibrary.appendonly
หรือ photoslibrary
คุณสามารถสร้างรายการสื่อโดยใช้ขอบเขต photoslibrary.sharing
ได้ด้วย หากต้องการสร้างรายการที่มีขอบเขต photoslibrary.sharing
คุณต้องสร้างอัลบั้มและทำเครื่องหมายเป็นแชร์แล้วโดยใช้ shareAlbum
จากนั้นคุณจะสามารถสร้างรายการสื่อ
ที่แชร์กับผู้ใช้ในอัลบั้มได้ คุณไม่สามารถสร้างรายการใน
ห้องสมุดของผู้ใช้โดยตรง หรือในอัลบั้มที่แอปไม่ได้แชร์
เมื่อแสดงรายการอัลบั้ม พร็อพเพอร์ตี้ isWriteable
จะระบุว่าแอปพลิเคชันของคุณมีสิทธิ์เข้าถึงเพื่อสร้างสื่อในอัลบั้มใดอัลบั้มหนึ่งหรือไม่
ประเภทและขนาดของไฟล์ที่ยอมรับ
คุณอัปโหลดไฟล์ประเภทที่ระบุไว้ในตารางด้านล่างได้
ประเภทสื่อ | ประเภทไฟล์ที่ยอมรับ | ขนาดไฟล์สูงสุด |
---|---|---|
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
Java
// Open the file and automatically close it after upload try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) { // Create a new upload request UploadMediaItemRequest uploadRequest = UploadMediaItemRequest.newBuilder() // The media type (e.g. "image/png") .setMimeType(mimeType) // The file to upload .setDataFile(file) .build(); // Upload and capture the response UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest); if (uploadResponse.getError().isPresent()) { // If the upload results in an error, handle it Error error = uploadResponse.getError().get(); } else { // If the upload is successful, get the uploadToken String uploadToken = uploadResponse.getUploadToken().get(); // Use this upload token to create a media item } } catch (ApiException e) { // Handle error } catch (IOException e) { // Error accessing the local file }
PHP
try { // Create a new upload request by opening the file // and specifying the media type (e.g. "image/png") $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType); } catch (\GuzzleHttp\Exception\GuzzleException $e) { // Handle error }
ขนาดไฟล์ที่แนะนำสำหรับรูปภาพคือน้อยกว่า 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" } } , ... ] }
Java
try { // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos NewMediaItem newMediaItem = NewMediaItemFactory .createNewMediaItem(uploadToken, fileName, itemDescription); List<NewMediaItem> newItems = Arrays.asList(newMediaItem); BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) { Status status = itemsResponse.getStatus(); if (status.getCode() == Code.OK_VALUE) { // The item is successfully created in the user's library MediaItem createdItem = itemsResponse.getMediaItem(); } else { // The item could not be created. Check the status and try again } } } catch (ApiException e) { // Handle error }
PHP
try { $newMediaItems = []; // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName( $uploadToken, $itemDescription, $fileName); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems); foreach ($response->getNewMediaItemResults() as $itemResult) { $status = $itemResult->getStatus(); if ($status->getCode() != Code::OK) { // Error while creating the item. } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
คุณเพิ่มรายการสื่อลงในคลังเพลงและอัลบั้มได้โดยระบุอัลบั้ม id
ดูข้อมูลเพิ่มเติมได้ที่สร้างอัลบั้ม
แต่ละอัลบั้มมีรายการสื่อได้สูงสุด 20,000 รายการ คำขอสร้างรายการสื่อในอัลบั้มที่จะเกินขีดจำกัดนี้จะดำเนินการไม่สำเร็จ
REST
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create new media items in a specific album BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
นอกจากนี้ คุณยังระบุ 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" } }
Java
try { // Create new media items in a specific album, positioned after a media item AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum(); BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems, positionInAlbum); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId, 'albumPosition' => $albumPosition]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
ดูรายละเอียดเพิ่มเติมเกี่ยวกับการจัดวางตำแหน่งในอัลบั้มได้ที่เพิ่มคุณค่า
การตอบกลับการสร้างรายการ
การเรียก 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" } } ] }
Java
BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); // The response contains a list of NewMediaItemResults for (NewMediaItemResult result : response.getNewMediaItemResultsList()) { // Each result item is identified by its uploadToken String uploadToken = result.getUploadToken(); Status status = result.getStatus(); if (status.getCode() == Code.OK_VALUE) { // If the request is successful, a MediaItem is returned MediaItem mediaItem = result.getMediaItem(); String id = mediaItem.getId(); String productUrl = mediaItem.getProductUrl(); // ... } }
PHP
// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults foreach ($response->getNewMediaItemResults() as $itemResult) { // Each result item is identified by its uploadToken $itemUploadToken = $itemResult->getUploadToken(); // Verify the status of each entry to ensure that the item has been uploaded correctly $itemStatus = $itemResult->getStatus(); if ($itemStatus->getCode() != Code::OK) { // Error when item is being created } else { // Media item is successfully created // Get the MediaItem object from the response $mediaItem = $itemResult->getMediaItem(); // It contains details such as the Id of the item, productUrl $id = $mediaItem->getId(); $productUrl = $mediaItem->getProductUrl(); // ... } }
หากเพิ่มรายการสำเร็จ ระบบจะส่งคืน 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.
ทำขั้นตอนนี้ต่อไปจนกว่าการอัปโหลดและการเรียกใช้การสร้างสื่อทั้งหมดจะเสร็จสมบูรณ์