หลังจากเรียกใช้เพื่อ แสดงเนื้อหาในคลังภาพหรืออัลบั้ม แทนที่จะจัดเก็บรายการสื่อที่ส่งคืนมา แอปพลิเคชันของคุณควรจัดเก็บ รหัสของรายการสื่อไว้ เนื่องจากเนื้อหาของรายการสื่ออาจเปลี่ยนแปลง และ 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
ของรายการสื่อวิดีโอจะใช้งานไม่ได้จนกว่าระบบจะประมวลผลวิดีโอ
คำขอ GET มีดังนี้
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Beareroauth2-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 "
}
}
พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ
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
}
พร็อพเพอร์ตี้รูปภาพมีข้อมูลเมตาสำหรับรายการรูปภาพ
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
หากมีข้อผิดพลาด
จำนวนรายการสื่อสูงสุดที่คุณขอได้ในคอลเดียวคือ 50 รายการ รายการรายการสื่อต้องไม่มีตัวระบุที่ซ้ำกันและต้องไม่ว่างเปล่า
ต่อไปนี้คือคำขอ 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: Beareroauth2-token
คำขอ GET จะแสดงการตอบกลับต่อไปนี้
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id ",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id ",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
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
}
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 ฐานเข้ากับมิติข้อมูลที่ต้องการดังที่แสดงในตัวอย่าง ตัวอย่างเช่น
ตัวอย่างการแสดงรายการสื่อที่มีความกว้างไม่เกิน 2048 พิกเซลและสูงไม่เกิน 1,024 พิกเซล https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
คำอธิบาย พารามิเตอร์ครอบตัด หากต้องการครอบตัดรูปภาพให้มีความกว้างและความสูงที่ตรงกับขนาดที่คุณระบุ ให้ต่อ URL พื้นฐานกับพารามิเตอร์ ขนาด (เป็นพิกเซล) ควรอยู่ในช่วง [1, 16383] หากความกว้างหรือความสูงของรูปภาพเกินขนาดที่ขอ ระบบจะปรับขนาดรูปภาพให้เล็กลงและครอบตัด (โดยคงสัดส่วนภาพไว้) ตัวอย่างเช่น
ในตัวอย่างนี้ แอปพลิเคชันแสดงรายการสื่อที่มีความกว้าง 256 พิกเซลและสูง 256 พิกเซล เช่น ภาพขนาดย่อ https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
คำอธิบาย พารามิเตอร์ หากต้องการดาวน์โหลดรูปภาพโดยเก็บข้อมูลเมตา Exif ทั้งหมดไว้ ยกเว้นข้อมูลเมตาตำแหน่ง ให้ต่อ URL ฐานกับพารามิเตอร์ ตัวอย่างเช่น
ในตัวอย่างนี้ แอปพลิเคชันจะดาวน์โหลดรูปภาพที่มีข้อมูลเมตาทั้งหมด ยกเว้นข้อมูลเมตาตำแหน่ง https://lh3.googleusercontent.com/p/Az....XabC=d |
URL หลักของวิดีโอ
รายการตัวเลือกที่คุณใช้ได้กับ URL พื้นฐานของวิดีโอมีดังนี้
พารามิเตอร์ | |
---|---|
dv |
คำอธิบาย หากต้องการเข้าถึงไบต์ของวิดีโอ พารามิเตอร์ dv จะขอวิดีโอต้นฉบับเวอร์ชันที่แปลงรูปแบบไว้แล้วซึ่งมีคุณภาพสูง พารามิเตอร์ ใช้ร่วมกับพารามิเตอร์ w และ h ไม่ได้ URL พื้นฐานสำหรับการดาวน์โหลดวิดีโออาจใช้เวลา 2-3 วินาทีในการแสดงผลไบต์ ก่อนใช้พารามิเตอร์นี้ ให้ตรวจสอบว่าช่อง ตัวอย่างเช่น
ตัวอย่างต่อไปนี้แสดงวิธีดาวน์โหลดจำนวนไบต์ของวิดีโอ https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w , h , c และ d |
คำอธิบาย หากต้องการเข้าถึงภาพปกของวิดีโอ ให้ใช้พารามิเตอร์ URL พื้นฐานของรูปภาพ โดยค่าเริ่มต้น ภาพปกวิดีโอทั้งหมดจะมีปุ่มเล่นที่วางซ้อนอยู่ ดูพารามิเตอร์ -no เพื่อนำการวางซ้อนนี้ออก ตัวอย่างเช่น ดูตัวอย่างได้ที่ตาราง URL ฐานของรูปภาพ |
no |
คำอธิบาย พารามิเตอร์ หากต้องการเรียกข้อมูลภาพปกของวิดีโอโดยไม่มีปุ่มเล่นที่วางซ้อน ให้ต่อ URL พื้นฐานกับพารามิเตอร์ no ต้องใช้พารามิเตอร์ no กับพารามิเตอร์ URL ฐานของรูปภาพอย่างน้อย 1 รายการ ตัวอย่างเช่น
ตัวอย่างต่อไปนี้แสดงภาพขนาดย่อของวิดีโอที่มีความกว้าง 1280 พิกเซลและสูง 720 พิกเซลโดยไม่มีปุ่มเล่นวางซ้อน https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL พื้นฐานของรูปภาพเคลื่อนไหว
รูปภาพเคลื่อนไหวมีองค์ประกอบทั้งรูปภาพและวิดีโอ คุณใช้พารามิเตอร์จาก URL ฐานรูปภาพหรือ URL ฐานของวิดีโอสำหรับคำขอรูปภาพเคลื่อนไหว baseUrl
ได้
พารามิเตอร์ | |
---|---|
dv |
คำอธิบาย หากต้องการเรียกข้อมูลองค์ประกอบวิดีโอของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้พารามิเตอร์ |
w , h , c และ d |
คำอธิบาย หากต้องการเรียกข้อมูลองค์ประกอบรูปภาพของรายการสื่อรูปภาพเคลื่อนไหว ให้ใช้รูปแบบสำหรับ URL ฐานรูปภาพ |