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

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

إدراج الهياكل والأجهزة

استخدِم 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 الأخطاء.