หลังจากเรียกเพื่อแสดงเนื้อหาของคลังภาพหรืออัลบั้มแล้ว แอปพลิเคชันจะจัดเก็บรหัสของรายการสื่อแทนการจัดเก็บรายการสื่อที่ส่งคืน เนื่องจากเนื้อหาของรายการสื่ออาจมีการเปลี่ยนแปลงและหลังจากผ่านไประยะหนึ่ง URL ที่รวมอยู่ในการตอบกลับจะหมดอายุ รหัสรายการสื่อจะระบุรายการสื่อที่ไม่ซ้ํากัน เช่น รูปภาพหรือวิดีโอภายในคลังของผู้ใช้
โปรดทราบว่าแอปพลิเคชันไม่ควรแคชรูปภาพหรือวิดีโอของผู้ใช้ไว้เป็นระยะเวลานาน แต่จะจัดเก็บหรือแคชรหัสรายการสื่อได้นานเท่าที่จําเป็น ทั้งนี้ขึ้นอยู่กับกรณีการใช้งานของคุณ โปรดทราบว่าการเข้าถึงข้อมูลผู้ใช้จะอยู่ภายใต้ภาระหน้าที่ด้านความเป็นส่วนตัว
ขอบเขตการให้สิทธิ์ที่จําเป็น
หากต้องการเข้าถึงรายการสื่อ แอปจะต้องขอขอบเขตการให้สิทธิ์อย่างน้อย 1 ขอบเขต สิทธิ์เข้าถึงรายการสื่อที่ตอบกลับในการตอบกลับขึ้นอยู่กับขอบเขตที่คุณขอ
photoslibrary.readonly
อนุญาตให้เข้าถึงรายการสื่อทั้งหมดในไลบรารีของผู้ใช้photoslibrary.readonly.appcreateddata
อนุญาตการเข้าถึงรายการสื่อที่แอปสร้างขึ้นเท่านั้น
รายการสื่อ
A
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 px และสูงไม่เกิน 1024 px 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 ตัวอย่างต่อไปนี้แสดงภาพขนาดย่อของวิดีโอที่มีความกว้าง 1280 x ความสูง 720 พิกเซลพอดี และไม่รวมการวางซ้อนปุ่มเล่น https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL ของรูปภาพเคลื่อนไหว
รูปภาพเคลื่อนไหวมีทั้งองค์ประกอบรูปภาพและวิดีโอ คุณใช้พารามิเตอร์จาก URL ฐานรูปภาพหรือ URL ฐานวิดีโอสําหรับคําขอภาพเคลื่อนไหว baseUrl
ได้
พารามิเตอร์ | |
---|---|
dv |
คำอธิบาย หากต้องการเรียกองค์ประกอบวิดีโอของรายการสื่อภาพเคลื่อนไหว ให้ใช้พารามิเตอร์ |
w , h , c และ d |
คำอธิบาย หากต้องการเรียกข้อมูลองค์ประกอบรูปภาพของรายการสื่อที่มีการเคลื่อนไหว ให้ใช้รูปแบบ URL ของรูปภาพพื้นฐาน |