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

بعد الحصول على رمز مميّز للوصول وإجراء طلب الحصول على قائمة الأجهزة الأولي، أصبحت الآن جاهزًا لاستخدام واجهة برمجة التطبيقات لمجموعة أدوات 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 الخطأ.