ساختار API ها در iOS

APIهای ساختار ممکن است از طریق APIهای Home برای iOS قابل دسترسی باشند.

برای کار با Structure API، ابتدا بسته GoogleHomeSDK را به برنامه خود وارد کنید:

import GoogleHomeSDK

رسیدگی به خطا

برخی از روش‌ها در APIهای Home یک HomeError ایجاد می‌کنند، بنابراین توصیه می‌کنیم از بلوک do-catch برای دریافت HomeError در آن تماس‌ها استفاده کنید.

هنگام رسیدگی به HomeError ، فیلدهای code و message آن را بررسی کنید تا بدانید چه مشکلی پیش آمده است.

هر گونه خطای کنترل نشده باعث از کار افتادن برنامه شما می شود.

برای اطلاعات بیشتر، رسیدگی به خطا را ببینید.

API ساختار

Home نمودار Home را نشان می دهد و نقطه ورود به Structure API است. ارجاعاتی به سازه ها، اتاق ها و دستگاه ها ارائه می دهد.

Structure ساختاری را در نمودار Home شما نشان می دهد. این امکان دسترسی به ابرداده های ساختاری مانند id و name را فراهم می کند.

از structures() برای دریافت تمام ساختارها در حساب خود استفاده کنید. ساختارها در قالب یک Query برگردانده می شوند که راه های انتخابی برای مصرف داده های خود را ارائه می دهد:

فراخوانی structures().list() ممکن است بلافاصله مجموعه معتبری از ساختارها را برنگرداند. اگر برنامه شما واکنش‌پذیر است و stream() را برای اشتراک در همه تغییرات ساختار برای هدایت UI فراخوانی می‌کند، در نهایت باید فهرست معتبری از ساختارها برگردانده شود. موقعیت‌های دیگری وجود دارد که می‌توان یک لیست ساختار خالی را برگرداند، برای مثال اگر تلفن کاربر اتصال را قطع کند یا کاربر مجوزهای برنامه شما را لغو کرده باشد. شما باید مطمئن شوید که این موارد را در برنامه خود مدیریت می کنید.

@Published public private(set) var structures: [Structure] = []
private var structuresCancellable: AnyCancellable?

  self.structuresCancellable = home
    .structures()
    .batched()
    .receive(on: DispatchQueue.main)
    .map { Array($0) }
    .catch {
      Logger.error("Failed to load structures: \($0)")
      return Just([Structure]())
    }
    .assign(to: \.structures, on: self)

نمونه فراخوانی ساختار

مجموعه ای از ساختارها را دریافت کنید

فراخوانی list() در Query<Structure> جدیدترین مجموعه عناصر را برمی گرداند:

// Get a stream of all structures accessible to the user
let allStructuresChanges = try await self.home.structures()
let allStructures = try? await allStructuresChanges.list()

هنگام طراحی یک برنامه واکنش‌گرا، می‌خواهید از فراخوانی‌های batched() و stream() به جای list() استفاده کنید، زیرا اینها به طور خودکار داده‌ها را زمانی که نمودار اصلی تغییر می‌کند تولید می‌کنند.

خواص ساختار را دریافت کنید

با فهرستی از ساختارها، می توانید به ویژگی های آنها دسترسی داشته باشید:

// Get a stream of changes taking place on a structure.
let structureChanges = try await home.structures().list().filter { $0.id == structureID }

// Get a snapshot of the structure.
let structure = try await structureChanges.first!

// Get structure properties
print("id \(structure.id) ")
print("name \(structure.name) ")

یک سازه را با نام پیدا کنید

اگر نام یک ساختار را می دانید، می توانید با استفاده از ویژگی name نیز به آن دسترسی داشته باشید:

do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let error as HomeError {
  // Code for handling the exception
}

از آنجا، املاک، اتاق‌ها و دستگاه‌های هر سازه قابل دسترسی هستند.

با چندین ساختار کار کنید

برای استفاده از بیش از یک ساختار، یک مرجع جداگانه برای هر ساختار دریافت کنید:

var structure1: Structure!
var structure2: Structure!
do {
  structure1 = try await home.structures().list().first(where: { $0.name == "Main House" })
} catch let error as HomeError {
  // Code for handling the exception
}
do {
  structure2 = try await home.structures().list().first(where: { $0.name == "Guest Cottage" })
} catch let error as HomeError {
  // Code for handling the exception
}

اتاق ها

یک اتاق شامل گروهی از وسایل است. یک اتاق همیشه بخشی از یک سازه است و یک سازه ممکن است چندین اتاق داشته باشد. حذف یک اتاق از یک سازه، دستگاه های موجود در آن اتاق را از سازه حذف نمی کند. با این حال، اگر اتاق حذف شود، دستگاه‌های موجود در آن اتاق تخصیص داده نمی‌شوند.

از Home.rooms() برای بازیابی تمام اتاق های حساب استفاده کنید، سپس از roomID = device.roomID برای نمایش دستگاه های مربوطه در هر اتاق استفاده کنید.

self.home.rooms().batched()
  .combineLatest(self.home.devices().batched())
  .receive(on: DispatchQueue.main)
  .catch { error in
    Logger.error("Failed to load rooms and devices: \(error)")
    return Just((Set<Room>(), Set<HomeDevice>()))
  }
  .map { rooms, devices in
    var devicesByRoom = [Room: [HomeDevice]]()
    for room in rooms where room.structureID == currentStructureID {
      devicesByRoom[room] = devices.filter { $0.roomID == room.id }
    }
    return devicesByRoom
  }.assign(to: &self.$devicesByRoom)

نمونه تماس های اتاق

لیستی از اتاق ها را دریافت کنید

با استفاده از کلاس Home ، می‌توانید فهرستی از اتاق‌ها را دریافت کنید و به ویژگی‌های آنها دسترسی داشته باشید:

let allRoomsChanges = self.home.rooms()
let allRooms = try await allRoomsChanges.list()
let room = allRooms.first!
XCTAssertTrue(allRooms.contains(room))

print("id \(room.id) ")
print("name \(room.name) ")

یک اتاق ایجاد کنید

برای ایجاد یک اتاق جدید در یک Structure :

let testName = "Test Room Name"
var newRoom: Room!
do {
  newRoom = try await structure.createRoom(name: testName)
  XCTAssertNotNil(newRoom)
} catch let error as HomeError {
  // Code for handling the exception
}

یک اتاق را حذف کنید

یا، در عوض، می توانید یک اتاق را حذف کنید:

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

همچنین می توانید یک اتاق را با استفاده از شناسه آن حذف کنید:

let roomToDelete = allRooms.first(where: { $0.id == room.id })
if let roomToDelete1 = roomToDelete {
  do {
    try await structure.deleteRoom(roomToDelete1)
  } catch let error as HomeError {
    // Code for handling the exception
  }
}

اگر اتاقی با دستگاه‌ها حذف شود، دستگاه‌ها همچنان در ساختار هستند اما دیگر به اتاق اختصاص داده نمی‌شوند.

دستگاه ها را به اتاق دیگری منتقل کنید

Structure همچنین به شما امکان می دهد دستگاه را به اتاق دیگری منتقل کنید:

do {
  try await structure.move(device: light, to: room)
} catch let error as HomeError {
  // Code for handling the exception
}

نام اتاق را تغییر دهید

برای تغییر نام اتاق، متد setName(_:) را فراخوانی کنید:

let updatedRoom = try await theRoom.setName("new room name")

هنگام تغییر نام یک اتاق، ساختار اصلی Room ثابت می ماند و تغییر در شی Room به روز شده برگشتی منعکس می شود.

اگر بیش از 60 نقطه کد یونیکد (نویسه) حد مجاز باشد، نام ها کوتاه می شوند و هیچ خطایی ایجاد نمی شود. توسعه‌دهندگان مسئول رسیدگی به نام‌های طولانی هستند و به عنوان مثال، می‌توانند تصمیم بگیرند که آیا می‌خواهند به کاربران اطلاع دهند که نام‌های کوتاه می‌شوند یا خیر.

لیست API

هنگامی که یک نمونه از Home ایجاد می شود، API های ساختار زیر از طریق آن قابل دسترسی هستند:

Structure دارای API های زیر است:

Room دارای API های زیر است: