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

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

أخطاء أخرى

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