Permissions API

在使用任何 Home API 之前，應用程式必須具備存取使用者住家中裝置的權限，在 API 中稱為「結構體」。使用 Permissions API 後，使用者就能透過 Google 帳戶授予 Home API 應用程式住家中裝置的存取權。

整合 Permissions 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。

授予權限

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

如要使用 Home API 發布應用程式，必須先完成 Developer Console 註冊程序。您不需要測試及使用 Home API。

如果應用程式未註冊至 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. 直接透過網頁上的已連結的應用程式頁面。

OkGoogle 權限

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