Specification Manager - TakayukiHoshi1984/DeviceConnect-Docs GitHub Wiki

Device Connect Manager

Device Connect Managerは、OMA GotAPI v1.1で定義されているGotAPI Serverを実装したアプリケーションになります。

Device Connectシステムを使用するアプリケーションは、このDevice Connect Managerにアクセスして、様々なデバイスを操作します。

Device Connect セキュリティ

Device Connect Managerでは、GotAPIのセキュリティ以外にも以下の制限を設けています。

外部IPを許可

Device Connect Managerは、127.0.0.1(localhost)以外の外部IPからのアクセスを許可することができます。

外部IPからのアクセスを許可している場合には、Device Connect Managerがインストールされている端末と同じネットワーク内のPC端末などから操作を行うことができます。

構成図

外部IPからのアクセスを許可する場合には、意図しない人からのアクセスが考えられますので、デフォルトでは無効に設定してあります。

ただし、機能にアクセスしようとした時点で、アプリケーション認可機能がDevice Connect Managerがインストールされている端末で実行され認可が求められます。
よって、認可を受けていない外部IPからのアクセスでは、操作することはできません。

ポート監視

Device Connect Managerで使用するポートを監視を行い、Device Connect Manager以外のアプリケーションが起動している場合には、警告を表示してユーザに確認を行います。

ユーザは、Device Connect Manager以外のアプリがポートを使用していることに気がつくことができ、Device Connect Managerになりすましをしているアプリケーションを発見することができるようになります。

iOSでは、バックグラウンドでアプリケーションが動作することができないため、他のアプリケーションがなりすましすることができません。よって、この機能はAndroidにのみの仕様になります。

Device Connect API

各サービスの機能にアクセスするために定義したAPIです。

Device Connect API は、プロファイル単位で Swagger 2.0 で規定されるフォーマットで記述します。
各プロファイルの定義は、こちらを参照してください。

また、アプリケーションは、ServiceInformation APIで、その定義を取得することができ、サービスがサポートしているAPIを確認することができます。

新規APIを作成する場合には、API作成ガイドラインを参照してください。

リクエストの定義

リクエストは、RESTの仕様であるArchitectural Styles and the Design of Network-based Software Architectures CHAPTER 5 Representational State Transfer (REST)を参考にして、Device Connect APIを定義します。

共通パラメータ

アプリケーションはリクエストを送信する際、下記のパラメータが必要になります。

論理名 物理名 データ型 省略 設定値
アクセストークン accessToken string 右記参照 Authorization APIで取得したアクセストークン。
Availability API、Authorization APIのみ省略可。それ以外のAPIでは必須。
GotAPIの仕様のため、詳細はこちらを参照してください。
ワンタイムトークン nonce string ○ HMAC生成用のワンタイムトークン。
GotAPIの仕様のため、詳細はこちらを参照してください。

なお、 Device Connect Managerでは、設定画面において、アプリケーション認可機能の有効/無効を切り替えることができます。
アプリケーション認可機能が無効に設定されている場合には、accessTokenを省略することができます。

HTTPメソッド一覧

Device Connect APIでは以下のHTTPメソッドをサポートしています。

HTTPメソッド
GET
PUT
POST
DELETE

HTTP アクセス制御 (CORS)に対応するために、OPTIONSヘッダについては、Webサーバ側でレスポンスを返却します。

Access-Control-Allow-Origin: *

Device Connect Managerは、CORSのレスポンスで全てのOriginに対して許可を行います。

レスポンス定義

Device Connect APIへのリクエストに対するレスポンスは、以下の値を返します。

  • ステータスコードは、200で返します。
  • HTTPレスポンスヘッダのcontent typeには、application/jsonを返します。
  • HTTPレスポンスボディには、JSONを返します。

ただし、リソースにアクセスを行うfilesなどへのリクエストに対しては、バイナリを返却します。

共通パラメータ

Device Connect Managerからのレスポンスには以下のパラメータが返却される。

論理名 物理名 データ型 省略 備考
処理結果 result 数値 - 0:正常応答
0以外:異常応答
プロダクト名 product 文字列 - 処理を行った Device Connect Managerの名前
バージョン名 version 文字列 - 処理を行った Device Connect Managerのバージョン名
HMAC hmac 文字列 ○ Device Connect Managerの正当性を示すための署名。
アプリケーションが事前にHMAC生成鍵を送信していなかった場合は省略されます。

レスポンス例

{
    "product" : "Device Connect Manager",
    "version" : "2.0.0",
    "result" : 0,
    "playStatus" : {
        "mediaId" : "media001",
        "mimeType" : "audio/mp3",
        "status" : "play",
        "trackNo" : 5,
        "pos" : 80
    },
    "hmac" : "abcdef0123456789"
}

エラーレスポンス

リクエストに対するレスポンスは result が 0以外 のとき、以下の項目を含むレスポンスを返却します。

エラーレスポンスの共通パラメータ

論理名 物理名 データ型 備考
エラーコード errorCode 数値 エラーを識別するためのコード
エラーメッセージ errorMessage 文字列 エラーの内容
エラーレスポンス例
{
    "product" : "Device Connect Manager",
    "version" : "2.0.0",
    "result" : 1,
    "errorCode" : 1,
    "errorMessage" : "Unknown error."
}

エラーコード一覧

エラーコード エラー内容
1 原因不明のエラー
2 未サポートプロファイルエラー
3 未サポートアクション(HTTPメソッド)エラー
4 未サポートアトリビュートエラー
5 デバイスID未設定エラー
6 デバイス発見失敗エラー
7 タイムアウトエラー
8 未知のインターフェースへのアクセスエラー
9 バッテリー低下による操作不能エラー
10 不正なリクエストパラメータエラー
11 認証エラー
12 アクセストークン有効期限切れエラー
13 アクセストークン未設定エラー
14 スコープ外へのアクセスエラー
15 認証時にクライアントIDを発見できなかったエラー
16 デバイス状態異常エラー
17 サーバー状態異常エラー
18 リクエストの発行元が不正
19 リクエストURLが不正
20 Profile名が不正
21 リクエスト先のプラグインが無効
22 リクエスト先のプラグインの異常発生により連携停止中

イベント

WebSocketを使用して、ウェアラブルデバイスやIoTデバイスで発生するイベントを連続的に受信する機能を提供します。

WebSocketの接続

WebSocketに接続する際には、アクセストークンを送る必要があります。
アクセストークンが送られてくるまでは、接続されたとは認識せずにイベントの送信は行いません。

Open WebSocket

認可されたいないアクセストークンを送られてきた場合には、レスポンスに{"result": 1}を返却して、WebSocketを切断します。

Device Connect Managerにて、Local OAuthが無効にされている場合には、アクセストークンを送信しなくてもイベントの送信を行います。

WebSocketの切断

WebSocketが切断された時に、切断されたWebSocketのOriginを各プラグインに通知します。
プラグインでは、Originに紐づいていたイベントを必要に応じて解除するなどの後始末を行います。

Open WebSocket

イベント登録

プラグインに対して、イベントのAPIに対してPUT命令を行うことで、イベントを開始します。
WebSocketが接続されていても、イベント開始のAPIが呼び出されていない場合にはイベントの送信は行われません。

Open WebSocket

イベント解除

プラグインに対して、イベントのAPIに対してDELETE命令を行うことで、イベントを停止します。

Open WebSocket

イベントの解除は、他にもWebSocketが切断の通知でも行います。WebSocketが切れた時点でイベントが不要になったと判断し、プラグインは、イベントを停止します。

イベント通知

プラグインは、登録されたイベントが発生したタイミングで、Device Connect Managerに通知を行います。
Device Connect Managerでは、通知を受け取ったイベントを指定されたWebSocketに対して送信します。

Open WebSocket

リソースアクセス

アプリケーションとプラグイン間でのリソースのやりとりする機能を説明します。

リソース送信

アプリケーションからプラグインに対してリソースを送信する機能を提供します。

マルチパート

マルチパートのデータをDevice Connect Managerに送信することで、プラグインにリソースを送信します。

Device Connect Managerは、送られてきたマルチパートのデータをファイルに保存します。
Androidの場合には、ContentProvider経由でプラグインにファイルのデータを送信します。
iOSの場合には、同じアプリに同梱されていますので、NSFileHandle経由でプラグインにファイルのデータを送信します。

Open WebSocket
マルチパートサンプル
POST /canvas/drawImage HTTP/1.1
Host: localhost:4035
Content-Type: multipart/form-data;boundary=WebKitFormBoundaryp7MA4YWxkTrZu0gW
--WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="accessToken"

xxxxx
--WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data;name="serviceId"

localhost.deviceconnect.org
--WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="path"

/test/test.png
--WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="mimeType"

image/png
--WebKitFormBoundaryE19zNvXGzXaLvS5C
Content-Disposition: form-data; name="data"; filename="ic_launcher.png"
Content-Type: image/png

＜binary省略＞
--WebKitFormBoundaryE19zNvXGzXaLvS5C--

Webサーバ

アプリ側でWebサーバを用意して、そのURLをDevice Connect Manager経由でプラグインに渡します。
プラグインは、送られてきたURIからリソースを取得して、処理を行います。

Open WebSocket

リソース受信

Device Connect Manager経由

プラグイン側でファイルへのストリームをDevice Connect Managerに渡します。
Device Connect Managerは、自身のWebサーバのURIに変換して、アプリケーションに返却します。

Open WebSocket

Device Connect Managerとプラグイン間の通信は、Androidの場合には、ContentProvider、iOSの場合には、NSFileHandleを使用します。

Webサーバ経由

プラグイン側でWebサーバを起動して、そのURIをアプリケーションに返却します。

Sequence of Streaming data

アプリケーションは、レスポンスで受け取ったURIに対してアクセスを行い、リソースデータを受信します。

外部からの起動・停止

Device Connect Managerは、URLスキームを使用して起動と停止を操作することができます。

以下のURLスキームを呼び出すとDevice Connect Managerの起動・停止を行うことができます。

Android

  • Device Connect Manager 起動確認ダイアログを表示
<a href=intent://start/activity#Intent;scheme=gotapi;package=org.deviceconnect.android.manager;end">起動</a>

URLスキームを呼び出した時にManagerが起動している場合には、起動確認ダイアログは表示しません。

  • Device Connect Manager 停止確認ダイアログを表示
<a href="intent://stop/activity#Intent;scheme=gotapi;package=org.deviceconnect.android.manager;end">停止</a>

また、ユーザ確認なしでDevcie Connect Managerの起動・停止を行うこともできます。

  • Device Connect Manager 起動
<a href=intent://start/server#Intent;scheme=gotapi;package=org.deviceconnect.android.manager;end">起動</a>
  • Device Connect Manager 停止
<a href="intent://stop/server#Intent;scheme=gotapi;package=org.deviceconnect.android.manager;end">停止</a>

なお、本機能は、Device Connect Managerの設定画面で、有効・無効を設定することができます。
無効にされている場合には、勝手にDevice Connect Managerの起動・停止を行うことができずに、ユーザに対して確認を行う画面が表示されます。

iOS

  • Device Connect Manager 起動
<a href="gotapi://start?url={開いていたURL}"＞起動</a>
  • Device Connect Manager 停止
<a href="gotapi://stop"＞起動</a>

静的HTTPサーバーのページを表示

Android 版 Device Connect Manager は 静的HTTPサーバー も提供しますが、その ホスト名 (IP アドレスとポート番号の組み合わせ) はユーザーの設定によって変更されます。よって、基本的には、静的HTTPサーバーのホスト名は設定画面で確認しますが、ユーザーにとって若干の手間を要します。

そのホスト名を自動的に解決し、既定のブラウザ上で静的HTTPサーバーのページを表示するためのURIスキームを gotapi://shortcut として定義します。

$ adb shell am start -n org.deviceconnect.android.manager/.DConnectHostResolver -d gotapi://shortcut/path/to/page

上記のようなインテントを Device Connect Manager に対して送信すると、下記のようにURLを変換した上で、ブラウザで表示させることができます。

例: ホスト名が 192.168.x.x:8080 の場合
gotapi://shortcut/path/to/page
　↓
http://192.168.x.x:8080/path/to/page

⚠️ **GitHub.com Fallback** ⚠️