アプリケーション開発

アーカイブ管理 API

アーカイブ管理 API は、デバイスのアクションを実行した際にデバイスから返ってきたデータを保存するための API を提供します。デフォルトでは、すべてのアクションでアーカイブ化が未設定状態になっています。Symphony 側でレスポンスデータを保存したい場合は、アーカイブ化を開始します。その後、いつでも蓄積されたデータを条件を絞りながら取り出すことができます。

getArchiveDevices()

このメソッドは、アーカイブ可能なすべてのデバイスのアクションを取得します。この結果より、どのデバイスのどのアクションがアーカイブ可能か、また、現状のアーカイブ設定状態を確認することができます。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
state Integer 任意 設定状態。(0: 未設定, 1: 停止中, 2: 起動中)
サンプルコード
dSymphony.getArchiveDevices().thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "deviceList": [
    {
      "actionId": "ac-7A38F3E91034566581C54FA9D7D150D9",
      "summary": "Light On API (点灯)",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "deviceName": "Hue color lamp 1",
      "gatewayId": "gw-CAE3AB3F4F5A93733CF2451E720F2344",
      "gatewayName": "仕事部屋のゲートウェイ",
      "gatewayType": "hgw",
      "url": "/light:post",
      "state": 0,
      "isGatewayOnline": true
    },
    {
      "actionId": "ac-8D3574B38862F0219FCEB3DD0BE9F9B3",
      "summary": "Light Off API (消灯)",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "deviceName": "Hue color lamp 1",
      "gatewayId": "gw-CAE3AB3F4F5A93733CF2451E720F2344",
      "gatewayName": "仕事部屋のゲートウェイ",
      "gatewayType": "hgw",
      "url": "/light:delete",
      "state": 0,
      "isGatewayOnline": true
    },
    ...
  ]
}

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

レスポンス
プロパティ名 型 説明
deviceList SymphonyArray アーカイブ情報付きアクション情報を表す ArchiveActionInfo オブジェクトのリスト。

getArchiveDevice()

このメソッドは、thingId を指定して、該当のデバイスの中でアーカイブ可能なすべてのデバイスのアクションを取得します。この結果より、どのアクションがアーカイブ可能か、また、現状のアーカイブ設定状態を確認することができます。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 シング ID。
state Integer 任意 設定状態。(0: 未設定, 1: 停止中, 2: 起動中)
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .build();

dSymphony.getArchiveDevice(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "deviceList": [
    {
      "actionId": "ac-7A38F3E91034566581C54FA9D7D150D9",
      "summary": "Light On API (点灯)",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "deviceName": "Hue color lamp 1",
      "gatewayId": "gw-CAE3AB3F4F5A93733CF2451E720F2344",
      "gatewayName": "仕事部屋のゲートウェイ",
      "gatewayType": "hgw",
      "url": "/light:post",
      "state": 0,
      "isGatewayOnline": true
    },
    {
      "actionId": "ac-8D3574B38862F0219FCEB3DD0BE9F9B3",
      "summary": "Light Off API (消灯)",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "deviceName": "Hue color lamp 1",
      "gatewayId": "gw-CAE3AB3F4F5A93733CF2451E720F2344",
      "gatewayName": "仕事部屋のゲートウェイ",
      "gatewayType": "hgw",
      "url": "/light:delete",
      "state": 0,
      "isGatewayOnline": true
    },
    ...
  ]
}

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

レスポンス
プロパティ名 型 説明
deviceList SymphonyArray アーカイブ情報付きアクション情報を表す ArchiveActionInfo オブジェクトのリスト。

setArchiveDeviceState()

このメソッドは、thingId を指定してデバイス単位でまとめてアクションのアーカイブ化を開始または停止します。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 シング ID
state Integer 必須 設定状態。(0: 未設定, 1: 停止中, 2: 起動中)
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("state", 2)
    .build();

dSymphony.setArchiveDeviceState(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

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

getArchiveAction()

このメソッドは、thingId と actionId を指定して、該当のアクションのアーカイブ状態を取得します。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 シング ID
actionId String 必須 アクション ID
state Integer 任意 設定状態。(0: 未設定, 1: 停止中, 2: 起動中)
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("actionId", "ac-7A38F3E91034566581C54FA9D7D150D9")
    .build();

dSymphony.getArchiveAction(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "deviceInfo": {
    "actionId": "ac-7A38F3E91034566581C54FA9D7D150D9",
    "summary": "Light On API (点灯)",
    "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
    "deviceName": "Hue color lamp 1",
    "gatewayId": "gw-CAE3AB3F4F5A93733CF2451E720F2344",
    "gatewayName": "仕事部屋のゲートウェイ",
    "gatewayType": "hgw",
    "url": "/light:post",
    "state": 2,
    "isGatewayOnline": true
}

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

レスポンス
プロパティ名 型 説明
deviceInfo SymphonyArray アーカイブ情報付きアクション情報を表す ArchiveActionInfo オブジェクト。

setArchiveActionState()

このメソッドは、thingId と actionId を指定して該当のアクションのアーカイブ化を開始または停止します。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 必須 シング ID
actionId String 必須 アクション ID
state Integer 必須 設定状態。(0: 未設定, 1: 停止中, 2: 起動中)
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("actionId", "ac-7A38F3E91034566581C54FA9D7D150D9")
    .put("state", 1)
    .build();

dSymphony.setArchiveActionState(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

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

getArchiveRecordSummaries()

このメソッドは、アーカイブされたレコードの目録を取得します。データは含まれません。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 任意 シング ID。
actionId String 任意 アクション ID。
from String 任意 アーカイブ生成日時の検索開始日時。指定する日時形式は Java の Date オブジェクトが認識可能なものであれば、何でも構いません。(例：2018-03-09T00:00:00+09:00)
to String 任意 アーカイブ生成日時の検索終了日時。指定する日時形式は Java の Date オブジェクトが認識可能なものであれば、何でも構いません。(例：2018-03-10T00:00:00+09:00)
limit Integer 任意 取得するレコードの上限数。指定可能な値は 0 ～ 100000。指定がなければ 100 が指定されたものとして処理されます。
order String 任意 アーカイブ生成日の並び順。指定可能な値は asc (昇順), desc (降順) のいずれか。ただし、日付のみがソート対象で、時間はソート対象になりません。
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("from", "2018-03-10T20:20:00+09:00")
    .put("to", "2018-03-10T20:30:00+09:00")
    .put("limit", 2)
    .build();

dSymphony.getArchiveRecordSummaries(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "summaryList": [
    {
      "recordId": "rcd-263588DC23812BF43E5D3D60EAB36F54",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "deviceName": "Hue color lamp 1",
      "actionId": "ac-8D3574B38862F0219FCEB3DD0BE9F9B3",
      "summary": "Light Off API (消灯)",
      "url": "/light:delete",
      "registerDate": "2018-03-10T20:22:15+09:00"
    },
    ...
  ]
}

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

レスポンス
プロパティ名 型 説明
summaryList SymphonyArray アーカイブのレコードの情報を表すオブジェクトのリスト。
recordId String レコード ID。
thingId String シング ID。
deviceName String デバイス名。
actionId String アクション ID。
summary String アクション概要。
url String デバイスコネクトにおけるアクションのリクエストパスとリクエストメソッド。
registerDate String データが保存された日時

getArchiveRecords()

このメソッドは、アーカイブされたレコードのデータを取得します。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingId String 任意 シング ID。
actionId String 任意 アクション ID。
from String 任意 アーカイブ生成日時の検索開始日時。指定する日時形式は Java の Date オブジェクトが認識可能なものであれば、何でも構いません。(例：2018-03-09T00:00:00+09:00)
to String 任意 アーカイブ生成日時の検索終了日時。指定する日時形式は Java の Date オブジェクトが認識可能なものであれば、何でも構いません。(例：2018-03-10T00:00:00+09:00)
limit Integer 任意 取得するレコードの上限数。指定可能な値は 0 ～ 100000。指定がなければ 100 が指定されたものとして処理されます。
order String 任意 アーカイブ生成日の並び順。指定可能な値は asc (昇順), desc (降順) のいずれか。ただし、日付のみがソート対象で、時間はソート対象になりません。
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("from", "2018-03-10T20:20:00+09:00")
    .put("to", "2018-03-10T20:30:00+09:00")
    .put("limit", 2)
    .build();

dSymphony.getArchiveRecords(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "recordDataList": [
    {
      "recordId": "rcd-263588DC23812BF43E5D3D60EAB36F54",
      "data": "{\"profile\":\"light\",\"attribute\":\"\",\"result\":0,\"statusCode\":200,\"product\":\"node-gotapi\",\"version\":\"0.3.3\",\"hmac\":\"4219f9a910334f640cf3b5703ac10b93585a121ad655cd3c5e545a83a706e28c\",\"serviceId\":\"hue-light-0017882C7D50-1\"}",
      "registerDate": "2018-03-10T20:22:15+09:00"
    },
    ...
  ]
}

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

レスポンス
プロパティ名 型 説明
recordDataList SymphonyArray アーカイブのレコードデータ情報を表すオブジェクトのリスト。
recordId String レコード ID。
data String 保存されたデータ。ゲートウェイから送られてきたデータがそのまま保存されています。データ形式は JSON です。
registerDate String データの保存日時。

deleteArchiveRecords()

このメソッドは、アーカイブされたデータを削除します。ただし、該当のアクションのアーカイブ状態が「起動中」(state が 2)の場合は削除できませんので注意してください。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
thingIdList SymphonyArray 任意 シング ID のリスト。
actionIdList SymphonyArray 任意 アクション ID のリスト。
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("thingIdList", new SymphonyArray.Builder().add("39897")build())
    .build();

dSymphony.deleteArchiveRecords(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

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

getArchiveRecord()

このメソッドは、レコード ID から保存されたデータを取得します。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
recordId String 必須 レコード ID。
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("recordId", "rcd-263588DC23812BF43E5D3D60EAB36F54")
    .build();

dSymphony.getArchiveRecord(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "record": {
    "recordId": "rcd-263588DC23812BF43E5D3D60EAB36F54",
    "data": "{\"profile\":\"light\",\"attribute\":\"\",\"result\":0,\"statusCode\":200,\"product\":\"node-gotapi\",\"version\":\"0.3.3\",\"hmac\":\"4219f9a910334f640cf3b5703ac10b93585a121ad655cd3c5e545a83a706e28c\",\"serviceId\":\"hue-light-0017882C7D50-1\"}",
    "registerDate": "2018-03-10T20:22:15+09:00"
  }
}

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

レスポンス
プロパティ名 型 説明
record String レコード情報を格納したオブジェクト。
recordId String レコード ID。
data String 保存されたデータ。ゲートウェイから送られてきたデータがそのまま保存されています。データ形式は JSON です。
registerDate String データの保存日時。

deleteArchiveRecord()

このメソッドは、レコード ID から該当のレコードを削除します。ただし、該当のアクションのアーカイブ状態が「起動中」(state が 2)の場合は削除できませんので注意してください。このメソッドは、CompletableFuture オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
recordId String 必須 レコード ID。
サンプルコード
SymphonyObject params = new SymphonyObject.Builder()
    .put("recordId", "rcd-263588DC23812BF43E5D3D60EAB36F54")
    .build();

dSymphony.deleteArchiveRecord(params).thenAccept(obj -> {
    Log.d(TAG, obj.toString());
}).exceptionally(ex -> {
    Log.e(TAG, "", ex);
    return null;
});

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

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