開始使用 Ambient API

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

背景 API 流程

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

  1. 檢查現有裝置 (建議)：建議您在建立新裝置前，先檢查目前使用者是否已擁有裝置。應用程式應為內部使用者和 Google 提供的 deviceId 建立對應，以便使用者透過應用程式建立任何裝置。如果找到使用者的 deviceId，您可以繼續 (視需要) 重新整理其授權權杖。

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

  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 等情境。

如需更多詳細資訊，請參閱「列出及擷取媒體項目」指南。

後續步驟