撥打給 列出相片庫或相簿的內容, 應用程式應儲存 媒體項目的 ID。這是因為媒體項目的內容 時間過後,回應中所含網址就會失效。 媒體項目 ID 可用於識別相片或影片等媒體項目 在使用者介面中
請注意,您的應用程式不應快取使用者相片或影片的時間過長 根據您的用途,您可以儲存或 快取做為媒體項目編號 長 。 您也應該注意,user 資料受隱私權規範 義務。
必要的授權範圍
如要存取媒體項目,應用程式必須至少要求下列其中一項 授權範圍。 回應中傳回的媒體項目存取權取決於您的範圍 。
photoslibrary.readonly
會允許存取使用者 程式庫photoslibrary.readonly.appcreateddata
僅允許存取符合以下條件的媒體項目: 是由應用程式建立
媒體項目
A 罩杯
mediaItem
敬上
代表的媒體,例如上傳到 YouTube 的相片或影片
顯示在 Google 相簿相片庫中這是一個頂層物件,其屬性可以
會因基礎媒體類型而異
下表列出 mediaItem
屬性:
屬性 | |
---|---|
id |
用來識別物件的永久固定 ID。 |
description |
顯示於媒體項目的說明 Google 相簿 |
baseUrl |
用於存取原始位元組。詳情請參閱「基準網址」。 |
productUrl |
Google 相簿內部圖片的連結。這個連結不可 僅由開發人員開啟。網址指向以下中的媒體項目: 程式庫。如果是從相簿搜尋擷取的網址, 指向相簿中的項目。 |
mimeType |
可輕鬆識別媒體類型的媒體項目類型
(例如:image/jpg )。 |
filename |
在 Google 相簿向使用者顯示的媒體項目檔案名稱 。 |
mediaMetadata |
因媒體的基礎類型而異,例如 photo
或 video 。
如要減少酬載,可以使用欄位遮罩。
|
contributorInfo |
這個欄位只有在媒體項目位於共享相簿中時才會填入資料
,且使用者已授予
包含加入這個媒體的著作人相關資訊 項目。詳情請參閱「分享媒體」。 |
取得媒體項目
如要擷取媒體項目,請呼叫
mediaItems.get (使用
mediaItemId
。該要求會傳回單一媒體項目。
mediaItem
包含 ID、說明和網址等屬性。
photo
或 video
的其他資訊則是根據
檔案。可能不會顯示所有屬性。ContributorInfo
包含中繼資料
。這個欄位只有在
列出內容
使用者已授予 photoslibrary.sharing
的共享相簿
授權範圍。
如果媒體項目是影片,則必須先處理影片檔案。
mediaItem
在 mediaMetadata
中包含一個 status
欄位,用來說明
影片檔案的處理狀態最新上傳的檔案會傳回
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 }
取得多個媒體項目
如要依 ID 擷取多個媒體項目,請呼叫
mediaItems.batchGet
敬上
使用 mediaItemId
。
這個要求會傳回
MediaItemResults
敬上
按照請求中提供的媒體項目 ID 順序排列。每筆結果
包含 MediaItem
如果發生錯誤,則會傳回 Status
。
單次呼叫中可要求的媒體項目數量上限為 50 個。請注意, 媒體項目不得包含重複的 ID,亦不得留空。
REST
以下的 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: 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 }
基礎網址
Google Photos Library API 中的基本網址可讓你存取媒體位元組 項目。應用程式可以使用各種基準網址,下載媒體項目 或在應用程式內顯示媒體項目。「基礎網址」是 附加在回應中。這些 效期為 60 分鐘,且需要額外的參數,因為無法將 不過,無論內部 IP 位址為何 DNS 名稱始終會指向特定的執行個體
常見的網址如下:
baseUrl
:直接存取相片、影片縮圖或下載影片位元組。coverPhotoBaseUrl
:直接存取相簿的封面相片。profilePictureBaseUrl
:直接存取mediaItem
。
映像檔基本網址
以下是可與映像檔基本網址搭配使用的選項清單:
參數 | |
---|---|
w 、h |
說明 寬度、 如要存取圖片媒體項目,例如 則您必須指定要在影片廣告中顯示的尺寸 以便可以將圖片縮放為這些元件 同時保留長寬比)。方法如下 將基準網址連結至所需尺寸,如下所示: 範例。 例如: base-url=wmax-width-hmax-height 以下範例說明如何顯示寬度為 2048 像素且不大於 1024 像素: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
說明 裁剪, 如果您希望將圖片裁剪為確切的寬度和高度
將基準網址和
自選 大小 (以像素為單位) 應在 [1, 16383] 範圍內。如果有 圖片的寬度或高度,超過要求的大小, 縮小並裁剪圖片 (維持長寬比)。 例如: base-url=wmax-width-hmax-height-c 在這個範例中,應用程式會顯示 正好為寬 256 像素、256 像素高,例如 縮圖: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
說明 下載的 如果您想要下載保留所有 Exif 中繼資料的映像檔
除了位置中繼資料以外,請將基準網址和
例如: base-url=d 在此範例中,應用程式會下載映像檔 ,但位置中繼資料除外: https://lh3.googleusercontent.com/p/Az....XabC=d |
影片基礎網址
以下清單可搭配影片基礎網址使用:
參數 | |
---|---|
dv |
說明 如要存取影片 dv 參數請求的是高品質。 原始影片的轉碼版本。參數不是 與 w 和 h 相容 參數。 影片下載的基本網址可能需要幾秒鐘才能完成 傳回位元組。下載影片時,預設使用 H.264 編碼。如果 H.264 編碼失敗,系統會使用 VP9。 使用這個參數前,請檢查媒體項目的
例如: base-url=dv 以下範例說明如何下載 影片: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w 、h 、c 和
d |
說明 如要查看影片縮圖,請使用任一圖片基本網址參數。 根據預設,所有影片縮圖都會重疊在影片播放中 按鈕。查看 -no 參數即可移除這個疊加層。 例如: 請參閱圖片基本網址表格 。 |
no |
說明 移除縮圖疊加層 如果您希望擷取沒有重疊畫面的影片縮圖 (播放按鈕),使用 no 串連基準網址 參數。 no 參數必須至少與下列其中一項 這個 圖片基本網址參數。 例如: base-url=wmax-width-hmax-height-no 以下範例顯示的影片縮圖,寬度正好為 1280 px x 720 px,且不含播放按鈕重疊: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
動態相片基本網址
動態相片同時包含相片和影片元素。您可以使用
映像檔基本網址或
動態相片 baseUrl
要求的影片基本網址。
參數 | |
---|---|
dv |
說明 如要擷取動態相片媒體項目的影片元素,請使用
|
w 、h 、c 和
d |
說明 如要擷取動態相片媒體項目的相片元素,請使用 圖片基本網址的格式。 |