Permissions API

使用任何 Home API 前，應用程式必須具備存取使用者住家中裝置的權限，在 API 中稱為「結構體」。

Home API 會使用 OAuth 2.0 授予結構體中裝置的存取權。OAuth 可讓使用者授予應用程式或服務權限，而無須揭露登入憑證。使用者可透過 Permissions API，使用 Google 帳戶授予 Google Home API 應用程式存取家中裝置的權限。

使用 Permissions API 時，需要在應用程式、Google Cloud 和 Google Home Developer Console 中執行多個步驟：

1. 在 Google Cloud 中設定 OAuth
   1. 簽署應用程式
   2. 設定 OAuth 同意畫面
   3. 註冊應用程式並建立憑證
2. 整合 Permissions API
   1. 檢查權限
   2. 要求權限
3. 授予權限
   1. 變更權限
   2. 撤銷權限

在 Google Cloud 中設定 OAuth

如果您已擁有已驗證的 OAuth 用戶端，可以使用該用戶端，而無須設定新的用戶端。詳情請參閱「如果您已有 OAuth 用戶端」。

簽署應用程式

1. 在 Android Studio 中執行應用程式，產生 OAuth 金鑰。在 Android Studio 中執行或偵錯應用程式時，系統會自動產生用於開發和偵錯的 OAuth 金鑰。如需完整說明，請參閱「Android Studio：為偵錯版本簽署」。

   將行動裝置連接至本機。Android Studio 會依型號列出已連結的裝置。從清單中選取裝置，然後按一下「執行專案」。這會在行動裝置上建構及安裝範例應用程式。

   如需更詳細的操作說明，請參閱 Android 開發人員網站上的「在硬體裝置上執行應用程式」。

   接著停止執行中的應用程式。

2. 請按照 Google Cloud 控制台說明網站上的「設定 OAuth 2.0 / 原生應用程式/Android」一文中詳細說明的步驟，取得 OAuth 憑證的 SHA-1 指紋。

設定 OAuth 同意畫面

1. 在 Google Cloud 控制台中前往專案選取器資訊主頁，然後選取要用來建立 OAuth 憑證的專案。
2. 前往「API 和服務」頁面，然後點選導覽選單中的「憑證」。

3. 如果您尚未為這個 Google Cloud 專案設定同意畫面，系統會顯示「Configure consent screen」按鈕。在這種情況下，請按照下列程序設定同意畫面。否則，請繼續閱讀下一個部分。

   1. 按一下「設定同意畫面」。系統會顯示 OAuth 同意畫面頁面。
   2. 視用途而定，選取「內部」或「外部」，然後按一下「建立」。畫面上會顯示 OAuth 同意畫面窗格。
   3. 按照畫面上的指示，在「應用程式資訊」頁面輸入資訊，然後按一下「儲存並繼續」。系統會顯示「Scopes」窗格。
   4. 您不需要新增任何範圍，因此請按一下「儲存並繼續」。系統會顯示「Test users」窗格。
   5. 如果您想新增使用者，以便測試應用程式的存取權，請按一下「新增使用者」。系統隨即會顯示「新增使用者」窗格。測試使用者有權在您的應用程式中授予權限。
   6. 在空白欄位中新增一或多個 Google 帳戶電子郵件地址，然後按一下「新增」。
   7. 按一下「儲存並繼續」。系統會顯示「Summary」窗格。
   8. 查看 OAuth 同意畫面資訊，然後點選「返回資訊主頁」。

如需詳細資訊，請參閱 Google Cloud 控制台說明網站上的「設定 OAuth 同意畫面」。

註冊應用程式並建立憑證

如要為 OAuth 2.0 註冊應用程式並建立 OAuth 憑證，請按照「設定 OAuth 2.0」一文中的指示操作。您必須指出應用程式類型，也就是「原生/Android 應用程式」。

按照 Google Cloud 控制台說明網站上的設定 OAuth 2.0 / 原生應用程式一文中的操作說明，將您在簽署應用程式時取得的 SHA-1 指紋新增至您在 Google Cloud 控制台中設定的 OAuth 用戶端。

在行動裝置連上本機後，請從清單中選取裝置，然後再次按一下「Run project」執行專案。如需更詳細的操作說明，請參閱 Android 開發人員網站上的「在硬體裝置上執行應用程式」。

整合 Permissions API

使用者必須將權限授予您的應用程式，才能存取特定結構體中的裝置。開始之前，請確認您已按照這篇文章的說明初始化 Home API。此步驟中的 homeManager 例項會用於此處的所有權限範例。

首先，請使用 SDK 註冊 ActivityResultCaller。舉例來說，範例應用程式會以以下方式處理這項作業：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

檢查權限

在要求權限之前，建議您先檢查應用程式的使用者是否已同意授權。如要這麼做，請呼叫 Home 例項的 hasPermissions() 方法，取得 PermissionsState 值的 Flow：

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

如果檢查結果傳回 PermissionsState 的 NOT_GRANTED 或 PERMISSIONS_STATE_UNAVAILABLE，您就需要要求權限。如果檢查傳回 GRANTED 的 PermissionsState，但後續對 structures() 的呼叫未傳回任何結構，則表示使用者已透過 Google Home app (GHA) 設定頁面撤銷對應用程式的存取權，您應要求權限。否則，使用者應已具備存取權。

要求權限

您必須授予應用程式權限，才能存取特定結構體中的結構體和裝置。

如果使用者尚未授予權限，請使用 Home 例項的 requestPermissions() 方法啟動權限 UI，並處理結果：

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

如要讓權限 UI 正常啟動，您必須先為應用程式設定 OAuth。

授予權限

現在您應該可以執行應用程式，並要求使用者授予權限。您是否已在 Developer Console 中註冊應用程式，會影響可授予權限的使用者類型，以及可授予權限的裝置類型。

如要使用 Home API 發布應用程式，必須先完成 Developer Console 註冊程序。您不必測試及使用 Home API。如要存取控制台註冊功能，請與您的 Google Technical Account Manager (TAM)聯絡。

如果應用程式未註冊至 Developer Console，則會處於未驗證狀態。建議您使用以下方法測試 Home API 的用途：

• 只有在 OAuth 資訊主頁中註冊為測試使用者的使用者，才能授予應用程式權限。未經驗證的應用程式最多只能有 100 位測試使用者。

• 未經驗證的應用程式可存取任何裝置類型的裝置，這些裝置類型皆為 OAuth 支援的 Google Home API (Developer Console 中的裝置類型清單)。系統會授予結構體中的所有裝置。

如果應用程式已註冊至 Developer Console ，且已獲准存取一或多種裝置類型，且已完成 OAuth 品牌驗證，則會處於已驗證狀態。如要將應用程式發布至正式環境，就必須使用這個狀態：

• 測試使用者限制不再適用。任何使用者都能授予應用程式權限。
• 使用者只能將權限授予 Developer Console 中核准的裝置類型。

設定 OAuth 後，應用程式對 requestPermissions() 的呼叫會觸發下列對話方塊：

1. 系統會提示使用者選取要使用的 Google 帳戶。
2. 系統會提示使用者選取要授予應用程式存取權的結構。
   1. 對於未經驗證的應用程式，應用程式可使用 Google Home API 支援的所有裝置類型。
   2. 對於已驗證的應用程式，使用者只能將權限授予 Developer Console 中已核准的裝置類型。
   3. 如果應用程式有權管理的裝置類型屬於敏感裝置，使用者可以針對個別裝置限制存取權。舉例來說，如果使用者有三個居家鎖，則只能授予其中一個居家鎖的存取權。

取得權限後，應用程式就能使用 Home API 讀取結構體中的裝置狀態，並控制這些裝置。如果使用者未授予應用程式特定裝置類型或敏感裝置的權限，應用程式就無法使用 Home API 存取、控制或自動化這類裝置。

變更權限

如要授予不同結構中的裝置存取權，可以啟動帳戶挑選器，讓使用者選擇要切換的 Google 帳戶和結構。在此過程中，即使使用者先前已同意，系統仍會再次顯示同意畫面。

方法是再次呼叫 requestPermissions()，並將 forceLaunch 標記設為 true：

homeManager.requestPermissions(forceLaunch=true)

撤銷權限

使用者可以撤銷先前授予的存取權：

1. 前往 Google 我的帳戶頁面 >「資料和隱私權」>「第三方應用程式和服務」。這麼做會撤銷在授予初始同意聲明時核發的 OAuth 權杖，並撤銷使用者在所有途徑 (手機) 和結構中使用應用程式時，對任何應用程式例項的存取權。

2. 透過 GHA >「設定」>「已連結的應用程式」頁面。按一下 GHA 中的 settings，即可前往「設定」頁面。接著，請按一下「已連結的應用程式」圖塊，系統會帶您前往與同意聲明畫面類似的頁面。使用者可透過這個頁面移除應用程式的存取權。使用者也可以透過這個頁面變更應用程式可存取的裝置類型或特定敏感裝置。

3. 直接透過網頁上的已連結的應用程式頁面。

如果您已有 OAuth 用戶端

如果您已為已發布的應用程式使用已驗證的 OAuth 用戶端，可以使用現有的 OAuth 用戶端測試 Home API。

Developer Console 註冊不必使用 Home API 進行測試。不過，即使您已透過其他整合服務取得已驗證的 OAuth 用戶端，仍需要經過核准的 Developer Console 註冊才能發布應用程式。

請考量下列因素：

• 使用現有 OAuth 用戶端時，使用者人數上限為 100 位。如要瞭解如何新增測試使用者，請參閱「設定 OAuth 同意畫面」。除了 OAuth 驗證外，Google Home API 還會限制最多 100 位使用者可授予應用程式權限。完成 Developer Console 註冊後，這項限制就會解除。

• Developer Console註冊 ：當您準備好透過 OAuth 限制裝置類型授權，以便使用 Google Home API 更新應用程式時，請將註冊資訊送交審查。

如果 Google Cloud 應用程式仍在等待 OAuth 驗證，使用者必須等到驗證完成後，才能完成 OAuth 流程。授予權限的嘗試會失敗，並顯示以下錯誤：

Access blocked: <Project Name> has not completed the Google verification process.

OkGoogle 權限

okGoogle 指令是結構層級指令，可用於自動化結構中的任何裝置。不過，Home API 應用程式可能無法存取所有裝置。下表說明在這種情況下如何強制執行權限。