呼叫列出相片庫或相簿的內容後,應用程式應儲存媒體項目的 ID,而不是儲存傳回的媒體項目。這是因為媒體項目的內容可能會變更,且在一段時間後,回應中包含的網址會過期。媒體項目 ID 可明確識別媒體項目,例如使用者媒體庫中的相片或影片。
請注意,應用程式不應長時間快取使用者的相片或影片,但視用途而定,您可以儲存或快取媒體項目 ID,時間長度視需要而定。您也應注意,使用者資料的存取權受隱私權義務規範。
必要的授權範圍
如要存取媒體項目,應用程式必須至少要求以下其中一個授權範圍。您可以存取回應中傳回的媒體項目,取決於您要求的範圍。
photoslibrary.readonly
可存取使用者媒體庫中的所有媒體項目photoslibrary.readonly.appcreateddata
只允許存取由應用程式建立的媒體項目
媒體項目
mediaItem
是媒體的表示法,例如已上傳至 Google 相簿相片庫的相片或影片。這是頂層物件,其屬性可能會因基礎媒體類型而異。
下表列出 mediaItem
屬性:
屬性 | |
---|---|
id |
用於識別物件的永久固定 ID。 |
description |
Google 相簿中媒體項目的說明。 |
baseUrl |
用於存取原始位元組。詳情請參閱「Base URLs」。 |
productUrl |
Google 相簿內部圖片的連結。開發人員無法開啟這個連結,只有使用者可以開啟。網址會指向媒體庫中的媒體項目。如果網址是從相簿搜尋中擷取,則會指向相簿中的項目。 |
mimeType |
可輕鬆識別媒體類型的媒體項目類型,例如 image/jpg 。 |
filename |
媒體項目的檔案名稱,會在 Google 相簿應用程式中向使用者顯示 (在項目的資訊部分)。 |
mediaMetadata |
這會因媒體的基礎類型而異,例如 photo 或 video 。如要減少酬載,可以使用欄位遮罩。 |
contributorInfo |
只有在媒體項目位於由此應用程式建立的共用相簿中,且使用者已授予 包含新增此媒體項目的貢獻者相關資訊。詳情請參閱「分享媒體」。 |
取得媒體項目
如要擷取媒體項目,請使用 mediaItemId
呼叫 mediaItems.get。要求會傳回單一媒體項目。
mediaItem
包含 ID、說明和網址等屬性。photo
或 video
中的其他資訊,取決於檔案中的中繼資料。部分屬性可能不會顯示。ContributorInfo
包含共享相簿中項目的中繼資料。只有在列出共用相簿的內容時,才會納入這個欄位,且使用者必須已授予 photoslibrary.sharing
授權範圍。
如果媒體項目是影片,則必須先處理影片檔案。mediaItem
在 mediaMetadata
中包含 status
欄位,用來說明影片檔案的處理狀態。新上傳的檔案會先傳回 videoProcessingStatus
,值為 PROCESSING
,然後再 READY
供使用。影片必須先經過處理,才能使用影片媒體項目的 baseUrl
。
以下是 GET 要求:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Beareroauth2-token
相片媒體項目的回應如下所示。photo 屬性包含相片項目的中繼資料。
{
"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
}
取得多個媒體項目
如要依 ID 擷取多個媒體項目,請使用 mediaItemId
呼叫 mediaItems.batchGet
。
要求會依照要求中提供的媒體項目 ID 順序,傳回 MediaItemResults
清單。每個結果都包含 MediaItem
或 Status
(如果發生錯誤)。
一次呼叫中可要求的媒體項目數量上限為 50 個。媒體項目清單不得包含重複的 ID,也不能留空。
以下是 GET 要求,顯示媒體項目的存取成功和失敗情況。在要求中指定每個媒體項目 ID 做為新的 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
}
基礎網址
Google 相簿程式庫 API 中的基礎網址可讓您存取媒體項目的位元組。應用程式可使用各種基本網址,下載媒體項目或在應用程式中顯示媒體項目。基本網址是字串,會在您列出專輯或存取媒體項目時,納入回應中。有效時間為 60 分鐘,且需要額外參數,因為無法直接使用。
常見的網址如下:
baseUrl
:直接存取相片、影片縮圖或下載影片位元組。coverPhotoBaseUrl
:直接存取相簿的封面相片。profilePictureBaseUrl
:直接存取mediaItem
擁有者的個人資料相片。
圖片基準網址
以下是可搭配圖片基本網址使用的選項清單:
參數 | |
---|---|
w 、h |
說明 寬度 如要存取圖片媒體項目 (例如影片的相片或縮圖),您必須指定想要在應用程式中顯示的尺寸 (這樣圖片可以縮放為這些尺寸,同時保留長寬比)。如要這麼做,請將基準網址與所需尺寸連結,如範例所示。 例如:
以下範例說明如何顯示寬度不超過 2048 像素、高度不超過 1024 像素的媒體項目: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
說明 裁剪 如要將圖片裁剪為您指定的確切寬度和高度,請將基準網址與選用的 大小 (以像素為單位) 應介於 [1, 16383] 之間。如果圖片的寬度或高度超過要求的大小,圖片就會縮小並裁剪 (維持顯示比例)。 例如:
在這個範例中,應用程式會顯示寬度和高度皆為 256 像素的媒體項目,例如縮圖: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
說明 下載, 如果您想下載圖片,並保留位置中繼資料以外的所有 Exif 中繼資料,請將基準網址與 例如:
在這個範例中,應用程式會下載含有所有中繼資料的圖片,但不含位置中繼資料: https://lh3.googleusercontent.com/p/Az....XabC=d |
影片基準網址
以下是可搭配影片基本網址使用的選項清單:
參數 | |
---|---|
dv |
說明 如要存取影片 dv 參數會要求原始影片的高畫質轉碼版本。這個參數與 w 和 h 參數不相容。 影片下載的基本網址可能需要幾秒鐘的時間才能傳回位元組。 使用這個參數前,請確認媒體項目的 例如:
以下範例說明如何下載影片位元組: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w 、h 、c 和 d |
說明 如要存取影片縮圖,請使用任何圖片基準網址參數。 根據預設,所有影片縮圖都會附上播放按鈕的疊加層。查看 -no 參數即可移除這個疊加層。 例如: 如需範例,請參閱圖片基本網址表格。 |
no |
說明 移除縮圖覆蓋圖片, 如果您想擷取影片縮圖,但不顯示播放按鈕的疊加層,請將基本網址與 no 參數連結在一起。 no 參數必須搭配至少一個 圖片基本網址參數使用。 例如:
以下範例顯示的影片縮圖寬度和高度分別為 1280 像素和 720 像素,且不含播放按鈕疊加: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |