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

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

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

import GoogleHomeSDK

مدیریت خطا

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

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

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

برای اطلاعات بیشتر، به بخش مدیریت خطا مراجعه کنید.

ساختار API

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

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

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

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

@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!!)

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

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 به‌روزرسانی‌شده‌ی برگردانده‌شده منعکس می‌شود.

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

لیست API

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

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

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