開始使用 Ambient API

應用程式可透過 Ambient API 將微光裝置連結至使用者的 Google 相簿帳戶，並顯示所選相片。

Ambient API 流程

以下說明 Ambient API 如何連結裝置，然後擷取及顯示媒體項目：

1. 檢查現有裝置 (建議)：建立新裝置前，建議先檢查目前使用者是否已有裝置。應用程式應維護內部使用者與 Google 提供的 deviceId 之間的對應關係，以利使用者透過應用程式建立裝置。如果找到使用者的 deviceId，您可以繼續重新整理授權權杖 (如有需要)。

2. 啟動 OAuth 2.0 授權 (並視需要建立裝置)：要求授權碼，開始電視和輸入受限裝置的 OAuth 2.0 流程。

   注意： Ambient API 支援在授權要求中加入 state 參數。這會指示 Ambient API 在授權成功後，嘗試建立新裝置。

3. 建立新裝置：應用程式會呼叫 CreateDevice 並提供有效的 v4 UUID，在使用者 Google 相簿帳戶中建立裝置。

   成功建立裝置後，API 會傳回包含 Google 指派 deviceId 的 AmbientDevice 物件。應用程式必須儲存這項 deviceId，並與使用者建立關聯。

4. 顯示 settingsUri：AmbientDevice 物件包含 settingsUri。向使用者顯示這個 URI (通常是 QR code)，使用者可以使用行動裝置掃描。這個 URI 會將使用者導向 Google 相簿應用程式，讓他們設定要在微光模式裝置上顯示的媒體來源 (例如相簿)。

5. 輪詢 mediaSourcesSet：應用程式應定期呼叫 GetDevice 方法，並提供 deviceId，以檢查周遭裝置的狀態。監控回應中的 mediaSourcesSet 欄位。AmbientDevice 一開始會是 false。

   使用者在 Google 相簿應用程式中成功選取媒體來源後，這個欄位就會變更為 true。

   AmbientDevice 回應包含 pollingConfig 和 pollInterval，您應將 pollInterval 做為輪詢頻率的準則。

6. 擷取媒體項目：如果 mediaSourcesSet 傳回 true，應用程式即可開始擷取使用者選取的媒體項目。

   呼叫 ListMediaItems 方法，並提供 deviceId。API 會傳回包含 AmbientMediaItem 物件清單的 ListMediaItemsResponse。每個 AmbientMediaItem 都包含詳細資料，例如 id、createTime，以及含有額外中繼資料的 MediaFile 物件。MediaFile 包含 baseUrl，可用於擷取媒體項目的實際位元組。如要進一步瞭解其他 baseUrl 參數，請參閱「列出及擷取媒體項目」指南。

7. 顯示媒體項目：使用 MediaFile 中的 baseUrl，在環境裝置上顯示媒體內容。

重要注意事項

裝置限制和管理：

• 裝置限制：請注意，每個應用程式使用者最多只能有 100 部裝置。
• 裝置活動和權杖：您需要管理裝置和使用者授權權杖的生命週期。請考量裝置的有效期限，以及裝置閒置或權杖過期時，如何處理權杖重新整理或重新授權。

如需更多詳細資料，請參閱「建立及管理裝置」指南。

處理媒體項目：

• 媒體項目使用情形：瞭解如何使用 baseUrl 正確擷取及處理媒體項目內容，包括任何必要的驗證或參數。
• 錯誤處理：針對 API 呼叫實作完善的錯誤處理機制，包括裝置的 NOT_FOUND、未設定媒體來源時的 FAILED_PRECONDITION，以及達到裝置限制時的 RESOURCE_EXHAUSTED 等情境。

如需更多詳細資料，包括內容政策和篩選資訊，請參閱「列出及擷取媒體項目」指南。

後續步驟

• 設定應用程式：確認您擁有必要憑證，並已為電視和受限輸入裝置專用的 OAuth 2.0 設定應用程式。
• 查看 Ambient API 參考說明文件：瀏覽詳細的參考說明文件，瞭解所有可用的方法、要求和回應參數，以及錯誤代碼。