الوصول إلى الأجهزة والبيانات الوصفية للأجهزة في نظام التشغيل iOS

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يمكن الوصول إلى واجهات برمجة تطبيقات الأجهزة من خلال واجهات برمجة تطبيقات Home لنظام التشغيل iOS. استورِد الحِزم التالية إلى تطبيقك:

import GoogleHomeSDK
import GoogleHomeTypes

لمزيد من المعلومات، يُرجى الاطّلاع على نموذج البيانات على نظام التشغيل iOS.

معالجة الأخطاء

تُعرِض بعض الطرق في واجهات برمجة تطبيقات Home HomeError، لذا ننصحك باستخدام رمز do-catch لرصد HomeError في هذه الطلبات.

عند التعامل مع HomeError، تحقّق من حقلَي code وmessage لمعرفة الخطأ الذي حدث.

ستؤدي أي أخطاء غير متوقَّعة إلى تعطُّل تطبيقك.

لمزيد من المعلومات، يُرجى الاطّلاع على معالجة الأخطاء.

اطّلِع على إرسال أمر إلى جهاز للاطّلاع على مثال.

نماذج المكالمات

الحصول على قائمة بالأجهزة

باستخدام إشارة إلى عنصر Home ، يمكنك استدعاء devices() للحصول على Query من الأجهزة التي يمكن الوصول إليها. استخدِم Query batched() الطريقة التي تُصدِر مجموعة تعكس الحالة الحالية للمنزل مع كل تغيير في البيانات الوصفية للجهاز. أو يمكنك الاتصال بالرقم Query.list() للحصول على لمحة عن الأجهزة المتاحة. هذه طريقة مساعدة تشترك في مجرىbatched() وتُرجع أول قيمة يتم بثّها. يُنشئ Query.stream() بثًا يُرسِل قيمًا جديدة عند تغيير البيانات الوصفية للجهاز، مثل اسمه أو غرفته أو بنيته. في الوقت نفسه، يتم استخدام batched() لعرض السمات التي تم تغييرها فقط.

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

ومن هناك، يمكن الوصول إلى حالات كل جهاز، ويمكن إرسال الأوامر المتاحة إلى الجهاز.

الحصول على أنواع الأجهزة

للحصول على أنواع الأجهزة المرتبطة بجهاز معيّن، اقرأ سمة types الجهاز، والتي تعرض قيمة DeviceTypeController.

يُرجى الاتصال بالرقم DeviceTypeController.subscribe(_:) للاشتراك في تلقّي إشعارات بشأن تحديثات نوع جهاز معيّن:

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")
    }
}

إذا كان الجهاز لا يتوافق مع نوع الجهاز المحدّد، يتم عرض Empty Publisher يتم إكماله على الفور.

إذا كان الجهاز متوافقًا مع نوع جهاز معيّن، يمكنك الحصول على معرّف لذلك النوع من خلال الاتصال get():

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

إذا كان الجهاز لا يتيح النوع المحدّد، يتم عرض القيمة nil.

يُرجى الاتصال بالرقم DeviceTypeController.subscribeAll() للحصول على Publisher بشأن DeviceTypeCollection. تتيح لك هذه الفئة التحقّق ممّا إذا كان الجهاز يحتوي على نوع جهاز معيّن:

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]
    }
}

الحصول على سمة نوع الجهاز

تشكّل أنواع الأجهزة نقطة الدخول لقراءة السمات، لأنّها تُحلّل الجهاز إلى أجزائه الوظيفية (مثل نقاط النهاية في Matter).

وتراعي هذه الميزة أيضًا حالات تعارض السمات في حال كان الجهاز يضم نوعَين من الأجهزة، قد يكون لكلاهما السمة نفسها. على سبيل المثال، إذا كان الجهاز مكبّر صوت ومصباحًا قابلَين للتعتيم، سيتضمّن سمتَي تشغيل/إيقاف و سمتَي التحكّم في المستوى.

يمكن أن يحدث نوع آخر من تعارض السمات عندما يكون للجهاز سمتان يحملان الاسم نفسه. على سبيل المثال، يمكن أن تشير onOff إلى مثيل لسمة OnOff العادية، أو يمكن أن تشير إلى مثيل لسمة OnOff حدّدها المصنّع. لإزالة أي غموض محتمل بشأن السمة المقصودة، يمكنك الإشارة إلى سمة من خلال إحدى مجموعتَي السمات على كل نوع من أنواع الأجهزة.

بالنسبة إلى السمات العادية، أي تلك التي تشبه Matter المجموعات العنقودية العادية، استخدِم matterTraits. على سبيل المثال، للحصول على سمة محدّدة لنوع جهاز الإضاءة المتغيّرة السطوع:

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

بالنسبة إلى سمات Google، استخدِم googleTraits:

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

للوصول إلى سمة خاصة بالشركة المصنّعة، يمكنك الإشارة إليها من خلال السمة traits ، ولكن عليك وضع اسم حزمة الشركة المصنّعة قبلها:

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
}

قراءة حالة جهاز

اطّلِع على هذا المثال للتحقّق من سمة OnOff من سمة On/Off (تفعيل/إيقاف) للجهاز:

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
}

الحصول على قائمة بالأجهزة التي تتضمّن سمة معيّنة

للحصول على قائمة بالأجهزة التي تتضمّن سمة معيّنة، عليك تكرار المرور على الأجهزة وأنواع كل جهاز وسمات كل نوع من أنواع الأجهزة. على سبيل المثال، للحصول على قائمة بالأجهزة في المنزل التي تتضمّن جميعها سمة "تفعيل/إيقاف":

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
var 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)
    }
  }
}

اطّلِع على فهرس السمات على نظام التشغيل iOS للحصول على قائمة كاملة بالسمات المتاحة في واجهات برمجة تطبيقات Home.

الحصول على قائمة بالأجهزة التي تتضمّن أنواع أجهزة مشابهة

للحصول على قائمة بالأجهزة التي تمثّل جميع الأضواء في المنزل:

// 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)
  }

هناك أنواع متعددة من الأجهزة في واجهات برمجة التطبيقات Home APIs التي يمكن أن تمثّل نوع جهاز أساسيًا. على سبيل المثال، لا يتوفّر نوع جهاز "مصباح". بدلاً من ذلك، هناك أربعة أنواع مختلفة من الأجهزة التي يمكن أن تمثّل مصباحًا، كما هو موضّح في المثال السابق. وبالتالي، للحصول على نظرة شاملة على نوع الجهاز على مستوى أعلى في المنزل، يجب تضمين أنواع أجهزة متعددة.

اطّلِع على أنواع الأجهزة المتوافقة على نظام التشغيل iOS للحصول على قائمة كاملة بأنواع الأجهزة والسمات المتاحة في واجهة برمجة التطبيقات Home APIs.

الحصول على اسم المورِّد أو معرِّف المورِّد أو معرِّف المنتج لجهاز

تتضمّن السمة BasicInformationTrait معلومات مثل معرّف المورّد ومعرّف المنتج واسم المنتج الرقم التسلسلي للجهاز:

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")
}

تحديد الأجهزة من السحابة الإلكترونية إلى السحابة الإلكترونية لصنّاع الأجهزة

إذا كنت صانع أجهزة وتُنشئ أجهزة Cloud-to-cloud، يمكنك تضمين حقول السلاسل التالية في استجابة SYNC لتحديد أجهزتك Cloud-to-cloud من خلال سمة BasicInformation:

• رقم تعريف المورّد الذي أصدرته رابطة Connectivity Standards Alliance‏ (CSA): "matterOriginalVendorId": "0xfff1",

• معرّف منتج يحدّد منتجًا خاصًا بمورّد بشكل فريد: "matterOriginalProductId": "0x1234",

• معرّف فريد للجهاز يتم إنشاؤه بطريقة خاصة بالمصنّع: "matterUniqueId": "matter-device-id",

عند إدخال حقول السلاسل هذه، استخدِم Matter معرّفات المورّد والمنتجات إذا كانت لديك. إذا لم تكن مشتركًا في CSA ولم يتم تحديد هذين الرقمَين التعريفيَين لك، يمكنك ترك حقلَي matterOriginalVendorId و matterOriginalProductId فارغَين وتقديم matterUniqueId كأحد علامتَي التعريف.

يوضّح مثال استجابة SYNC استخدام هذه الحقول:

{
  "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",
          }
        ]
      }
    ]
  }
}

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Cloud-to-cloud SYNC.

البيانات الوصفية للأجهزة والسمات

تحتوي الأجهزة والسمات في واجهات برمجة تطبيقات Home على بيانات وصفية مرتبطة بها، ويمكن أن تساعد هذه البيانات في إدارة تجربة المستخدم في التطبيق.

تحتوي كل سمة في واجهات برمجة تطبيقات Home على سمة sourceConnectivity ، والتي تتضمّن معلومات عن حالة السمة على الإنترنت وموقعها الجغرافي (التوجيه المحلي أو عن بُعد).

الحصول على النوع الأساسي للجهاز

قد تعرض بعض الأجهزة أنواع أجهزة متعددة من خلال Home APIs. لضمان تقديم الخيارات المناسبة للمستخدمين في التطبيق (مثل التحكّم في الجهاز والإجراءات المبرمَجة المقترَحة) لأجهزة المستخدمين، من المفيد التحقّق ممّا إذا كان نوع الجهاز هو نوعه الأساسي.

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.")
  }
}

التحقّق مما إذا كانت السمة متوفّرة على الإنترنت

اطّلِع على السمة connectivityState للتحقّق من إمكانية اتصالها:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

قد تظهر بعض السمات، عادةً سمات smart home من Google، بلا إنترنت إذا لم يكن الجهاز متصلاً بالإنترنت. ويعود السبب في ذلك إلى أنّه تستند هذه السمات إلى السحابة الإلكترونية ولا تتضمّن توجيهًا محليًا.

التحقّق من إمكانية اتصال جهاز

يتم التحقّق من إمكانية اتصال الجهاز بالإنترنت على مستوى نوع الجهاز لأنّ بعض الأجهزة تتوافق مع أنواع أجهزة متعددة. الحالة التي يتم عرضها هي مزيج من حالات الاتصال لجميع السمات على هذا الجهاز.

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

قد تظهر الحالة partiallyOnline في حال استخدام أنواع أجهزة مختلطة في حال عدم توفّر اتصال بالإنترنت. Matter قد تظلّ الصفات العادية متاحة على الإنترنت بسبب التوجيه المحلي، ولكن الصفات المستندة إلى السحابة الإلكترونية ستكون غير متاحة.

التحقّق من توجيه الشبكة لسمة

تتوفّر أيضًا معلومات الموقع الجغرافي للسمة في Home APIs. يشير الرمز dataSourceLocality إلى ما إذا كان يتم توجيه السمة عن بُعد (من خلال السحابة الإلكترونية) أو محليًا (من خلال مركز اتصالات محلي) أو من جهاز إلى جهاز (مباشرةً من الجهاز إلى الجهاز بدون مركز اتصالات).

يمكن أن تظهر قيمة الموقع الجغرافي غير المعروفة unspecified، على سبيل المثال، أثناء بدء تشغيل أحد التطبيقات ولم يصل بعد إلى مركز أو خادم لربط الجهاز. لا يمكن الوصول إلى هذه الأجهزة، ولن يتمكّن الجهاز من تنفيذ طلبات التفاعل المرسَلة من الأوامر أو الأحداث. ويعود الأمر إلى العميل لتحديد كيفية التعامل مع هذه الأجهزة.

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

التحقّق من توجيه الشبكة لجهاز

تمامًا مثل الاتصال، يتم التحقّق من الموقع الجغرافي على مستوى نوع الجهاز. الولاية التي يتم عرضها هي عبارة عن تركيبة من الموقع الجغرافي لجميع السمات على ذلك الجهاز.

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

قد تظهر حالة mixed في سيناريو مشابه لحالة الاتصال partiallyOnline: تكون بعض السمات مستندة إلى السحابة الإلكترونية في حين تكون سمات أخرى محلية.

قائمة واجهات برمجة التطبيقات

بعد إنشاء مثيل لتطبيق Home، يمكن من خلاله الوصول إلى واجهات برمجة تطبيقات الأجهزة التالية:

بعد الحصول على HomeDevice، يمكنك من خلاله الوصول إلى موارد برمجة التطبيقات التالية: