หลังจากโทรหา ระบุเนื้อหาของคลังภาพหรืออัลบั้ม แทนที่จะจัดเก็บรายการสื่อที่ส่งคืน แอปพลิเคชันของคุณควรจัดเก็บ รหัสของรายการสื่อ เนื่องจากเนื้อหาของรายการสื่ออาจ และหลังจากผ่านไประยะหนึ่ง URL ที่รวมอยู่ในการตอบกลับจะหมดอายุ รหัสรายการสื่อจะระบุรายการสื่อโดยไม่ซ้ำกัน เช่น รูปภาพหรือวิดีโอ ภายในไลบรารีของผู้ใช้
โปรดทราบว่าแอปพลิเคชันของคุณไม่ควรแคชรูปภาพหรือวิดีโอของผู้ใช้เป็นเวลานาน ระยะเวลา แต่ขึ้นอยู่กับกรณีการใช้งานของคุณ คุณสามารถจัดเก็บหรือ แคชรหัสรายการสื่อสำหรับ ยาวเท่ากับ (จำเป็น) นอกจากนี้คุณควรทราบว่าการเข้าถึง user ข้อมูลอยู่ในบังคับของความเป็นส่วนตัว และข้อผูกพันเพิ่มเติมดังต่อไปนี้
ขอบเขตการให้สิทธิ์ที่จำเป็น
หากต้องการเข้าถึงรายการสื่อ แอปของคุณต้องขอรายการต่อไปนี้อย่างน้อย 1 รายการ ขอบเขตการให้สิทธิ์ สิทธิ์เข้าถึงรายการสื่อที่แสดงในการตอบกลับจะขึ้นอยู่กับขอบเขตที่คุณ ได้ส่งคำขอ
photoslibrary.readonly
อนุญาตให้เข้าถึงรายการสื่อทั้งหมดใน คลังphotoslibrary.readonly.appcreateddata
อนุญาตให้เข้าถึงเฉพาะรายการสื่อที่ สร้างโดยแอป
รายการสื่อ
ต
mediaItem
คือการนำเสนอสื่อ เช่น รูปภาพหรือวิดีโอ ที่อัปโหลดไปยัง
คลังภาพ Google Photos เป็นออบเจ็กต์ระดับบนสุดและพร็อพเพอร์ตี้ของออบเจ็กต์สามารถ
จะแตกต่างกันไปตามประเภทสื่อ
ตารางต่อไปนี้แสดงพร็อพเพอร์ตี้ mediaItem
พร็อพเพอร์ตี้ | |
---|---|
id |
รหัสแบบถาวรและคงที่ที่ใช้เพื่อระบุออบเจ็กต์ |
description |
คำอธิบายรายการสื่อตามที่เห็นด้านใน Google Photos |
baseUrl |
ใช้เพื่อเข้าถึงไบต์ดิบ สำหรับข้อมูลเพิ่มเติม โปรดดูที่ URL หลัก |
productUrl |
ลิงก์ไปยังรูปภาพใน Google Photos ลิงก์นี้ไม่สามารถ เปิดโดยนักพัฒนาซอฟต์แวร์ โดยผู้ใช้เท่านั้น 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 พิกเซล แต่ไม่เกิน 1024 พิกเซล https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
คำอธิบาย การครอบตัด พารามิเตอร์ ถ้าคุณต้องการครอบตัดภาพให้มีความกว้างและความสูงที่แน่นอน
ให้เชื่อม URL พื้นฐานด้วยแอตทริบิวต์
พารามิเตอร์ ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากมี ความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ รูปภาพถูกลดขนาดลงและครอบตัด (คงสัดส่วนภาพไว้) ตัวอย่างเช่น base-url=wmax-width-hmax-height-c ในตัวอย่างนี้ แอปพลิเคชันจะแสดงรายการสื่อที่ กว้าง 256 พิกเซล สูง 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 วินาทีในการ ไบต์ที่แสดงผล ค่าเริ่มต้นของการดาวน์โหลดวิดีโอจะใช้การเข้ารหัส H.264 หากเข้ารหัส H.264 ไม่สำเร็จ ระบบจะใช้ VP9 ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่ารายการสื่อ
ช่อง ตัวอย่างเช่น base-url=dv ตัวอย่างต่อไปนี้แสดงวิธีดาวน์โหลดไบต์ของ วิดีโอ: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c และ
d |
คำอธิบาย หากต้องการเข้าถึงภาพขนาดย่อของวิดีโอ ให้ใช้พารามิเตอร์ URL ที่เป็นฐานของรูปภาพ โดยค่าเริ่มต้น ภาพขนาดย่อของวิดีโอทั้งหมดจะมีการวางซ้อนการเล่น ดูพารามิเตอร์ -no เพื่อนำการวางซ้อนนี้ออก ตัวอย่างเช่น โปรดดูตาราง URL ฐานของรูปภาพ เพื่อดูตัวอย่าง |
no |
คำอธิบาย การนำการวางซ้อนภาพขนาดย่อออก พารามิเตอร์ ถ้าคุณต้องการเรียกภาพขนาดย่อของวิดีโอโดยไม่มีการวางซ้อน ของปุ่มเล่น ให้เชื่อมต่อ URL พื้นฐานด้วยเครื่องหมาย no พารามิเตอร์ ต้องใช้พารามิเตอร์ no กับ เวลา พารามิเตอร์ URL ฐานของรูปภาพ ตัวอย่างเช่น 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 ฐานรูปภาพ |