アプリケーション開発

ロール管理 API

Symphony では、共有ユーザーとして登録されたユーザーに対して、自分のゲートウェイ配下のデバイスにアクセスする権限を与える仕組みを提供します。共有ユーザーの管理については「ユーザー管理 API」の章をご覧ください。

共有ユーザーに付与する役割を「ロール」と呼びます。たとえば、ライトを制御する役割を作るとします。ライトの制御には、ライトをつける、ライトを消す、という機能の権限が必要になります。また、その権限には今日限りといった期限を設けたいこともあるでしょう。このように、どのデバイスのどの機能を、どのような利用条件 (「付帯条件」と呼びます) で共有ユーザーに使わせるかを定義します。この機能及び利用条件を「パーミッション」と呼びます。そして、1 つのロールの中に、それに関連するパーミッションを追加していきます。最後に、そのロールを共有ユーザーに割り当てることで、その共有ユーザーは、指定された条件で指定の機能だけ利用できるようになります。

ロール作成および共有ユーザーへのロールの割り当ての手順は以下の通りです。

  1. createRole() メソッドを使ってロールを生成します。この時点では、そのロールには何もパーミッションが定義されていません。また、どの共有ユーザーにも関連付けられていません。単に箱を作っただけです。
  2. createRolePermission() メソッドを使って、どのデバイスのどのサービスをどのような条件で使えるようにするかを定義したパーミッションをロールに追加します。必要に応じて、複数のパーミッションを追加していきます。
  3. 最後に、ユーザー管理の setShareUserRoles() メソッドを使って、生成したロールを共有ユーザーに割り当てます。

ロールが共有ユーザーに割り当てられると、共有ユーザー側では、getDevices(), getDevice(), getActions() メソッドなどを使って、あたかも自分のデバイスかのように、あなたのデバイスやアクションが見えるようになり、requestAction(), request() メソッドを使って、アクションを実行することができます。

getRoles()

このメソッドは、登録済みのロールを検索します。このメソッドは、Promise オブジェクトを返します。

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

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

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "roleList": [
    {
      "roleId": "rl-A68023F982DE365646789D50AEA0548A",
      "roleName": "Hue Light #1 ON",
      "permissionList": [
        {
          "permissionId": "pm-992584384AD382C3B82DDDD3A606E8FB",
          "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
          "actionId": null,
          "additional": {
            "term": [
              {
                "once": {
                  "from": "2018-03-01T00:00:00+09:00",
                  "to": "2018-04-01T00:00:00+09:00"
                },
                "weekly": null,
                "everyday": null
              }
            ],
            "location": [],
            "number": []
          },
          "policy": "DeviceFullAccess"
        }
      ],
      "userId": "wNrFkaOg"
    }
  ]
}

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

レスポンス
プロパティ名 型 説明
roleList Array ロール情報を表す RoleInfoオブジェクトのリスト。

createRole()

このメソッドは、ロールを新規に生成します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleName String 必須 ロール名。
サンプルコード
dSymphony.createRole({
  roleName : 'Hue Light #1 ON'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "roleId": "rl-A90CB1300A236F4B6DF3C1EB0ED55D19"
}

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

レスポンス
プロパティ名 型 説明
roleId Array 新たに生成されたロールの ID。

deleteRoles()

このメソッドは、すべてのロールをまとめて削除します。このメソッドは、Promise オブジェクトを返します。

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

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

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

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

updateRole()

このメソッドは、ロールの名前を変更します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 必須 ロール ID。
roleName String 必須 ロール名。
サンプルコード
dSymphony.updateRole({
  roleId   : 'rl-38041C30F4C08F741748D2C5B4CC105C',
  roleName : 'Hue Light #1 点灯'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

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

deleteRole()

このメソッドは、ロールを削除します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 必須 ロール ID。
サンプルコード
dSymphony.deleteRole({
  roleId : 'rl-38041C30F4C08F741748D2C5B4CC105C'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

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

getRolePermissions()

このメソッドは、指定のロールに登録されているパーミッション情報を取得します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 任意 ロール ID。
サンプルコード
dSymphony.getRolePermissions({
  roleId : 'rl-964BBB96F1ECCC7648CCDC5F5FDC420F'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "permissionList": [
    {
      "permissionId": "pm-96803FB6E14D2FD3F8DDD58998C31796",
      "roleId": "rl-964BBB96F1ECCC7648CCDC5F5FDC420F",
      "thingId": "th-A7E2F85D264D52E8F2EA0B507D8CCA57",
      "actionId": null,
      "userId": "wNrFkaOg",
      "additional": {
        "term": [
          {
            "once": {
              "from": "2018-03-01T00:00:00+09:00",
              "to": "2018-04-01T00:00:00+09:00"
            },
            "weekly": null,
            "everyday": null
          }
        ],
        "location": [],
        "number": []
      },
      "policy": "DeviceFullAccess"
    }
  ]
}

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

レスポンス
プロパティ名 型 説明
permissionList Array パーミッション情報を表す PermissionInfo オブジェクトのリスト。

createRolePermission()

このメソッドは、ロールにパーミッションを新規に追加します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 必須 ロール ID。
thingId String 条件付き 共有ユーザーに利用を許可したいデバイスのシング ID。thingId を指定した場合は、該当のデバイスのすべてのアクションの利用を許可することになります。また、同時に actionId を指定することはできません。
actionId String 条件付き 共有ユーザーに利用を許可したいアクションのアクション ID。actionId を指定した場合は、同時に thingId を指定することはできません。
additional Object 必須 パーミッションを与える付帯条件を格納した PermissionAdditionalInfoオブジェクト。
policy String 必須 DeviceFullAccess (デバイス API のフルアクセス権限)、ArchiveFullAccess (アーカイブ API のフルアクセス権限)、ArchiveReadWrite (アーカイブ API の GET、PUT API のみ利用可能な権限)、ArchiveReadOnly (アーカーブ API のGET API のみ利用可能な権限) のいずれか。
サンプルコード
dSymphony.createRolePermission({
  roleId     : 'rl-964BBB96F1ECCC7648CCDC5F5FDC420F',
  thingId    : 'th-A7E2F85D264D52E8F2EA0B507D8CCA57',
  additional : [{
    term : {
      once : {
        from : '2018-03-01T00:00:00+09:00',
        to   : '2018-04-01T00:00:00+09:00'
      }
    }
  }],
  policy     : 'DeviceFullAccess'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

レスポンスの例
{
  "result": 0,
  "error": null,
  "permissionId": "pm-96803FB6E14D2FD3F8DDD58998C31796"
}

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

レスポンス
プロパティ名 型 説明
permissionId Array 新たに生成されたパーミッションの ID。

deleteRolePermissions()

このメソッドは、指定のロールからすべてのパーミッションを削除します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 必須 ロール ID。
サンプルコード
dSymphony.deleteRolePermissions({
  roleId : 'rl-964BBB96F1ECCC7648CCDC5F5FDC420F'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

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

deleteRolePermission()

このメソッドは、1 つのパーミッションを個別に削除します。このメソッドは、Promise オブジェクトを返します。

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

パラメータ
プロパティ名 型 必須 説明
roleId String 必須 ロール ID。
permissionId String 必須 パーミッション ID。
サンプルコード
dSymphony.deleteRolePermission({
  roleId       : 'rl-964BBB96F1ECCC7648CCDC5F5FDC420F',
  permissionId : 'pm-96803FB6E14D2FD3F8DDD58998C31796'
}).then(function (res) {
  console.log(JSON.stringify(res, null, '  '));
}).catch(function (error) {
  console.error(error);
});

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

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