開始使用 Ambient API

Ambient API 可讓應用程式將環境裝置連結至使用者的 Google 相簿帳戶，並顯示使用者選取的相片。

Ambient API 流程

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

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

2. 啟動 OAuth 2.0 授權：要求授權碼，開始適用於電視和輸入受限裝置的 OAuth 2.0 流程。

   注意： Ambient API 支援在授權要求中加入 state 參數，以啟用簡化驗證流程。

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

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

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

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

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

   AmbientDevice 回應包含 pollingConfig 和 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 參考文件：瀏覽詳細參考文件，瞭解所有可用方法、要求和回應參數，以及錯誤代碼。