API を構成する

Structure API には、Home API を介してアクセスできます。次のパッケージをアプリにインポートします。

import com.google.home.Home
import com.google.home.Id
import com.google.home.Structure

エラー処理

Home API のどのメソッドでも HomeException をスローする可能性があるため、すべての呼び出しで try-catch ブロックを使用して HomeException をキャッチすることをおすすめします。

HomeException を処理する際は、code フィールドと message フィールドをチェックして、エラーの原因を確認します。

例外を処理しないと、アプリがクラッシュします。

詳細については、エラー処理をご覧ください。

呼び出しの例

構造のリストを取得する

初期化されると、structures() 呼び出しはアクセス可能な構造体のフローを返します。

// Get a flow of all structures accessible to the user
val allStructuresFlow: HomeObjectsFlow<Structure> = home.structures()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allStructures: Set<Structure> = allStructuresFlow.list()

structures() API は、有効な構造リストをすぐに返さない可能性があるフローです。アプリがリアクティブで、そのフローをサブスクライブして UI を駆動する場合、最終的には有効な構造リストが返されます。空の構造リストが返される状況は他にもあります。たとえば、ユーザーのスマートフォンが接続を失った場合や、ユーザーがアプリに対する権限を取り消した場合などです。このようなケースはアプリで必ず処理する必要があります。

また、リアクティブ プログラミングではなく命令型プログラミングが強く求められる場合は、ターミナル フロー演算子を使用できます。

val everyStructure = withTimeout(5000) { home.structures().first { it.isNotEmpty() } }

この呼び出しは、有効な構造リストがフローから送信されるのを待機し、アプリ指定のタイムアウト内にリストが受信されなかった場合はタイムアウトします。

構造のプロパティを取得する

構造物のリストを取得したら、そのプロパティにアクセスできます。

// Get a flow on a structure. Flow emits new values on structure metadata changes: name.
val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

// Get structure properties
println("id ${structure.id}")
println("name ${structure.name}")

名前で構造を検索する

構造体の名前がわかっている場合は、name プロパティを使用してアクセスすることもできます。

val myHome = home.structures().list().first { it.name == "My home" }

そこから、各構造物のプロパティ、部屋、デバイスにアクセスできます。

複数の構造を扱う

複数の構造を使用するには、各構造への個別の参照を取得します。

var structure1: Structure? = null
var structure2: Structure? = null

try {
  structure1 = home.structures().list().firstOrNull { it.name == "Main House" }
} catch (e: HomeException) {
  // Code for handling the exception
}
try {
  structure2 = home.structures().list().firstOrNull { it.name == "Guest Cottage" }
} catch (e: HomeException) {
  // Code for handling the exception
}

部屋のリストを取得する

構造が手元にあると、部屋のリストを取得して、部屋のプロパティにアクセスできます。

val allRoomsFlow: HomeObjectsFlow<Room> = structure.rooms()
val allRooms: Set<Room> = allRoomsFlow.list()
val room: Room = allRooms.first()

println("id ${room.id}")
println("name ${room.name}")

チャットルームを作成する

新しい部屋を作成するには:

val testName = "Test Room Name"
val newRoom: Room = structure.createRoom(testName)

部屋を削除する

または、部屋を削除することもできます。

val roomToDelete = structure.rooms().list().filter { it.name == "room_id1" }.firstOrNull()
    structure.deleteRoom(roomToDelete!!)

ID のみを使用して部屋を削除することもできます。

val roomToDelete1 = allRooms.filter { it.id == testRoomId }.firstOrNull()
structure.deleteRoom(roomToDelete1!!)

デバイスのある部屋を削除しても、デバイスは構造内に残りますが、部屋には割り当てられなくなります。

デバイスを別の部屋に移動する

ストラクチャを作成したら、そのストラクチャ内の別の部屋にデバイスを移動できます。

val room2 = structure.rooms().get(Id("room_id_other_structure"))
    val device1 = structure.devices().get(Id("device_id1"))
    structure.moveDevicesToRoom(room2!!, listOf(device1!!))

デバイス ID と部屋 ID のみがわかる場合は、デバイスを移動することもできます。

structure.moveDevicesToRoom(Id("room_id_other_structure"), listOf(Id("device_id1")))

自動化

Automation API へのエントリ ポイントは構造です。Home API の自動化の詳細については、自動化を設計するをご覧ください。

API リスト

Home のインスタンスが作成されると、次の Structure API にアクセスできるようになります。

API 説明
structures() Google アカウントのすべてのストラクチャを取得します。詳細な取得とフィルタリング オプションを提供する HomeObjectsFlow を返します。

Structure を取得すると、次の API にアクセスできます。

API 説明
automations() ストラクチャに属するすべての自動化を一覧表示します。Home API で作成された自動化のみが返されます。
createAutomation(automation) 構造の自動化インスタンスを作成します。
createRoom(name) ユーザーが指定した名前で部屋を作成します。
deleteAutomation(automationId) ID で自動化インスタンスを削除します。
deleteRoom(roomId) 部屋 ID を指定して部屋を削除します。
devices() ストラクチャ内のすべてのデバイスを取得します。HomeObjectsFlow を返します。
getAutomation(automationId) ID で自動化インスタンスを取得します。
getSourceConnectivity(trait) 特定の特徴のメタデータを取得します。SourceConnectivity を返します。
has(trait) 現在のリクエストされた特徴がデバイスでサポートされているかどうかを確認します。
id 構造物の一意のシステム ID。
moveDevicesToRoom(roomId, deviceIds) デバイスをストラクチャ内の別の部屋 ID に移動します。
name ユーザーが指定した構造の名前。
rooms() ストラクチャ内のすべての部屋を取得します。HomeObjectsFlow を返します。
trait(trait) 特徴属性の現在のスナップショットを取得します。

一般的な API(devices()idname など)は、Room でも使用できます。