列出及擷取媒體項目

使用者在 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 帳戶設定撤銷應用程式的權限，網址可能會提早失效。

注意： 對 PickedMediaItem.mediaFile baseUrl 提出的要求必須包含 Authorization 標頭，以及有效的 OAuth 2.0 不記名權杖。

對於 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	說明 如要擷取動態相片媒體項目的相片元素，請使用圖片基本網址的格式。

內容政策和篩選

在電視或數位螢幕等共用裝置上顯示圖片和影片時，Google 相簿預設會套用標準內容篩選功能。這項篩選器可排除以下內容，提升觀看體驗：

• 功能性圖片 (例如螢幕截圖、文件、收據)。
• 圖片在大螢幕上可能無法正常顯示 (例如解析度過低、模糊、顆粒感過重)。
• 系統判定為高度個人或私密內容，可能不適合在共用環境中公開顯示。

所有內容篩選作業都是自動進行。如要讓使用者進一步控管顯示的內容，可以允許他們手動選取及更新微光模式使用的媒體來源。

後續步驟

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