アプリケーション開発

ロール管理 API

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

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

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

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

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

`getRoles()`

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

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

サンプルコード

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

このメソッドの実行が成功すると、コールバック関数には 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`	SymphonyArray	ロール情報を表す `RoleInfo`オブジェクトのリスト。

`createRole()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleName`	String	必須	ロール名。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleName", "Hue Light #1 ON")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null,
  "roleId": "rl-A90CB1300A236F4B6DF3C1EB0ED55D19"
}

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

レスポンス

プロパティ名	型	説明
`roleId`	SymphonyArray	新たに生成されたロールの ID。

`deleteRoles()`

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

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

サンプルコード

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

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

レスポンスの例

{
  "result": 0,
  "error": null
}

`updateRole()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleId`	String	必須	ロール ID。
`roleName`	String	必須	ロール名。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-38041C30F4C08F741748D2C5B4CC105C")
    .put("roleName", "Hue Light #1 点灯")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null
}

`deleteRole()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleId`	String	必須	ロール ID。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-38041C30F4C08F741748D2C5B4CC105C")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null
}

`getRolePermissions()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleId`	String	任意	ロール ID。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-964BBB96F1ECCC7648CCDC5F5FDC420F")
    .build();

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

このメソッドの実行が成功すると、コールバック関数には 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`	SymphonyArray	パーミッション情報を表す `PermissionInfo` オブジェクトのリスト。

`createRolePermission()`

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

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

パラメータ

プロパティ名	型	必須	説明
`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 のみ利用可能な権限) のいずれか。

サンプルコード

SymphonyObject rangeCondition = new SymphonyObject.Builder()
    .put("from", "2018-03-01T00:00:00+09:00")
    .put("to", "2018-04-01T00:00:00+09:00")
    .build();
SymphonyObject timeCondition = new SymphonyObject.Builder()
    .put("once", rangeCondition)
    .build();
SymphonyObject permission = new SymphonyObject.Builder()
    .put("term", timeCondition)
    .build();
SymphonyArray permissions = new SymphonyArray.Builder()
    .add(permission)
    .build();
SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-964BBB96F1ECCC7648CCDC5F5FDC420F")
    .put("thingId", "th-A7E2F85D264D52E8F2EA0B507D8CCA57")
    .put("additional", permissions)
    .put("policy", "DeviceFullAccess")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null,
  "permissionId": "pm-96803FB6E14D2FD3F8DDD58998C31796"
}

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

レスポンス

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

`deleteRolePermissions()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleId`	String	必須	ロール ID。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-964BBB96F1ECCC7648CCDC5F5FDC420F")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null
}

`deleteRolePermission()`

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

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

パラメータ

プロパティ名	型	必須	説明
`roleId`	String	必須	ロール ID。
`permissionId`	String	必須	パーミッション ID。

サンプルコード

SymphonyObject params = new SymphonyObject.Builder()
    .put("roleId", "rl-964BBB96F1ECCC7648CCDC5F5FDC420F")
    .put("permissionId", "pm-96803FB6E14D2FD3F8DDD58998C31796")
    .build();

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

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

レスポンスの例

{
  "result": 0,
  "error": null
}