アプリケーション開発

チーミング管理 API

もしゲートウェイが 2 つあり、それぞれのゲートウェイが同じデバイスを認識していた場合、それぞれのゲートウェイ経由で該当のデバイスが Symphony に登録されると、別々の thingId が割り当てられます。Symphony 内部では、それぞれの thingId は実質的に同じデバイスを指していることは認識しています。そのため、該当のデバイスが提供するアクションを実行する場合、つまり、request() メソッドを呼び出す際には、どちらの thingId を指定しても構いません。仮に一方のゲートウェイがオフラインだったとしても、Symphony はもう一方のゲートウェイ経由で該当のデバイスにアクセスしようとします。

通常は、Symphony がどちらのゲートウェイを使うかを自動的に判定するこの通常の仕組みで問題なく利用できますが、Symphony では、2 つのゲートウェイをどのように使うのかを細かく制御する枠組みも提供しています。

チーミング とは、このように同一のデバイスであるにもかかわらず、異なるゲートウェイ経由で登録されたため、別々の thingId が割り当てられた状況において、それら 2 つの thingId をグルーピングして、あたかも一つのデバイスであるかのように扱うための仕組みです。そのグルーピングされた仮想的なデバイスをチーミングデバイスと呼びます。チーミングデバイスには新たに thingId が割り当てられます。request() メソッドを使ってアクションを実行する際には、このチーミングデバイスの thingId を指定することができます。しかし、単にアクションを実行するという意味においては、個々の thingId を指定して実行するのと違いはありません。個々の thingIid を指定したとしても、Symphony は自動的にアクティブなゲートウェイを経由してリクエストを送るからです。

チーミングを利用するメリットは、その 2 つのゲートウェイの利用頻度の配分や、優先度を指定できる点です。チーミングには AGGREGATION モードと FAULT_TOLERANCE モードという 2 つのモードを設定することができます。

AGGREGATION モードでは、2 つの thingId に対して配分率をそれぞれ指定することができます。これは実質的にゲートウェイの利用配分を決めているのと同じです。

FAULT_TOLERANCE モードでは、2 つの thingId に対して優先順位を指定することができます。通常は優先順位が高いゲートウェイのルートを使ってデバイスにアクセスしますが、そのゲートウェイがオフラインと判定されると、もう一方のゲートウェイのルートを使ってアクセスします。さらに、一定時間経過後に自動フェイルバック、つまり、優先順位が高いほうのゲートウェイを使うよう、ルートを元に戻すことができます。

getTeamings()

このメソッドは、登録済みのチーミングデバイスの一覧を取得します。このメソッドは、Promise オブジェクトを返します。

このメソッドには、引数はありません。

サンプルコード
dSymphony.getTeamings().then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "teamingList": [
    {
      "thingId": "th-2978C5C3686A50FBBA078438930B12FE",
      "mode": "AGGREGATION",
      "teamedDeviceList": [
        {
          "thingId": "th-DF069858E95F1BB895D97006BAC7F6AA",
          "weight": 20,
          "metric": null,
          "isFailback": null,
          "failbacktime": null,
          "state": null
        },
        {
          "thingId": "th-0B57BD0C829BFDF6E5D60403579A0CF5",
          "weight": 80,
          "metric": null,
          "isFailback": null,
          "failbacktime": null,
          "state": null
        }
      ]
    }
  ]
}

レスポンス情報のうち、主要な値の意味は以下のとおりです。

レスポンス
プロパティ名 型 説明
teamingList Array チーミング情報を表す TeamingInfo オブジェクトのリスト。

createTeaming()

このメソッドは、チーミングデバイスを新規に生成します。このメソッドは Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
mode String 必須 AGGREGATION, FAULT_TOLERANCE のいずれか。
thingId1 String 必須 1 つ目のデバイスのシング ID。
wight1 Integer 条件付き 1 つ目のデバイスのリクエスト配分。mode が AGGREGATION の場合のみ有効かつ必須です。リクエスト配分は 0 ～ 100 の整数で指定してください。
metric1 Integer 条件付き 1 つ目のデバイスの優先順位。mode が FAULT_TOLERANCE の場合のみ有効かつ必須です。優先順位は 1 か 2 のいずれかを指定してください。
isFailbackEnabled1 Boolean 条件付き 1 つ目のデバイスの自動フェイルバック有効フラグ。mode が FAULT_TOLERANCE の場合のみ有効かつ必須です。自動ファイルバックを有効にするなら true を、無効にするなら false をセットしてください。
failbackTime1 Integer 条件付き 1 つ目のデバイスの自動フェイルバック周期。mode が FAULT_TOLERANCE で、かつ、自動フェイルバックが有効の場合のみ、有効かつ必須です。単位は秒で、60 ～ 86400 の整数で指定してください。
thingId2 String 必須 2 つ目のデバイスのシング ID。
wight2 Integer 条件付き 2 つ目のデバイスのリクエスト配分。
metric2 Integer 条件付き 2 つ目のデバイスの優先順位。
isFailbackEnabled2 Boolean 条件付き 2 つ目のデバイスの自動フェイルバック有効フラグ。
failbackTime2 Integer 条件付き 2 つ目のデバイスの自動フェイルバック周期。

次のサンプルコードは AGGREGATION モードでチーミングデバイスを登録します。

サンプルコード
dSymphony.createTeaming({
  // モード
  mode     : 'AGGREGATION',
  // デバイス1
  thingId1 : 'th-0B57BD0C829BFDF6E5D60403579A0CF5',
  weight1  : 80,
  // デバイス2
  thingId2 : 'th-DF069858E95F1BB895D97006BAC7F6AA',
  weight2  : 20
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "thingId": "th-2978C5C3686A50FBBA078438930B12FE"
}

このように、チーミングデバイスを新規に生成すると、新たに thingId が割り当てられます。以降、その thingId を使うことで、あたかも 1 つのデバイスかのように操作することができます。

次のサンプルコードは FAULT_TOLERANCE モードでチーミングデバイスを登録します。

サンプルコード
dSymphony.createTeaming({
  // モード
  mode               : 'FAULT_TOLERANCE',
  // デバイス1
  thingId1           : 'th-0B57BD0C829BFDF6E5D60403579A0CF5',
  metric1            : 1,
  isFailbackEnabled1 : true,
  failbackTime1      : 300,
  // デバイス2
  thingId2           : 'th-DF069858E95F1BB895D97006BAC7F6AA',
  metric2            : 2,
  isFailbackEnabled2 : true,
  failbackTime2      : 300
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

deleteTeamings()

このメソッドは、登録済みのすべてのチーミングデバイスをまとめて削除 (解除) します。このメソッドは、Promise オブジェクトを返します。

このメソッドには、引数はありません。

サンプルコード
dSymphony.deleteTeamings().then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null
}

getTeaming()

このメソッドは、チーミング ID からチーミングデバイス情報を取得します。このメソッドは Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 チーミングデバイスのシング ID。
サンプルコード
dSymphony.getTeaming({
  thingId: 'th-2978C5C3686A50FBBA078438930B12FE'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "teamingInfo": {
    "thingId": "th-2978C5C3686A50FBBA078438930B12FE",
    "mode": "AGGREGATION",
    "teamedDeviceList": [
      {
        "thingId": "th-0B57BD0C829BFDF6E5D60403579A0CF5",
        "weight": 80,
        "metric": null,
        "isFailbackEnabled": null,
        "failbackTime": null,
        "state": null
      },
      {
        "thingId": "th-DF069858E95F1BB895D97006BAC7F6AA",
        "weight": 20,
        "metric": null,
        "isFailbackEnabled": null,
        "failbackTime": null,
        "state": null
      }
    ]
  }
}

レスポンス情報のうち、主要な値の意味は以下のとおりです。

レスポンス
プロパティ名 型 説明
teamingInfo Array チーミングデバイス情報を表す TeamingInfo オブジェクト。

updateTeaming()

このメソッドは、チーミングデバイスを設定変更を行います。チーミングデバイスとしてセットされた 2 つのデバイスを組み替えることはできません。このメソッドは Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 対象のチーミングデバイスの thingId。
mode String 必須 AGGREGATION, FAULT_TOLERANCE のいずれか。
thingId1 String 必須 1 つ目のデバイスのシング ID。必ず対象のチーミングデバイスを登録した際に指定したシング ID を指定してください。
wight1 Integer 条件付き 1 つ目のデバイスのリクエスト配分。mode が AGGREGATION の場合のみ有効かつ必須です。リクエスト配分は 0 ～ 100 の整数で指定してください。
metric1 Integer 条件付き 1 つ目のデバイスの優先順位。mode が FAULT_TOLERANCE の場合のみ有効かつ必須です。優先順位は 1 か 2 のいずれかを指定してください。
isFailbackEnabled1 Boolean 条件付き 1 つ目のデバイスの自動フェイルバック有効フラグ。mode が FAULT_TOLERANCE の場合のみ有効かつ必須です。自動ファイルバックを有効にするなら true を、無効にするなら false をセットしてください。
failbackTime1 Integer 条件付き 1 つ目のデバイスの自動フェイルバック周期。mode が FAULT_TOLERANCE で、かつ、自動フェイルバックが有効の場合のみ、有効かつ必須です。単位は秒で、60 ～ 86400 の整数で指定してください。
thingId2 String 必須 2 つ目のデバイスのシング ID。
wight2 Integer 条件付き 2 つ目のデバイスのリクエスト配分。
metric2 Integer 条件付き 2 つ目のデバイスの優先順位。
isFailbackEnabled2 Boolean 条件付き 2 つ目のデバイスの自動フェイルバック有効フラグ。
failbackTime2 Integer 条件付き 2 つ目のデバイスの自動フェイルバック周期。
サンプルコード
dSymphony.updateTeaming({
  thingId  : 'th-2978C5C3686A50FBBA078438930B12FE',
  mode     : 'AGGREGATION',
  thingId1 : 'th-0B57BD0C829BFDF6E5D60403579A0CF5',
  weight1  : 30,
  thingId2 : 'th-DF069858E95F1BB895D97006BAC7F6AA',
  weight2  : 70
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null
}

deleteTeaming()

このメソッドは、チーミングデバイスを削除 (解除) します。このメソッドは Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 対象のチーミングデバイスの thingId。
サンプルコード
dSymphony.deleteTeaming({
  thingId  : 'th-2978C5C3686A50FBBA078438930B12FE'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null
}
アプリケーション開発