استخدام واجهة برمجة التطبيقات

بعد أن أصبح رمز الدخول في متناول اليد وإجراء مكالمة قائمة الأجهزة الأولية، أصبحت الآن جاهزًا لاستخدام واجهة برمجة التطبيقات SDM API للوصول إلى جهازك والتحكّم فيه.

إدراج البُنى والأجهزة

استخدِم curl لإجراء طلب GET بسيط إلى نقطة نهاية structures:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/structures' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

تعرض المكالمة الناجحة قائمة بالبُنى الخاصة بالحسابات المرتبطة بمشروعك:Device Access :

{
  "structures": [
    {
      "name": "enterprises/project-id/structures/structure-id",
      "traits": {
        "sdm.structures.traits.Info": {
          "customName": "structure-name"
        }
      }
    }
  ]
}

إذا لم يسبق لك إجراء مكالمة GET إلى نقطة النهاية devices للحصول على قائمة بالأجهزة، يمكنك تنفيذ ما يلي:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

تعرض المكالمة الناجحة قائمة بالأجهزة المرتبطة بمشروعك. Device Access لكل جهاز قائمة فريدة خاصة به من السمات المتاحة:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

انسخ device-id لكل جهاز، ستحتاج إليه لطلب طلبات البيانات من واجهة برمجة التطبيقات الأخرى.

الحصول على معلومات بشأن جهاز

للحصول على معلومات عن جهاز معيّن، يمكنك إجراء مكالمة GET إلى نقطة النهاية device-id:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

من المفترض أن يكون الرد مشابهًا كما في السابق، ولكن بالنسبة إلى الجهاز المحدّد فقط:

{
  "name": "enterprises/project-id/devices/device-id",
  "type": "sdm.devices.types.device-type",
  "traits": { ... },
  "parentRelations": [
    {
      "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName": "device-room-name"
    }
  ]
}

تنفيذ أمر

بعد التحقُّق من إمكانية الوصول من خلال طلب GET ناجح، جرِّب تنفيذ أمر استنادًا إلى نوع الجهاز الذي سمحت له باستخدام:

جهاز الترموستات

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.ThermostatMode.SetMode",
    "params" : {
      "mode" : "HEAT"
    }
  }'

الكاميرا

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
    "params" : {}
  }'

إذا كانت مكالمتك ناجحة، سيتم عرض النتائج التالية:

جهاز الترموستات

ستتلقّى استجابة فارغة وسيغيّر الترموستات الوضع الحالي إلى الوضع المحدّد في معلَمات الأمر.

{}

الكاميرا

ستتلقّى عنوان URL للبث المباشر ورموزًا مميّزة ذات صلة.

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

تحديد المشاكل وحلّها

عدم الحصول على المصادقة

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

أخطاء أخرى

يمكنك الرجوع إلى مرجع رمز الخطأ للاطّلاع على القائمة الكاملة Device Access لرموز الخطأ.