設定 Ambient API 應用程式

如要開始使用 Ambient API，請在 Google API 控制台中啟用 API，並設定 OAuth 2.0 用戶端 ID，藉此設定專案。Ambient API 會使用 適用於電視和輸入裝置應用程式的 OAuth 2.0。

您的應用程式會代表 Ambient API 使用者與 Ambient API 互動。使用者會使用 OAuth 2.0 通訊協定授權這些 API 要求。

OAuth 2.0 用戶端 ID 可讓應用程式使用者登入、驗證，進而使用 Ambient API。Ambient API 不支援服務帳戶。如要使用這些 API，使用者必須登入有效的 Google 帳戶。

設定應用程式

請先啟用 API，然後要求 OAuth 2.0 用戶端 ID。

啟用 API

您必須先在專案中啟用 Ambient API，才能使用這項 API。

  1. 前往 Google API 控制台。
  2. 在選單列中選取專案或建立新專案。
  3. 如要開啟 Google 相簿 API，請在導覽選單中依序選取「API 和服務」>「程式庫」。
  4. 搜尋「Ambient API」。選取 Ambient API，然後按一下「啟用」。

要求 OAuth 2.0 用戶端 ID

請按照下列步驟要求 OAuth 用戶端 ID，並為應用程式設定用戶端 ID。Ambient API 會使用 適用於電視和輸入裝置應用程式的 OAuth 2.0。

  1. 前往 Google API 控制台，然後選取您的專案。
  2. 在選單中，依序選取「API 和服務」>「憑證」。

  3. 在「憑證」頁面上，依序點選「建立憑證」>「OAuth 用戶端 ID」。

  4. 選取「應用程式類型」。在這個範例中，應用程式類型為「電視和輸入受限的裝置」。

  5. 為 OAuth 2.0 用戶端提供名稱，然後按一下「建立」。

  6. 在隨後顯示的 OAuth 用戶端對話方塊中，複製下列內容：

    • 用戶端 ID
    • 用戶端密碼

應用程式可以使用這些值存取已啟用的 Google API。

您必須先讓 Google 審查應用程式，才能推出可存取 Ambient API 的公開應用程式。在您測試應用程式之前，畫面上會顯示「未驗證的應用程式」訊息，直到應用程式通過驗證為止。

設定應用程式後，即可開始使用。您可以參閱下列資源，或繼續閱讀有關 Ambient API 簡化驗證流程的說明。

變更用戶端 ID

透過任何 Google 相簿 API 建立的資源，只能使用用於建立這些資源的原始用戶端 ID 存取或修改。舉例來說，如果您在 Picker API 中使用特定用戶端 ID 建立 session，之後又在應用程式中變更該用戶端 ID，應用程式就會失去使用先前用戶端 ID 建立的任何 API 資源的存取權。

請仔細規劃，並為所使用的 Google 相簿 API 選擇正確的用戶端 ID 類型。只有在絕對必要的情況下，才可以變更用戶端 ID，以免發生存取問題。

簡化 Ambient API 的驗證流程

標準的 Ambient API 驗證流程要求使用者掃描 2 個 QR code：

  • 第一步：登入 Google 帳戶 (如果尚未登入)。
  • 第二個是連結至 Google 相簿帳戶中新建立的 Ambient 裝置，使用者可在該裝置上選取要顯示的媒體項目。

透過簡化流程，您可以透過初始驗證呼叫傳遞額外的 state 參數，為使用者提供單一 QR code。

針對有限輸入裝置要求裝置和使用者代碼時，請在要求中加入額外的 state 參數。將下列內容新增至 state 參數：

參數
requestId

string

必要欄位。用戶端提供的這項要求專屬 ID。這可用於在網路發生故障時，減少資源重複。

這個 ID 必須採用 UUID (第 4 版) 字串格式，並符合下列規定：

  • 不得包含任何使用者的機密識別資訊。
  • 必須包含 32 個十六進位字元，以連字號分為五組，格式為「xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx」(或 8-4-4-4-12)。
displayName

string

選用設定。使用者為這部裝置定義的顯示名稱。

使用者可在 Google 相簿應用程式設定中看到這項資訊，但只能透過這個 API 編輯。

有效的顯示名稱長度必須介於 1 至 100 個半形字元之間 (含上下限)。

例如，請參閱下列程式碼區塊：

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

成功的回應會包含 user_code 和 verification_url，您可以向使用者顯示這些資訊 (最有可能是以 QR code 的形式)，讓他們在其他裝置上前往該頁面。只要加入 state 參數，日後使用 Ambient API 呼叫 createDevice 時，您就可以略過在第二個 QR code 中顯示 settingsUri，因為 OAuth 流程中的最後一個步驟會自動重新導向至這個位置。

如需完整詳細資訊，請參閱以下更詳盡的說明。您也可以查看範例應用程式中的程式碼，瞭解如何使用 Ambient API 為有限輸入裝置的 OAuth 使用 state 參數。

簡化驗證流程的詳細資訊

如要充分瞭解 Ambient API 的簡化 OAuth 流程，建議您同時瞭解適用於電視和輸入裝置應用程式的 OAuth 2.0 流程，以及標準的 Ambient API 流程。以下是各流程的步驟。

適用於電視和輸入受限裝置的應用程式：

  1. 應用程式會向 Google 授權伺服器傳送要求，指出應用程式要求存取權限的範圍。
  2. 伺服器會傳回幾個資訊，供後續步驟使用，例如裝置代碼和使用者代碼。
  3. 您可以顯示使用者可在其他裝置上輸入的資訊，以授權您的應用程式。
  4. 應用程式會開始輪詢 Google 授權伺服器，判斷使用者是否已授權您的應用程式。
  5. 使用者切換至輸入功能更豐富的裝置，開啟網路瀏覽器，前往步驟 3 顯示的網址，然後輸入步驟 3 中顯示的代碼。使用者就能授予 (或拒絕) 應用程式的存取權。
  6. 輪詢要求的下一個回應會包含應用程式需要的權杖，以便代表使用者授權要求。(如果使用者拒絕存取您的應用程式，回應就不會包含權杖)。

Ambient API 流程：

  1. 檢查是否有現有的 OAuth 權杖，然後重新整理權杖或要求新的權杖。
  2. 取得 OAuth 權杖後，請建立新裝置。
  3. 向使用者顯示 settingsUri，並開始輪詢裝置，直到 mediaSourcesSet 傳回 true 為止。
  4. 使用者前往 settingsUri，然後選取要與應用程式共用的相片。
  5. mediaSourcesSet 傳回 true 後，請擷取 mediaItems 清單。
  6. 您現在可以開始幻燈片或其他微光螢幕體驗了。

這兩個流程都包含一個步驟，您會向使用者顯示網址，而使用者則可透過更豐富的輸入裝置前往該網址。只要在初始 OAuth 呼叫中加入 state 參數，即可避免顯示第二個網址。

這是因為適用於電視和輸入受限裝置應用程式的 OAuth 2.0 流程最後一個步驟通常會將使用者重新導向至「您現在可以返回裝置」的頁面。由於包含狀態參數，流程的最後一個步驟現在會嘗試將您重新導向至 settingsUri。應用程式仍會收到 OAuth 權杖。您應使用這個符記，透過相同的 requestId 呼叫 createDevice。建立具有相同 ID 的裝置後，初始 OAuth 流程就會成功將使用者重新導向至相片應用程式中豐富裝置的正確頁面。

請注意下列事項：

  • 不過，如果驗證程序發生問題，建議您還是顯示 settingsUri。
  • 您仍可在其他情況下使用 settingsUri，例如使用者想要更新所選相片時。