このページは Cloud Translation API によって翻訳されました。

Android の構造化 API

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

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

エラー処理

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

HomeException を処理するときは、code フィールドと message フィールドを確認して、何が問題だったかを把握します。

処理されていない例外が発生すると、アプリがクラッシュします。

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

サンプル呼び出し

構造のリストを取得する

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

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

部屋の名前を変更する

setName() メソッドを呼び出して、部屋の名前を変更します。

livingRoom.setName("Living Room")

名前が 60 Unicode コードポイント（文字）の上限を超えている場合、名前は切り捨てられます。エラーは発生しません。長い名前の処理はデベロッパーの責任で行われます。たとえば、名前が切り捨てられることをユーザーに通知するかどうかをデベロッパーが決定できます。

自動化

Automation API のエントリポイントは構造体です。Home API の自動化について詳しくは、Android の Automation 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)`	特性属性の現在のスナップショットを取得します。

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