يمكن الوصول إلى واجهات برمجة التطبيقات Structure API من خلال واجهات برمجة التطبيقات Home API لنظام التشغيل iOS.
للعمل مع واجهات برمجة تطبيقات Structure، عليك أولاً استيراد حزمة GoogleHomeSDK
إلى
تطبيقك:
import GoogleHomeSDK
معالجة الأخطاء
تُعرِض بعض الطرق في واجهات برمجة تطبيقات Home HomeError
، لذا ننصحك باستخدام رمز do-catch
لرصد HomeError
في هذه الطلبات.
عند التعامل مع HomeError
، تحقّق من حقلَي code
وmessage
لمعرفة الخطأ الذي حدث.
ستؤدي أي أخطاء غير متوقَّعة إلى تعطُّل تطبيقك.
لمزيد من المعلومات، يُرجى الاطّلاع على معالجة الأخطاء.
واجهة برمجة التطبيقات Structure API
يمثّل Home
الرسم البياني "المنزل"، وهو نقطة الدخول إلى Structure API.
وتوفّر هذه البيانات إشارات إلى الهياكل والغرف والأجهزة.
يمثّل الرمز Structure
بنية في الرسم البياني "المنزل". تتيح هذه البيانات الوصول إلى
البيانات الوصفية للبنية، مثل id
وname
.
استخدِم structures()
للحصول على
جميع الهياكل في حسابك. يتم عرض البنى على شكل
Query
، ما يقدّم خيارًا
لطرق استخدام بياناتها:
واجهة برمجة التطبيقات | الوصف |
---|---|
stream() |
تعرِض هذه الدالة Publisher تُرسِل كل عنصر على حدة أثناء حدوث التغييرات. |
batched() |
تعرِض Publisher التي تُصدِر النتيجة الحالية كSet من العناصر. يمثّل كل Set يتمّ بثّه الحالة الحالية لرسم بيانيّ الكائنات. |
list() |
لعرض النتيجة الحالية كSet من العناصر. |
قد لا يعرض طلب 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()
ل retrieving retrieve all the rooms in the account، ثم استخدِم roomID = device.roomID
ل displaying the corresponding devices in each room.
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 }
قائمة واجهات برمجة التطبيقات
بعد إنشاء مثيل لبنية
Home
، يمكن من خلاله الوصول إلى
واجهات برمجة تطبيقات Structure التالية:
واجهة برمجة التطبيقات | الوصف |
---|---|
devices() |
إتاحة جميع الأجهزة لهذا الحساب |
device(id:) |
الحصول على Publisher لجهاز محدّد يُرسِل الحالة الحالية ومرة أخرى عند حدوث أي تعديلات على الحالة في المستقبل |
structures() |
الحصول على جميع الهياكل في حساب Google تعرِض هذه الدالة Query<Structure> الذي يقدّم المزيد من خيارات الاسترجاع والفلترة. |
structure(id:) |
الحصول على البنية التي تحمل رقم التعريف المطابق |
rooms() |
الحصول على جميع الغرف في حساب Google تعرِض هذه الدالة Query<strRoom> الذي يقدّم المزيد من خيارات الاسترجاع والفلترة. |
room(id:) |
يمكنك الحصول على Publisher لغرفة محدّدة تُرسِل الحالة الحالية ومرة أخرى عند تحديث أي حالة مستقبلية. |
تتضمّن Structure
موارد برمجة التطبيقات التالية:
واجهة برمجة التطبيقات | الوصف |
---|---|
deleteRoom(id:) |
يمكنك حذف غرفة باستخدام رقم تعريف الغرفة. |
id |
المعرّف الفريد للنظام للبنية |
move(device:, to:) |
نقل جهاز إلى غرفة مختلفة في البنية |
move(device:, to:) |
نقل الجهاز الذي يحمل رقم التعريف المحدَّد إلى الغرفة التي تحمل رقم التعريف المحدَّد |
move(devices:, to:) |
تنقل الأجهزة المحدّدة إلى الغرفة المحدّدة. |
move(devices:, to:) |
نقل الأجهزة التي تحمل معرّفات محدّدة إلى الغرفة التي تحمل معرّفًا محدّدًا |
name |
الاسم الذي يوفّره المستخدم للبنية |
تتوفّر واجهتَا برمجة التطبيقات التاليتَين في Room
:
واجهة برمجة التطبيقات | الوصف |
---|---|
id |
المعرّف الفريد للنظام الخاص بالغرفة |
name |
اسم الغرفة الذي يوفّره المستخدم. |
structureID |
المعرّف الفريد للنظام الخاص بالبنية التي تنتمي إليها الغرفة |