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

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