アプリケーション開発

デバイス API

デバイス API は、ゲートウェイに対して、デバイス (サービス) の発見 (discoverServices()) とアクションの実行 (request()) を行う API 群です。

※ Symphony で「デバイス」または「シング」と呼ばれる概念は、デバイスコネクトでは「サービス」と呼ばれます。

discoverServices()

このメソッドは、指定のゲートウェイにサービスの発見を指示し、その結果を返します。ゲートウェイでのサービス発見には 10 秒以上の時間がかかる場合があります。このメソッドはデバイスコネクトが返す情報をそのまま返し、Symphony で利用するうえで必要な加工は施されていません。Symphony は必要に応じて自動的にサービスの発見を行いますので、通常はこのメソッドを使う必要はありません。このメソッドは、Promise オブジェクトを返します。

このメソッドは、以下のプロパティを持ったオブジェクトを引数に取ります。

パラメータ
プロパティ名 型 必須 説明
gatewayId String 必須 ゲートウェイ ID。
サンプルコード
dSymphony.discoverServices({
  gatewayId : 'gw-CAE3AB3F4F5A93733CF2451E720F2344'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

このメソッドの実行が成功すると、コールバック関数には Symphony から返されたオブジェクトが引数に与えられます。

レスポンスの例
{
  "profile": "networkServiceDiscovery",
  "attribute": "getNetworkServices",
  "services": [
    {
      "serviceId": "hue-bridge-0017882C7D50",
      "name": "Philips hue bridge 2015",
      ...
    },
    {
      "serviceId": "hue-light-0017882C7D50-1",
      "name": "Hue color lamp 1",
      ...
    },
    ...
  ],
  "product": "node-gotapi",
  "result": 0,
  ...
}

request()

このメソッドは、ゲートウェイにインストールされているデバイスコネクトに対して、サービスのリクエストを送ります。このメソッドは、Promise オブジェクトを返します。

このメソッドは、以下のプロパティを持ったオブジェクトを引数に取ります。

パラメータ
プロパティ名 型 必須 説明
path String 必須 デバイスへのリクエストパス。
method String 任意 デバイスへのリクエストメソッド。get, post, put, delete のいずれか。指定がなければ get が指定されたものとして処理されます。
gatewayId String 任意 ゲートウェイ ID。指定がなければ Symphony が適切と思われるゲートウェイに自動的にリクエストを割り振ります。
thingId String 条件付き デバイスを識別するシング ID。
nickname String 条件付き ニックネーム。
tagName String 条件付き タグ名。
parameters Object Optional デバイスコネクト API パラメータを格納したハッシュオブジェクト。

thingId, nickname, tagName のいずれか 1 つは必須です。しかし、2 つ以上を同時に指定することはできません。

以下のサンプルコードは、デバイス識別子 (thingId) を指定して、Hue のライトを黄色に点灯します。

サンプルコード
dSymphony.request({
  path       : '/light',
  method     : 'post',
  thingId    : 'th-A7E2F85D264D52E8F2EA0B507D8CCA57',
  parameters : {
    color    : 'ffff00'
  }
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

このメソッドの実行が成功すると、コールバック関数には Symphony から返されたオブジェクトが引数に与えられます。

レスポンスの例
{
  "result": 0,
  "serviceId": "hue-light-0017882C7D50-1",
  ...
}

以下のサンプルコードは、タグ名 (tagName) を指定して、該当のタグ名に属する複数の Hue のライトを赤色にまとめて点灯します。

サンプルコード
dSymphony.request({
  path       : '/light',
  method     : 'post',
  tagName    : '居間の照明',
  parameters : {
    color    : 'ff0000'
  }
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

このメソッドの実行が成功すると、コールバック関数には Symphony から返されたオブジェクトが引数に与えられます。

レスポンスの例
{
  "results": [
    {
      "result": 0,
      "serviceId": "hue-light-0017882C7D50-1",
      ...
    },
    {
      "result": 0,
      "serviceId": "hue-light-0017882C7D50-2",
      ...
    },
    {
      "result": 0,
      "serviceId": "hue-light-0017882C7D50-3",
      ...
    }
  ]
}

このように、対象のデバイスが 1 つの場合と複数の場合とではレスポンスのデータ構造が若干違うので注意してください。また、デバイスコネクト側のエラーについては、本 SDK はハンドリングしません。そのため、デバイスコネクト側の処理結果の判定を行いたい場合は、result が 0 かどうかをチェックしてください。0 なら成功を意味します。それ以外の値の場合は、何かしらのエラーが発生したことを意味します。

アプリケーション開発