หลังจากเรียกใช้ รายการเนื้อหาของคลังภาพหรืออัลบั้ม แทนที่จะจัดเก็บรายการสื่อที่ส่งคืนแล้ว แอปพลิเคชันของคุณควรจัดเก็บ ID ของรายการสื่อไว้ เนื่องจากเนื้อหาของรายการสื่ออาจมีการเปลี่ยนแปลง และ URL ที่รวมอยู่ในการตอบกลับจะหมดอายุหลังจากผ่านไประยะหนึ่ง รหัสรายการสื่อจะระบุรายการสื่อโดยไม่ซ้ำกัน เช่น รูปภาพหรือวิดีโอในคลังภาพของผู้ใช้
โปรดทราบว่าแอปพลิเคชันไม่ควรแคชรูปภาพหรือวิดีโอของผู้ใช้เป็นเวลานาน แต่คุณอาจจัดเก็บหรือแคชรหัสรายการสื่อไว้เท่าที่จำเป็นได้ ทั้งนี้ขึ้นอยู่กับกรณีการใช้งานของคุณ และโปรดทราบด้วยว่าการเข้าถึงข้อมูลผู้ใช้อยู่ในบังคับของภาระหน้าที่ด้านความเป็นส่วนตัว
ขอบเขตการให้สิทธิ์ที่จำเป็น
หากต้องการเข้าถึงรายการสื่อ แอปของคุณต้องขอขอบเขตการให้สิทธิ์ต่อไปนี้อย่างน้อย 1 รายการ การเข้าถึงรายการสื่อที่แสดงในคำตอบจะขึ้นอยู่กับขอบเขตที่คุณขอ
photoslibrary.readonly
อนุญาตให้เข้าถึงรายการสื่อทั้งหมดในไลบรารีของผู้ใช้photoslibrary.readonly.appcreateddata
อนุญาตให้เข้าถึงเฉพาะรายการสื่อที่แอปสร้างขึ้น
รายการสื่อ
mediaItem
คือการนำเสนอสื่อต่างๆ เช่น รูปภาพหรือวิดีโอที่ได้รับอัปโหลดไปยังคลังภาพ Google Photos ออบเจ็กต์นี้เป็นออบเจ็กต์ระดับบนสุดและพร็อพเพอร์ตี้อาจแตกต่างกันไปตามประเภทสื่อที่ใช้งานอยู่
ตารางต่อไปนี้แสดงพร็อพเพอร์ตี้ mediaItem
พร็อพเพอร์ตี้ | |
---|---|
id |
รหัสถาวรที่เสถียรซึ่งใช้ในการระบุออบเจ็กต์ |
description |
คำอธิบายของรายการสื่อตามที่เห็นใน Google Photos |
baseUrl |
ใช้เพื่อเข้าถึงไบต์ดิบ ดูข้อมูลเพิ่มเติมได้ที่ URL ฐาน |
productUrl |
ลิงก์ไปยังรูปภาพใน Google Photos นักพัฒนาแอปจะเปิดลิงก์นี้ไม่ได้ เฉพาะผู้ใช้เท่านั้น URL ที่ชี้ไปยังรายการสื่อในไลบรารี หาก URL ดึงข้อมูลมาจากการค้นหาอัลบั้ม URL จะชี้ไปยังรายการภายในอัลบั้ม |
mimeType |
ประเภทของรายการสื่อเพื่อช่วยให้ระบุประเภทของสื่อได้อย่างง่ายดาย (เช่น image/jpg ) |
filename |
ชื่อไฟล์ของรายการสื่อที่แสดงต่อผู้ใช้ในแอป Google Photos (ในส่วนข้อมูลของรายการ) |
mediaMetadata |
แตกต่างกันไปตามประเภทสื่อที่สำคัญ เช่น photo หรือ video
ใช้มาสก์ฟิลด์เพื่อลดเพย์โหลดได้
|
contributorInfo |
ช่องนี้จะมีการป้อนข้อมูลก็ต่อเมื่อรายการสื่ออยู่ในอัลบั้มที่แชร์
ที่แอปนี้สร้างขึ้น และผู้ใช้ได้ให้สิทธิ์
ขอบเขต มีข้อมูลเกี่ยวกับผู้มีส่วนร่วมที่เพิ่มรายการสื่อนี้ โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อแชร์สื่อ |
รับรายการสื่อ
หากต้องการเรียกรายการสื่อ ให้เรียกใช้ mediaItems.get โดยใช้ mediaItemId
คำขอแสดงรายการสื่อรายการเดียว
mediaItem
มีพร็อพเพอร์ตี้ เช่น รหัส คำอธิบาย และ URL ข้อมูลเพิ่มเติมภายใน photo
หรือ video
อิงตามข้อมูลเมตาภายในไฟล์ อาจไม่มีพร็อพเพอร์ตี้บางรายการ ContributorInfo
มีข้อมูลเมตาสำหรับรายการที่เป็นส่วนหนึ่งของอัลบั้มที่แชร์ ช่องนี้จะมีไว้เฉพาะในกรณีที่แสดงเนื้อหาของอัลบั้มที่แชร์ซึ่งผู้ใช้อนุญาตphotoslibrary.sharing
ขอบเขตการให้สิทธิ์
หากรายการสื่อเป็นวิดีโอ จะต้องประมวลผลไฟล์วิดีโอก่อน ช่อง mediaItem
มีช่อง status
ภายใน mediaMetadata
ซึ่งอธิบายสถานะการประมวลผลของไฟล์วิดีโอ ไฟล์ที่อัปโหลดใหม่จะแสดงค่า videoProcessingStatus
ที่มีค่า PROCESSING
ก่อน READY
สำหรับการใช้งาน baseUrl
ของรายการสื่อวิดีโอจะไม่พร้อมใช้งานจนกว่าระบบจะประมวลผลวิดีโอเสร็จสิ้น
REST
นี่คือคำขอ GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
การตอบกลับรายการสื่อรูปภาพจะมีลักษณะดังนี้ พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ
{ "id": "media-item-id", "description": "item-description", "productUrl": "url-to-open-in-google-photos", "baseUrl": "base-url_do-not-use-directly", "mimeType": "mime-type-of-media", "filename": "item-filename", "mediaMetadata": { "width": "media-item-width", "height": "media-item-height", "creationTime": "media-item-creation-time", "photo": { "cameraMake": "make-of-the-camera", "cameraModel": "model-of-the-camera", "focalLength": "focal-length-of-the-camera-lens", "apertureFNumber": "aperture-f-number-of-the-camera-lens", "isoEquivalent": "iso-of-the-camera", "exposureTime": "exposure-time-of-the-camera-aperture" } }, "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly", "displayName": "name-of-user" } }
การตอบสนองสำหรับรายการสื่อวิดีโอจะมีลักษณะเช่นนี้ พร็อพเพอร์ตี้วิดีโอมีข้อมูลเมตาสำหรับรายการวิดีโอ
{ "id": "media-item-id", "description": "item-description", "productUrl": "url-to-open-in-google-photos", "baseUrl": "base-url_do-not-use-directly", "mimeType": "mime-type-of-media", "filename": "item-filename", "mediaMetadata": { "width": "media-item-width", "height": "media-item-height", "creationTime": "media-item-creation-time", "video": { "cameraMake": "make-of-the-camera", "cameraModel": "model-of-the-camera", "fps": "frame-rate-of-the-video", "status": "READY" }, }, "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly", "displayName": "name-of-user" } }
Java
พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasPhoto()) { // This media item is a photo and has additional photo metadata Photo photoMetadata = metadata.getPhoto(); String cameraMake = photoMetadata.getCameraMake(); String cameraModel = photoMetadata.getCameraModel(); float aperture = photoMetadata.getApertureFNumber(); int isoEquivalent = photoMetadata.getIsoEquivalent(); // ... } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
พร็อพเพอร์ตี้วิดีโอมีข้อมูลเมตาสำหรับรายการวิดีโอ
try { // Get a media item using its ID String mediaItemId = "..."; MediaItem item = photosLibraryClient.getMediaItem(mediaItemId); // Get some properties from the retrieved media item String id = item.getId(); String description = item.getDescription(); String baseUrl = item.getBaseUrl(); String productUrl = item.getProductUrl(); // ... if (item.hasMediaMetadata()) { // The media item contains additional metadata, such as the height and width MediaMetadata metadata = item.getMediaMetadata(); long height = metadata.getHeight(); long width = metadata.getWidth(); Timestamp creationTime = metadata.getCreationTime(); // ... if (metadata.hasVideo()) { // This media item is a video and has additional video metadata Video videoMetadata = metadata.getVideo(); VideoProcessingStatus status = videoMetadata.getStatus(); if (status.equals(VideoProcessingStatus.READY)) { // This video media item has been processed String cameraMake = videoMetadata.getCameraMake(); String cameraModel = videoMetadata.getCameraModel(); double fps = videoMetadata.getFps(); // ... } } } if (item.hasContributorInfo()) { // A user has contributed this media item to a shared album ContributorInfo contributorInfo = item.getContributorInfo(); String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl(); String displayName = contributorInfo.getDisplayName(); } } catch (ApiException e) { // Handle error }
PHP
พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $photoMetadata = $metadata->getPhoto(); if (!is_null($photoMetadata)) { // This media item is a photo and has additional photo metadata $cameraMake = $photoMetadata->getCameraMake(); $cameraModel = $photoMetadata->getCameraModel(); $aperture = $photoMetadata->getApertureFNumber(); $isoEquivalent = $photoMetadata->getIsoEquivalent(); // ... } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
พร็อพเพอร์ตี้วิดีโอมีข้อมูลเมตาสำหรับรายการวิดีโอ
try { // Get a media item using its ID $mediaItemId = "..."; $item = $photosLibraryClient->getMediaItem($mediaItemId); // Get some properties from the retrieved media item $id = $item->getId(); $description = $item->getDescription(); $baseUrl = $item->getBaseUrl(); $productUrl = $item->getProductUrl(); // ... $metadata = $item->getMediaMetadata(); if (!is_null($metadata)) { // The media item contains additional metadata, such as the height and width $height = $metadata->getHeight(); $width = $metadata->getWidth(); $creationTime = $metadata->getCreationTime(); // ... $videoMetadata = $metadata->getVideo(); if (!is_null($videoMetadata)) { // This media item is a video and has additional video metadata if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) { // This video media item has been processed $cameraMake = $videoMetadata->getCameraMake(); $cameraModel = $videoMetadata->getCameraModel(); $fps = $videoMetadata->getFps(); // ... } } } $contributorInfo = $item->getContributorInfo(); if (!is_null($contributorInfo)) { // A user has contributed this media item to a shared album $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl(); $displayName = $contributorInfo->getDisplayName(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
รับรายการสื่อหลายรายการ
หากต้องการเรียกรายการสื่อหลายรายการด้วยตัวระบุ ให้เรียกใช้ mediaItems.batchGet
โดยใช้ mediaItemId
คำขอจะแสดงรายการ MediaItemResults
ตามลำดับตัวระบุรายการสื่อที่ให้ไว้ในคำขอ ผลลัพธ์แต่ละรายการจะมี MediaItem
หรือ Status
หากมีข้อผิดพลาด
จำนวนรายการสื่อสูงสุดที่คุณสามารถขอต่อการเรียก 1 ครั้งคือ 50 รายการ ชุดรายการสื่อต้องไม่มีตัวระบุที่ซ้ำกันและต้องไม่ว่างเปล่า
REST
นี่คือคำขอ GET ที่แสดงให้เห็นการเข้าถึงรายการสื่อทั้งที่สำเร็จและไม่สำเร็จ ระบุตัวระบุรายการสื่อแต่ละรายการเป็นพารามิเตอร์การค้นหา mediaItemIds
ใหม่เป็นส่วนหนึ่งของคําขอ
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
คำขอ GET แสดงการตอบกลับต่อไปนี้
{ "mediaItemResults": [ { "mediaItem": { "id": "media-item-id", ... } }, { "mediaItem": { "id": "another-media-item-id", ... } }, { "status": { "code": 3, "message": "Invalid media item ID." } } ] }
Java
try { // List of media item IDs to retrieve List<String> mediaItemIds = Arrays .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"); // Get a list of media items using their IDs BatchGetMediaItemsResponse response = photosLibraryClient .batchGetMediaItems(mediaItemIds); // Loop over each result for (MediaItemResult result : response.getMediaItemResultsList()) { // Each MediaItemresult contains a status and a media item if (result.hasMediaItem()) { // The media item was successfully retrieved, get some properties MediaItem item = result.getMediaItem(); String id = item.getId(); // ... } else { // If the media item is not set, an error occurred and the item could not be loaded // Check the status and handle the error Status status = result.getStatus(); // ... } } } catch (ApiException e) { // Handle error }
PHP
try { // List of media item IDs to retrieve $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"]; // Get a list of media items using their IDs $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds); // Loop over each result foreach ($response->getMediaItemResults() as $itemResult) { // Each MediaItemresult contains a status and a media item $mediaItem = $itemResult->getMediaItem(); if(!is_null($mediaItem)){ // The media item was successfully retrieved, get some properties $id = $mediaItem->getId(); // ... } else { // If the media item is null, an error occurred and the item could not be loaded } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
URL ฐาน
URL ฐานภายใน Google Photos Library API ช่วยให้คุณเข้าถึงไบต์ของรายการสื่อได้ การใช้ URL ฐานที่หลากหลายช่วยให้แอปดาวน์โหลดรายการสื่อหรือแสดงรายการสื่อภายในแอปได้ โดย URL หลักคือสตริงที่รวมอยู่ในการตอบกลับเมื่อคุณแสดงรายการอัลบั้มหรือเข้าถึงรายการสื่อ พารามิเตอร์เหล่านี้ใช้ได้เป็นเวลา 60 นาทีและต้องมีพารามิเตอร์เพิ่มเติมเนื่องจากไม่มีการใช้งานตามที่เป็นอยู่
URL ฐานต่างๆ ได้แก่
baseUrl
: เข้าถึงรูปภาพ ภาพขนาดย่อสำหรับวิดีโอโดยตรง หรือดาวน์โหลดไบต์ของวิดีโอcoverPhotoBaseUrl
: เข้าถึงรูปภาพปกของอัลบั้มโดยตรงprofilePictureBaseUrl
: เข้าถึงรูปโปรไฟล์ของเจ้าของmediaItem
โดยตรง
URL ฐานของรูปภาพ
รายการตัวเลือกที่คุณใช้กับ URL ฐานรูปภาพได้มีดังนี้
พารามิเตอร์ | |
---|---|
w h |
คำอธิบาย ความกว้าง หากต้องการเข้าถึงรายการสื่อรูปภาพ เช่น รูปภาพหรือภาพขนาดย่อของวิดีโอ คุณต้องระบุขนาดที่คุณวางแผนจะแสดงในแอปพลิเคชัน (เพื่อให้ปรับขนาดรูปภาพเป็นขนาดเหล่านี้ได้ในขณะที่รักษาสัดส่วนภาพไว้) โดยเชื่อม URL ฐานเข้ากับมิติข้อมูลที่จำเป็นดังที่แสดงในตัวอย่าง ตัวอย่างเช่น base-url=wmax-width-hmax-height ตัวอย่างจะแสดงรายการสื่อที่มีขนาดไม่เกิน 2048 พิกเซลและไม่เกิน 1,024 พิกเซล https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
คำอธิบาย การครอบตัดพารามิเตอร์ หากต้องการครอบตัดรูปภาพตามขนาดความกว้างและความสูงพอดีที่ระบุไว้ ให้เชื่อม URL ฐานด้วยพารามิเตอร์ ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากมีความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ ระบบจะปรับขนาดรูปภาพลงและครอบตัด (รักษาสัดส่วนภาพไว้) ตัวอย่างเช่น base-url=wmax-width-hmax-height-c ในตัวอย่างนี้ แอปพลิเคชันจะแสดงรายการสื่อที่มีความกว้าง 256 พิกเซล x สูง 256 พิกเซลพอดี เช่น ภาพขนาดย่อ https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
คำอธิบาย การดาวน์โหลด พารามิเตอร์ หากต้องการดาวน์โหลดรูปภาพที่เก็บข้อมูลเมตา Exif ทั้งหมดไว้ ยกเว้นข้อมูลเมตาของตำแหน่ง ให้เชื่อมต่อ URL ฐานกับพารามิเตอร์ ตัวอย่างเช่น base-url=d ในตัวอย่างนี้ แอปพลิเคชันจะดาวน์โหลดรูปภาพที่มีข้อมูลเมตาทั้งหมด ยกเว้นข้อมูลเมตาตำแหน่ง https://lh3.googleusercontent.com/p/Az....XabC=d |
URL ฐานของวิดีโอ
รายการตัวเลือกที่คุณใช้กับ URL ฐานของวิดีโอได้มีดังนี้
พารามิเตอร์ | |
---|---|
dv |
คำอธิบาย หากต้องการเข้าถึงไบต์ของวิดีโอ พารามิเตอร์ dv จะขอวิดีโอต้นฉบับที่แปลงและมีคุณภาพสูง พารามิเตอร์นี้ใช้งานร่วมกับพารามิเตอร์ w และ h ไม่ได้ URL ฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลาถึง 2-3 วินาทีในการแสดงไบต์ ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าช่อง ตัวอย่างเช่น base-url=dv ตัวอย่างต่อไปนี้แสดงวิธีดาวน์โหลดไบต์ของวิดีโอ https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c และ d |
คำอธิบาย หากต้องการเข้าถึงภาพขนาดย่อของวิดีโอ ให้ใช้พารามิเตอร์ URL ฐานของรูปภาพ โดยค่าเริ่มต้น ภาพขนาดย่อของวิดีโอทั้งหมดจะมีการวางซ้อนปุ่มเล่น ดูพารามิเตอร์ -no เพื่อนำการวางซ้อนนี้ออก ตัวอย่างเช่น ดูตัวอย่างได้ที่ตาราง URL ฐานของรูปภาพ |
no |
คำอธิบาย นำการวางซ้อนภาพขนาดย่อออก พารามิเตอร์ หากต้องการดึงข้อมูลภาพขนาดย่อของวิดีโอโดยไม่มีปุ่มเล่นวางซ้อน ให้เชื่อมต่อ URL ฐานกับพารามิเตอร์ no คุณต้องใช้พารามิเตอร์ no กับพารามิเตอร์ URL พื้นฐานของรูปภาพอย่างน้อย 1 รายการ ตัวอย่างเช่น base-url=wmax-width-hmax-height-no ตัวอย่างต่อไปนี้แสดงภาพขนาดย่อของวิดีโอที่มีความกว้าง 1,280 พิกเซล x สูง 720 พิกเซลพอดีและไม่รวมการวางซ้อนปุ่มเล่น https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL ฐานของภาพเคลื่อนไหว
รูปภาพเคลื่อนไหวจะมีทั้งองค์ประกอบรูปภาพและวิดีโอ คุณใช้พารามิเตอร์จาก URL ฐานของรูปภาพหรือ URL ฐานของวิดีโอสำหรับคำขอ baseUrl
รูปภาพเคลื่อนไหวได้
พารามิเตอร์ | |
---|---|
dv |
คำอธิบาย หากต้องการเรียกองค์ประกอบวิดีโอของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้พารามิเตอร์ |
w , h , c และ d |
คำอธิบาย หากต้องการเรียกองค์ประกอบรูปภาพของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้รูปแบบสำหรับ URL ฐานของรูปภาพ |