Permissions API

Home API を使用する前に、アプリはユーザーの家にあるデバイス（API ではストラクチャ）にアクセスする権限を取得する必要があります。

Home API は、OAuth 2.0 を使用して構造内のデバイスへのアクセス権を付与します。OAuth を使用すると、ユーザーはログイン認証情報を公開することなく、アプリやサービスに権限を付与できます。Permissions API を使用すると、ユーザーは Google アカウントを使用して、家にあるデバイスへのアクセス権を Home APIs アプリに付与できます。

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 プロジェクトの同意画面をまだ構成していない場合は、[同意画面を構成] ボタンが表示されます。その場合は、次の手順で同意画面を構成します。問題が解決しない場合は、次のセクションに進みます。

   1. [同意画面を構成] をクリックします。OAuth 同意画面が表示されます。
   2. ユースケースに応じて [内部] または [外部] を選択し、[作成] をクリックします。[OAuth 同意画面] ペインが表示されます。
   3. 画面上の手順に沿って [アプリ情報ページ] に情報を入力し、[保存して次へ] をクリックします。[スコープ] ペインが表示されます。
   4. スコープを追加する必要はありません。[保存して次へ] をクリックします。[Test users] ペインが表示されます。
   5. アプリへのアクセスをテストするユーザーを追加する場合は、[ユーザーを追加] をクリックします。[ユーザーを追加] ペインが表示されます。テストユーザーには、アプリで権限を付与する権限があります。
   6. 空のフィールドに 1 つ以上の 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 クライアントに追加します。

モバイル デバイスをローカルマシンに接続し、リストからデバイスを選択して、[プロジェクトを実行] をもう一度クリックして実行します。詳細な手順については、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")
  }
}

チェックが NOT_GRANTED または PERMISSIONS_STATE_UNAVAILABLE の PermissionsState を返す場合は、権限をリクエストする必要があります。チェックで 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 人です。

• 未確認のアプリは、Home APIs の OAuth でサポートされているデバイスタイプ（Developer Console のデバイスタイプのリスト）のすべてのデバイスにアクセスできます。ストラクチャ内のすべてのデバイスにアクセス権が付与されます。

アプリが Developer Console に登録されており、1 つ以上のデバイスタイプへのアクセスが承認され、OAuth のブランド確認が完了している場合、そのアプリは確認済みステータスになります。 この状態は、アプリを本番環境にリリースするために必要です。

• テストユーザーの上限は適用されなくなりました。どのユーザーもアプリに権限を付与できます。
• ユーザーは、Developer Console で承認されたデバイスタイプにのみ権限を付与できます。

OAuth が設定されたので、アプリの requestPermissions() 呼び出しによって次のダイアログがトリガーされます。

1. ユーザーは、使用する Google アカウントを選択するよう求められます。
2. アプリにアクセス権を付与する構造を選択するよう求めるメッセージが表示されます。
   1. 未確認のアプリの場合、Home API でサポートされているすべてのデバイスタイプがアプリで使用できます。
   2. 確認済みのアプリの場合、ユーザーは Developer Console で承認されているデバイスタイプにのみ権限を付与できます。
   3. アプリが管理にアクセスできる機密性の高いデバイスタイプについては、ユーザーはデバイスごとにアクセスを制限できます。たとえば、ユーザーが 3 つのロックを持っている場合、アクセス権を付与できるのは 1 つのロックのみです。

権限が付与されると、アプリは Home API を使用してストラクチャ内のデバイスの状態を読み取り、デバイスを操作できるようになります。ユーザーが特定のデバイスタイプまたは機密性の高いデバイスに対してアプリに権限を付与しない場合、アプリは Home API を使用してデバイスにアクセス、制御、自動化を行うことはできません。

権限を変更

別の構造のデバイスにアクセスする権限を付与するには、アカウント選択ツールを起動して、ユーザーが切り替える Google アカウントと構造を選択できるようにします。このプロセスでは、以前に同意が得られていた場合でも、ユーザーに同意画面が再度表示されます。

これを行うには、forceLaunch フラグを true に設定して requestPermissions() を再度呼び出します。

homeManager.requestPermissions(forceLaunch=true)

権限を取り消す

ユーザーは、以前に付与したアクセス権を取り消すことができます。

1. Google マイアカウント ページ > [データとプライバシー] > [サードパーティ製のアプリとサービス] からアクセスします。これにより、最初の同意が付与されたときに発行された OAuth トークンが取り消され、ユーザーがすべてのサーフェス（スマートフォン）と構造で使用していたアプリのインスタンスへのアクセスが取り消されます。

2. [GHA] > [設定] > [リンクされたアプリ] ページからアクセスします。GHA の settings をクリックすると、[設定] ページが表示されます。そこから [リンク済みアプリ] タイルをクリックすると、同意画面に似たページが表示されます。このページから、アプリへのアクセス権を削除できます。また、この同じページを使用して、アプリがアクセスできるデバイスタイプや特定の機密性の高いデバイスを変更することもできます。

3. ウェブの [リンク済みアプリ] ページから直接。

既存の OAuth クライアントがある場合

公開済みのアプリの検証済み OAuth クライアントがすでにある場合は、既存の OAuth クライアントを使用して Home API をテストできます。

Home API のテストと使用に Developer Console の登録は必要ありません。ただし、別の統合から検証済みの OAuth クライアントがあっても、アプリを公開するには承認済みの Developer Console 登録が必要です。

次のことに注意してください。

• 既存の OAuth クライアントを使用する場合、ユーザー数の上限は 100 ユーザーです。テストユーザーの追加については、OAuth 同意画面を設定するをご覧ください。OAuth の確認とは別に、Home APIs では、アプリに権限を付与できるユーザー数が 100 人に制限されています。この制限は、Developer Console の登録が完了すると解除されます。

• Developer Console 登録 は、Home API を使用してアプリを更新する準備として、OAuth を介してデバイスタイプの権限付与を制限する準備ができたら、承認のために送信する必要があります。

OAuth 検証が保留中の Google Cloud アプリの場合、検証が完了するまでユーザーは OAuth フローを完了できません。権限を付与しようとすると、次のエラーで失敗します。

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

OkGoogle の権限

okGoogle コマンドは構造レベルのコマンドであり、構造内の任意のデバイスを自動化するために使用できます。ただし、Home APIs アプリがすべてのデバイスにアクセスできるとは限りません。次の表に、このような場合に権限が適用される仕組みを示します。