Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mengakses perangkat dan metadata perangkat untuk iOS

API Perangkat dapat diakses melalui Home API untuk iOS. Impor paket berikut ke dalam aplikasi Anda:

import GoogleHomeSDK
import GoogleHomeTypes

Untuk mengetahui informasi selengkapnya, lihat Model data di iOS.

Penanganan error

Beberapa metode di Home API menampilkan HomeError, jadi sebaiknya gunakan blok do-catch untuk menangkap HomeError pada panggilan tersebut.

Saat menangani HomeError, periksa kolom code dan message untuk mengetahui penyebab masalah.

Error yang tidak ditangani akan menyebabkan aplikasi Anda error.

Untuk mengetahui informasi selengkapnya, lihat Penanganan error.

Lihat Mengirim perintah ke perangkat untuk mengetahui contohnya.

Panggilan sampel

Mendapatkan daftar perangkat

Dengan referensi ke Home objek, panggil devices() untuk mendapatkan Query perangkat yang dapat diakses. Panggil metode Query's batched(), yang menampilkan Set yang mencerminkan status Home saat ini dengan setiap perubahan metadata perangkat. Atau, panggil Query.list() untuk mendapatkan snapshot perangkat yang tersedia. Ini adalah metode praktis yang berlangganan ke aliran batched() dan menampilkan nilai pertama yang ditampilkan. Query.stream() menghasilkan aliran yang menampilkan nilai baru pada perubahan metadata perangkat seperti nama, ruangan, atau struktur. Secara internal, metode ini menggunakan batched() dan hanya menampilkan properti yang diubah.

// Get a list of all devices accessible to the user
let homeDevices = try await self.home.devices().list()

Dari sana, Anda dapat mengakses status untuk setiap perangkat dan mengirim perintah ke perangkat.

Dengan Home API versi 1.8, Anda memiliki opsi untuk membuat API merepresentasikan setiap perangkat multipart sebagai satu perangkat dengan menetapkan parameter enableMultipartDevices metode devices() ke true. Lihat Perangkat multipart di iOS untuk mengetahui informasi selengkapnya.

Mendapatkan jenis perangkat

Untuk mendapatkan jenis perangkat yang terkait dengan perangkat, baca properti perangkat types, yang menampilkan DeviceTypeController.

Panggil DeviceTypeController.subscribe(_:) untuk berlangganan update untuk jenis perangkat tertentu:

let devices = try await self.home.devices().list()
if let device = devices.first(where: { $0.id == myDeviceId }) {
  var receivedUpdate1 = false
  var receivedUpdate2 = false
  device.types.subscribe(OnOffLightDeviceType.self)
    .assertNoFailure()
    .sink { device in
      if !receivedUpdate1 {
        receivedUpdate1 = true
        Task {
          try await device.matterTraits.onOffTrait?.on()
        }
        return
      }
      if !receivedUpdate2 {
        receivedUpdate2 = true
        return
      }
      fatalError("Received unexpected update")
    }
}

Jika perangkat tidak mendukung jenis perangkat yang ditentukan, perangkat akan menampilkan Empty Publisher yang segera selesai.

Jika perangkat mendukung jenis perangkat tertentu, Anda dapat mendapatkan handle ke jenis tersebut dengan memanggil get():

if let device = devices.first(where: { $0.id == myDeviceId }) {
  let _ = await device.types.get(OnOffLightDeviceType.self)
}

Jika perangkat tidak mendukung jenis yang ditentukan, perangkat akan menampilkan nil.

Panggil DeviceTypeController.subscribeAll() untuk mendapatkan Publisher dari DeviceTypeCollection. Class ini memungkinkan Anda memeriksa apakah perangkat memiliki jenis perangkat tertentu:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  device.types.subscribeAll()
    .assertNoFailure()
    .sink { types in
      let lightDeviceType = types[OnOffLightDeviceType.self]
      let fanDeviceType = types[FanDeviceType.self]
    }
}

Mendapatkan fitur jenis perangkat

Jenis perangkat adalah titik entri untuk membaca fitur, karena jenis perangkat menguraikan a perangkat menjadi bagian fungsionalnya (seperti endpoint di Matter).

Jenis perangkat juga memperhitungkan konflik fitur jika perangkat memiliki dua jenis perangkat, yang keduanya mungkin memiliki fitur yang sama. Misalnya, jika perangkat adalah Speaker dan Lampu yang Dapat Diredupkan, perangkat tersebut akan memiliki dua fitur On/Off dan dua fitur Kontrol Level.

Jenis konflik fitur lainnya dapat terjadi jika perangkat memiliki dua fitur dengan nama yang sama. Misalnya, onOff dapat merujuk ke instance fitur OnOff standar, atau dapat merujuk ke instance fitur OnOff yang ditentukan produsen. Untuk menghilangkan potensi ambiguitas terkait fitur mana yang dimaksud, referensikan fitur melalui salah satu dari dua koleksi fitur di setiap jenis perangkat.

Untuk fitur standar, yaitu fitur yang analog dengan Matter cluster standar, gunakan matterTraits. Misalnya, untuk mendapatkan fitur tertentu untuk jenis perangkat Lampu yang Dapat Diredupkan:

if let dimmableLightDeviceType =
  await device.types.get(DimmableLightDeviceType.self)
{
  // Accessing standard trait on the type.
  let levelControlTrait =
    dimmableLightDeviceType.matterTraits.levelControlTrait.self
}

Untuk fitur Google, gunakan googleTraits:

if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) {
  // Accessing Google trait on the type.
  let doorbellPressTrait =
    doorbellDeviceType.traits[Google.DoorbellPressTrait.self]
}

Untuk mengakses fitur khusus produsen, referensikan melalui properti traits, tetapi awali dengan nama paket produsen:

let deviceType = await device1?.types.get(OnOffLightDeviceType.self)
// Accessing custom trait on the type.
if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] {
  let rpmVal = spinnerTrait.attributes.rpm
}

Membaca status perangkat

Lihat contoh pemeriksaan atribut OnOff dari fitur On/Off perangkat ini:

let lightDevices = devices.filter {
  $0.types.contains(OnOffLightDeviceType.self)
}
let light1 = lightDevices.first
let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self)
if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait {
  let onOffVal = onOffTrait.attributes.onOff
}

Mendapatkan daftar perangkat dengan fitur tertentu

Untuk mendapatkan daftar perangkat yang memiliki fitur tertentu, Anda harus melakukan iterasi pada perangkat, jenis perangkat setiap perangkat, dan fitur setiap jenis perangkat. Misalnya, untuk mendapatkan daftar perangkat di rumah yang semuanya memiliki fitur On/Off:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
let allDevices = try await home.devices().list()
for device in allDevices {
  if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
    if deviceType.traits.contains(Matter.LevelControlTrait.self) {
      levelControlDevices.append(device)
    }
  }
}

Lihat Indeks fitur di iOS untuk mengetahui daftar lengkap fitur yang tersedia di Home API.

Mendapatkan daftar perangkat dengan jenis perangkat yang serupa

Untuk mendapatkan daftar perangkat yang mewakili semua lampu di rumah:

// Get a list of devices with similar device types (lights)
let lightDevices =
  try await self.home.devices().list().compactMap {
    $0.types.contains(DimmableLightDeviceType.self)
      || $0.types.contains(OnOffLightDeviceType.self)
      || $0.types.contains(ColorTemperatureLightDeviceType.self)
      || $0.types.contains(ExtendedColorLightDeviceType.self)
  }

Ada beberapa jenis perangkat di Home API yang dapat mewakili jenis perangkat inti. Misalnya, tidak ada jenis perangkat "Lampu". Sebagai gantinya, ada empat jenis perangkat berbeda yang dapat mewakili lampu, seperti yang ditunjukkan dalam contoh sebelumnya. Oleh karena itu, untuk mendapatkan tampilan komprehensif jenis perangkat tingkat yang lebih tinggi di rumah, beberapa jenis perangkat harus disertakan.

Lihat Jenis perangkat yang didukung di iOS untuk mengetahui daftar lengkap jenis perangkat dan fiturnya yang tersedia di Home API.

Mendapatkan Nama Vendor, ID Vendor, atau ID Produk untuk perangkat

Fitur BasicInformationTrait mencakup informasi seperti ID Vendor, ID Produk, Nama Produk, dan Nomor Seri untuk perangkat:

guard
  let vendorName =
    basicInfoTrait.attributes.vendorName
else {
  fatalError("Failed to get vendorName")
}
guard
  let vendorID =
    basicInfoTrait.attributes.vendorID
else {
  fatalError("Failed to get vendorID")
}
guard
  let productID =
    basicInfoTrait.attributes.productID
else {
  fatalError("Failed to get productID")
}

Identifikasi perangkat cloud-ke-cloud untuk produsen perangkat

Jika Anda adalah produsen perangkat dan membuat Cloud-to-cloud perangkat, untuk mengidentifikasi Cloud-to-cloud perangkat Anda melalui BasicInformation fitur, Anda dapat menyertakan kolom string ini dalam respons SYNC mereka:

ID vendor yang dikeluarkan Connectivity Standards Alliance (Alliance) "matterOriginalVendorId": "0xfff1",
ID Produk yang secara unik mengidentifikasi produk vendor: "matterOriginalProductId": "0x1234",
ID unik untuk perangkat, yang dibuat dengan cara khusus produsen: "matterUniqueId": "matter-device-id",

Saat memasukkan kolom string ini, gunakan Matter ID Vendor dan Produk jika Anda memilikinya. Jika Anda bukan anggota Alliance dan belum diberi ID ini, Anda dapat mengosongkan kolom matterOriginalVendorId dan matterOriginalProductId, lalu memberikan matterUniqueId sebagai ID.

Contoh respons SYNC menunjukkan penggunaan kolom ini:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "deviceInfo": { ... },
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "matterUniqueId": "matter-device-id",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

Untuk mengetahui informasi selengkapnya, lihat Cloud-to-cloud SYNC dokumentasi.

Metadata perangkat dan fitur

Perangkat dan fitur di Home API memiliki metadata yang terkait dengannya, yang dapat membantu mengelola pengalaman pengguna di aplikasi.

Setiap fitur di Home API berisi properti sourceConnectivity, yang memiliki informasi tentang status online dan lokalitas fitur (routing lokal atau jarak jauh).

Mendapatkan jenis utama perangkat

Beberapa perangkat dapat menampilkan beberapa jenis perangkat melalui Home API. Untuk memastikan pengguna mendapatkan opsi yang sesuai di aplikasi (seperti kontrol perangkat dan otomatisasi yang disarankan) untuk perangkat mereka, sebaiknya periksa apakah jenis perangkat adalah jenis utama perangkat.

if let deviceType =
  await device?.types.get(HumiditySensorDeviceType.self)
{
  if deviceType.metadata.isPrimaryType {
    print("Humidity Sensor is the primary type on this device.")
  } else {
    print("Humidity Sensor isn't the primary type on this device.")
  }
}

Memeriksa apakah fitur sedang online

Baca properti connectivityState untuk memeriksa konektivitas fitur:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

Beberapa fitur, biasanya fitur Google smart home mungkin menampilkan status offline jika perangkat tidak memiliki konektivitas internet. Hal ini karena fitur ini berbasis cloud dan tidak memiliki routing lokal.

Memeriksa konektivitas untuk perangkat

Konektivitas untuk perangkat sebenarnya diperiksa di tingkat jenis perangkat karena beberapa perangkat mendukung beberapa jenis perangkat. Status yang ditampilkan adalah kombinasi status konektivitas untuk semua fitur di perangkat tersebut.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

Status partiallyOnline dapat diamati dalam kasus jenis perangkat campuran jika tidak ada konektivitas internet. Matter Fitur standar Matter mungkin masih online karena routing lokal, tetapi fitur berbasis cloud akan offline.

connectivityStatepartiallyOnline

Mendapatkan alamat IP perangkat

Untuk menemukan alamat IP perangkat, gunakan atribut networkInterfaces dari the GeneralDiagnosticsTrait. Alamat ditampilkan sebagai objek Data, yang dapat Anda format ke string IPv4 atau IPv6 standar menggunakan framework Network:

func getIpAddresses(trait: Matter.GeneralDiagnosticsTrait) -> [String] {
  let interfaces = trait.attributes.networkInterfaces ?? []
  var ipAddresses: [String] = []

  for interface in interfaces {
    for data in interface.iPv4Addresses {
      if let ipv4 = IPv4Address(data) {
        ipAddresses.append(String(describing: ipv4))
      }
    }
    for data in interface.iPv6Addresses {
      if let ipv6 = IPv6Address(data) {
        ipAddresses.append(String(describing: ipv6))
      }
    }
  }

  return ipAddresses
}

Memeriksa routing jaringan fitur

Lokalitas untuk fitur juga tersedia di Home API. dataSourceLocality menunjukkan apakah fitur dirutekan dari jarak jauh (melalui cloud), secara lokal (melalui hub lokal), atau peer-to-peer (langsung dari perangkat ke perangkat, tanpa hub).

Nilai lokalitas yang tidak diketahui unspecified dapat terjadi, misalnya, saat aplikasi melakukan booting dan belum mencapai hub atau server untuk konektivitas perangkat. Perangkat ini tidak dapat dijangkau dan akan gagal dalam permintaan interaksi dari perintah atau peristiwa. Klien yang menentukan cara menangani perangkat tersebut.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

Memeriksa routing jaringan untuk perangkat

Seperti konektivitas, lokalitas diperiksa di tingkat jenis perangkat. Status yang ditampilkan adalah kombinasi lokalitas untuk semua fitur di perangkat tersebut.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

Status mixed dapat diamati dalam skenario yang serupa dengan konektivitas partiallyOnline: beberapa fitur berbasis cloud, sedangkan yang lain bersifat lokal.

Mengubah nama perangkat

Panggil metode setName(_:) untuk mengubah nama perangkat:

let updatedDevice = try await theDevice.setName("new device name")

Saat mengubah nama perangkat, struct HomeDevice asli tetap sama dan perubahan akan ditampilkan dalam objek HomeDevice yang diperbarui dan ditampilkan.

Nama akan dipangkas jika melebihi batas 60 titik kode Unicode (karakter) dan tidak ada error yang akan ditampilkan. Developer bertanggung jawab untuk menangani nama yang panjang dan, misalnya, dapat memutuskan apakah mereka ingin memberi tahu pengguna bahwa nama akan dipangkas.