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() 方法启动权限界面并处理结果：

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}")
      }
    }
  }
}

如需正确启动权限界面，您必须已为应用设置 OAuth。

授予权限

现在，您应该能够运行应用并让用户授予权限。可以授予权限的用户类型以及可授予权限的设备类型因您是否已在 Google Home Developer Console 中注册应用而异。

若要使用 Home API 发布应用，必须进行 Developer Console 注册。无需进行测试即可使用 Home API。

如果某个应用未在 Developer Console 中注册，则会处于未经验证状态。建议您使用以下方法测试 Home API 的使用情况：

• 只有在 OAuth 控制台中注册为测试用户的用户才能为应用授予权限。未经验证的应用的测试用户数量上限为 100 人。

• 未经验证的应用将有权访问 Home API 的 OAuth 支持的任何类型的设备（Developer Console 中的设备类型列表）。系统会授予结构中的所有设备访问权限。

如果应用已在 Developer Console 中注册 ，并且已获准访问一种或多种设备类型，并且已完成 OAuth 品牌验证，则该应用将处于已验证状态。应用必须处于此状态才能发布到生产环境：

• 测试用户数量上限已不再适用。任何用户都可以向应用授予权限。
• 用户只能向 Developer Console 中已获批准的设备类型授予权限。

现在，OAuth 已设置完毕，应用对 requestPermissions() 的调用会触发以下对话框：

1. 系统会提示用户选择要使用的 Google 账号。
2. 系统会提示用户选择要向应用授予访问权限的结构。
   1. 对于未经验证的应用，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 应用可能无法访问每台设备。下表介绍了在这种情况下如何强制执行权限。