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

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

import GoogleHomeSDK
import GoogleHomeTypes

لمزيد من المعلومات، يُرجى الاطّلاع على نموذج البيانات على أجهزة iOS.

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

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

عند معالجة HomeError، تحقَّق من الحقلَين code وmessage لمعرفة المشكلة.

ستؤدي أي أخطاء لم تتم معالجتها إلى تعطُّل تطبيقك.

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

يمكنك الاطّلاع على إرسال أمر إلى جهاز للحصول على مثال.

نماذج الطلبات

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

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

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

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

مع الإصدار 1.8 من واجهات برمجة التطبيقات لمنزل Google، يتوفّر لك خيار جعل واجهة برمجة التطبيقات تمثّل كل جهاز متعدد الأجزاء كجهاز واحد من خلال ضبط المعلمة enableMultipartDevices للطريقة devices() على true. لمزيد من المعلومات، يُرجى الاطّلاع على الأجهزة متعددة الأجزاء على أجهزة iOS.

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

للحصول على أنواع الأجهزة المرتبطة بجهاز، اقرأ السمة للجهاز 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 _ = 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.traits[Google.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 من سمة تشغيل/إيقاف التشغيل في الجهاز:

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] = []
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)
    }
  }
}

يُرجى الاطّلاع على فهرس السمات على أجهزة iOS للحصول على قائمة كاملة بالسمات المتاحة في واجهات برمجة التطبيقات لمنزل Google.

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

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

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

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

يُرجى الاطّلاع على أنواع الأجهزة المتوافقة على أجهزة iOS للحصول على قائمة كاملة بأنواع الأجهزة وسماتها المتاحة في واجهات برمجة التطبيقات لمنزل Google.

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

تتضمّن السمة 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، يمكنك تحديد هوية أجهزتك Cloud-to-cloud من خلال السمة BasicInformation، وذلك من خلال تضمين حقول السلسلة هذه في استجابة SYNC:

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

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

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

عند إدخال حقول السلسلة هذه، استخدِم أرقام تعريف Matter المورِّد والمنتج إذا كانت متوفّرة لديك. إذا لم تكن عضوًا في Alliance ولم يتم تخصيص أرقام التعريف هذه لك، يمكنك ترك الحقلَين 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.

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

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

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

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

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

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

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

التحقّق من اتصال الجهاز

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

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

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

الحصول على عنوان IP للجهاز

للعثور على عنوان IP للجهاز، استخدِم السمة networkInterfaces في الـ GeneralDiagnosticsTrait. يتم عرض العناوين كعناصر Data، يمكنك تنسيقها كسلاسل IPv4 أو IPv6 عادية باستخدام إطار عمل 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
}

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

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

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

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

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

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

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

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

تغيير اسم الجهاز

استدعِ الطريقة setName(_:) لتغيير اسم الجهاز:

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

عند تغيير اسم الجهاز، يظل البنية HomeDevice الأصلية كما هي ويظهر التغيير في العنصر HomeDevice المعدَّل المعروض.

سيتم اقتطاع الأسماء إذا تجاوزت الحد الأقصى لعدد نقاط رمز Unicode (الأحرف) البالغ 60 ولن يتم عرض أي أخطاء. يتحمّل المطوّرون مسؤولية التعامل مع الأسماء الطويلة، ويمكنهم مثلاً تحديد ما إذا كانوا يريدون إبلاغ المستخدمين بأنّه سيتم اقتطاع الأسماء.