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

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