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

Home API'lerindeki herhangi bir yöntem HomeException hata verebilir. Bu nedenle, tüm çağrılarda HomeException yakalamak için bir try-catch bloğu kullanmanızı öneririz.

HomeException ile ilgili işlem yaparken 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.

İşlenmemiş istisnalar, uygulamanızın kilitlenmesine neden olur.

Daha fazla bilgi için Hata işleme bölümüne bakın.

Ö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ürmeyebilen 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 olmanız gerekir.

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 belirlenen zaman aşımı süresi içinde alınmazsa zaman aşımına uğrar.

Yapı özelliklerini alma

Elinizde yapıların listesi varken bunların ö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
}

Odaların listesini alma

Elinizde bir yapı olduğunda 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 bir 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!!)

Ayrıca, yalnızca kimlik kullanarak da oda silebilirsiniz:

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

Cihazların bulunduğu 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 kısaltılır ve hata verilmez. Geliştiriciler, uzun adları işlemeyle sorumludur ve örneğin, kullanıcılara adların kısaltılacağını bildirmek isteyip istemediklerine karar verebilirler.

Google Home ekosisteminde, çoğu cihaz türü için kullanıcılar bu türdeki tüm cihazlara aynı anda izin 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
            }
        }
    }
}

Cihaz grupları

Cihaz grubu, tek bir yapı içindeki kullanıcı tanımlı cihaz koleksiyonunu temsil eder.

Fiziksel odalar gibi, cihaz grupları da tek bir yapıya aittir. Ancak odaların aksine, cihaz grupları mantıksal gruplandırmalardır. Bir cihaz aynı anda birden fazla cihaz grubuna ait olabilir. Cihaz grupları en fazla 100 cihaz içerebilir.

Cihaz grupları, HomeDevice'den farklı olan Group öğesiyle temsil edilir.

Cihaz grubu oluşturma

Cihaz grubu oluşturmak için yapıda GroupManagement simgesini kullanın:

val groupManagement = structure.trait(GroupManagementTrait)
val response = groupManagement?.createUserDefinedGroup(
  name = "Living room lights",
  memberDeviceObjectIds = listOf(light1.id.id, light2.id.id)
)

Grup üyeliğini yönetme

Mevcut bir gruba üye eklemek için:

structure.trait(GroupManagementTrait)?.addGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light3.id.id)
)

Gruptan üye çıkarmak için:

structure.trait(GroupManagementTrait)?.removeGroupMembers(
  groupObjectId = group.id.id,
  memberDeviceObjectIds = listOf(light1.id.id)
)

Cihaz grubunun adını değiştirme

Bir cihaz grubunu yeniden adlandırmak için grubun GroupTrait üzerindeki ad özelliğini güncelleyin:

group.trait(GroupTrait)?.update {
  name = "Movie corner"
}

Cihaz grubunu silme

Bir cihaz grubunu yapıdan silmek için:

structure.trait(GroupManagementTrait)?.deleteGroup(
  groupObjectId = group.id.id
)

Otomasyonlar

Automation API'ye giriş noktası bir yapıdır. Home API'lerdeki otomasyonlar hakkında daha fazla bilgi edinmek için Android'de Automation API'ye genel bakış başlıklı makaleyi inceleyin.