列出及擷取媒體項目

使用者設定環境裝置並在 Google 相簿中選取媒體來源後，應用程式就能列出並擷取這些媒體項目來顯示。

事前準備

  • 檢查裝置設定：確認您已為使用者成功建立並設定裝置。
  • 瞭解 Ambient API 流程：請詳閱 Ambient API 流程，瞭解整體程序，尤其是涉及輪詢 mediaSourcesSet 的步驟。

mediaSourcesSet 的意見調查

您必須先讓使用者在 Google 相簿應用程式中選取要與應用程式分享的相片，才能為裝置列出媒體項目。您的應用程式必須輪詢裝置，以判斷何時完成此選取作業。

定期呼叫特定 deviceId 的 devices.get 方法。監控 AmbientDevice 回應中的 mediaSourcesSet 欄位。一開始會是 false。使用者成功選取媒體來源後，這個欄位就會變更為 true。

AmbientDevice 回應包含 pollingConfig，其中包含 pollInterval，您應將其做為輪詢頻率的規範。

列出媒體項目

mediaSourcesSet 為裝置的 true 後，您就可以開始擷取使用者選取的媒體項目。

  1. 使用 mediaItems.list 端點：向 https://photosambient.googleapis.com/v1/mediaItems 提出 GET 要求，並在路徑中提供 deviceId。

  2. 處理分頁 (如有必要)：回應可能會分頁。使用 pageSize 參數指定傳回的項目數量上限，以及先前回應中的 pageToken，藉此擷取後續的結果頁面。

  3. 處理媒體項目：回應會包含 AmbientMediaItem 物件的陣列，每個物件都代表所選的媒體項目。這些物件包含以下重要詳細資料：

    • id：媒體項目的專屬 ID。
    • creationTime：建立媒體項目的時間戳記。
    • mediaFile：包含存取實際內容的詳細資料的物件。

mediaFile 欄位包含 baseUrl。您會使用這個 baseUrl 建構網址，以便以各種解析度或格式存取媒體項目的內容。

基礎網址

Google 相簿 API 中的基本網址可提供媒體項目的原始位元組存取權，讓應用程式下載或顯示這些項目。列出專輯 (Library API) 或存取媒體項目 (Library 和 Picker API) 時，這些網址會包含在回應中。請注意，基礎網址需要額外參數才能正常運作。

Picker API：

所有 PickedMediaItem.mediaFile 物件都包含 baseUrl。

基本網址會保持有效 60 分鐘，但如果使用者透過 Google 帳戶設定撤銷應用程式的權限，則可能會提早失效。

Library API：

基礎網址會在 60 分鐘內保持有效。

各種基礎網址如下：

  • baseUrl：直接存取相片、影片縮圖或下載影片位元組。
  • coverPhotoBaseUrl：直接存取相簿的封面相片。
  • profilePictureBaseUrl：直接存取 mediaItem 擁有者的個人資料相片。

圖片基準網址

以下是可搭配圖片基本網址使用的選項清單：

參數
w、h

說明

寬度 w 和高度 h 參數。

如要存取圖片媒體項目 (例如相片或影片縮圖)，您必須指定要在應用程式中顯示的尺寸 (這樣圖片就能縮放至這些尺寸，同時保留顯示比例)。如要這麼做，請將基準網址與所需尺寸連結，如範例所示。

範例：

base-url=wmax-width-hmax-height

以下範例顯示的媒體項目寬度不超過 2048 像素，高度不超過 1024 像素：

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

說明

裁剪 c 參數。

如要將圖片裁剪為指定的確切寬度和高度，請將基準網址與選用 -c 參數連結，並加上必要的 w 和 h 參數。

大小 (以像素為單位) 應介於 [1, 16383] 之間。如果圖片的寬度或高度超過要求的大小，系統會縮小圖片並裁剪 (保留顯示比例)。

範例：

base-url=wmax-width-hmax-height-c

在這個範例中，應用程式會顯示寬度和高度皆為 256 像素的媒體項目，例如縮圖：

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

說明

下載，d 參數。

如果您想下載圖片，並保留位置中繼資料以外的所有 Exif 中繼資料，請將基準網址與 d 參數連結。

範例：

base-url=d

在這個範例中，應用程式會下載含有所有中繼資料的圖片，但不含位置中繼資料：

https://lh3.googleusercontent.com/p/Az....XabC=d

影片基準網址

以下是可搭配影片基本網址使用的選項清單：

參數
dv

說明

如要存取影片 mediaItem 的位元組，請將 baseUrl 與下載影片 dv 參數連結。

dv 參數會要求原始影片的高品質轉碼版本。這個參數與 w 和 h 參數不相容。

影片下載的基本網址可能需要幾秒鐘的時間才能傳回位元組。

使用這個參數前，請確認媒體項目的 mediaMetadata.status 欄位為 READY。否則，如果媒體項目尚未完成處理，您可能會收到錯誤訊息。

範例：

base-url=dv

以下範例說明如何下載影片的位元組：

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w、h、c 和 d

說明

如要存取影片縮圖，請使用任何圖片基準網址參數。

根據預設，所有影片縮圖都會附上播放按鈕的疊加層。如要移除這項疊加層，請參閱 -no 參數。

範例：

如需範例，請參閱圖片基本網址表格。
no

說明

移除縮圖覆蓋圖層，no 參數。

如果您想擷取影片縮圖，但不顯示播放按鈕的疊加層，請將基本網址與 no 參數連結。

no 參數必須與至少一個 圖片基本網址參數搭配使用。

範例：

base-url=wmax-width-hmax-height-no

以下範例顯示的影片縮圖寬度和高度分別為 1280 像素和 720 像素，且不含播放按鈕重疊：

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

動態相片基本網址

動態相片包含相片和影片元素。您可以使用 圖片基本網址或影片基本網址中的參數，用於動態相片 baseUrl 要求。

參數
dv

說明

如要擷取動態相片媒體項目的影片元素，請使用 dv 參數，就像從影片基礎網址下載一樣。
w、h、c 和 d

說明

如要擷取動態相片媒體項目的圖片元素，請使用圖片基礎網址的格式。

後續步驟

  • 應用程式範例：我們的應用程式範例包含列出及擷取媒體項目的範例。詳情請參閱 checkMediaSourcesSet 和 fetch_media_item_list 函式。
  • 參考說明文件：請參閱全面的媒體項目參考文件，瞭解所有可用方法、要求和回應參數，以及錯誤代碼的詳細資訊。