Android'deki Structure API'leri

Structure API'lere Android için Home API'ler üzerinden erişilebilir. Aşağıdaki paketleri uygulamanıza aktarın:

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

Hata işleme

Ev API'lerindeki herhangi bir yöntem HomeException oluşturabilir. Bu nedenle, tüm çağrılarda HomeException'ı yakalamak için try-catch bloğunu kullanmanızı öneririz.

HomeException işlenirken neyin yanlış gittiğini öğrenmek için error.code ve error.message alanlarını kontrol edin. Alt hata kodları da olabilir. Bu nedenle getSubErrorCodes() yöntemini çağırın ve sonucu kontrol edin.

İşlenmeyen tüm istisnalar, uygulamanızın kilitlenmesine neden olur.

Daha fazla bilgi için Hata işleme başlıklı makaleyi inceleyin.

Örnek görüşmeler

Yapıların listesini alma

Başlatıldıktan sonra structures() çağrısı, erişebileceğiniz bir yapı akışı döndürür:

// 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, geçerli bir yapı listesini hemen döndürmeyebilecek bir akıştır. Uygulamanız reaktifse ve kullanıcı arayüzünü yönlendirmek için bu akışa abone oluyorsa sonunda geçerli bir yapı listesi döndürülmelidir. Boş bir yapı listesinin döndürülebileceği başka durumlar da vardır. Örneğin, kullanıcının telefonunun bağlantısı kesilirse veya kullanıcı uygulamanızın izinlerini iptal ederse. Bu durumları uygulamanızda ele aldığınızdan emin olmalısınız.

Alternatif olarak, reaktif programlama yerine zorunlu programlama kesinlikle gerekiyorsa bir terminal akış operatörü kullanılabilir:

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

Bu çağrı, akıştan geçerli bir yapı listesinin gelmesini bekler ve liste, uygulamada belirtilen zaman aşımı süresi içinde alınmazsa zaman aşımına uğrar.

Yapı özelliklerini alma

Elinizde yapıların listesi varken özelliklerine erişebilirsiniz:

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

Yapıları ada göre bulma

Bir yapının adını biliyorsanız name özelliğini kullanarak da erişebilirsiniz:

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

Buradan her yapı için mülklere, odalara ve cihazlara erişilebilir.

Birden fazla yapıyla çalışma

Birden fazla yapı kullanmak için her yapıya ayrı bir referans alın:

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
}

Oda listesini alma

Elinizde bir yapı varken odaların listesini alabilir ve bu odaların özelliklerine erişebilirsiniz:

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

Oda oluştur

Yeni oda oluşturmak için:

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

Oda silme

Alternatif olarak, bir odayı silebilirsiniz:

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

Yalnızca kimlik içeren bir odayı da silebilirsiniz:

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

Cihaz içeren bir oda silinirse cihazlar yapıda kalmaya devam eder ancak artık bir odaya atanmaz.

Cihazları farklı bir odaya taşıma

Bir yapı oluşturduktan sonra cihazları bu yapıdaki farklı bir odaya taşıyabilirsiniz:

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

Yalnızca cihaz ve oda kimlikleriniz varsa cihazları da taşıyabilirsiniz:

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

Odanın adını değiştirme

Bir odanın adını değiştirmek için setName() yöntemini çağırın:

livingRoom.setName("Living Room")

Adlar, 60 Unicode kod noktası (karakter) sınırını aşarsa kesilir ve hata verilmez. Geliştiriciler, uzun adları işlemeyle sorumludur ve örneğin, adların kısaltılacağı konusunda kullanıcıları bilgilendirmek isteyip istemediklerine karar verebilirler.

Kullanıcının izin verdiği cihaz türlerini görüntüleme

Google Home ekosisteminde, çoğu cihaz türünde kullanıcılar bu türdeki tüm cihazlar için izinleri tek seferde verebilir. Kilitler, kameralar veya kapı zilleri gibi hassas ya da kısıtlanmış cihaz türleri için kullanıcıların bu cihazlara tek tek izin vermesi gerekir.

Bir kullanıcının hassas veya kısıtlanmış bir cihaz türüne erişim izni verip vermediğini belirlemek için yapı düzeyinde consentedDeviceTypes() işlevini kullanın:

import com.google.home.Structure
import com.google.home.DeviceType
import com.google.home.DeviceTypeFactory
import com.google.home.consentedDeviceTypes // Extension function from the SDK
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

/**
 * Example of how an app may monitor which device types have been granted access by a user.
 */
fun monitorDeviceConsent(structure: Structure, myScope: CoroutineScope) {
    // Obtain the flow of consented device type factories
    val consentedTypesFlow: Flow<Set<DeviceTypeFactory<out DeviceType>>> =
        structure.consentedDeviceTypes()

    myScope.launch {
        consentedTypesFlow.collect { consentedSet ->
            // Check if the user has consented to share a specific restricted
            // type, such as a Doorbell or Camera.
            val hasCameraAccess = consentedSet.any {
                it.toString() == "matter.google.type.GoogleDoorbellDevice"
            }

            if (hasCameraAccess) {
                // Enable features that require camera access
            } else {
                // Inform the user or disable camera-specific features
            }
        }
    }
}

Otomasyonlar

Automation API'ye giriş noktası bir yapı aracılığıyla olur. Home API'lerindeki otomasyonlar hakkında daha fazla bilgi edinmek için Android'de Automation API'ye genel bakış başlıklı makaleyi inceleyin.