Specification
DeviceConnectAPIはスマートフォン上で仮想サーバとして動作するWebAPIで、様々なウェアラブルデバイスやIoTデバイスをWebブラウザやアプリから統一的な記述で簡単に利用することができる。
本ページでは、Device Connect RESTful APIの共通仕様について定義する。
DeviceConnect-JSはJavaScript版のDeviceConnectのライブラリである。
この文書のキーワード
- 「しなければならない（ MUST ）」
- 「してはならない（ MUST NOT ）」
- 「要求されている（ REQUIRED ）」
- 「することになる（ SHALL ）」
- 「することはない（ SHALL NOT ）」
- 「する必要がある（ SHOULD ）」
- 「しないほうがよい（ SHOULD NOT ）」
- 「推奨される（ RECOMMENDED ）」
- 「してもよい（ MAY ）」
- 「選択できる（ OPTIONAL ）」
は、RFC 2119に記述されているように解釈される。
シンプルで手軽なHTTPアクセスと、効率的なWebSocketによるイベント処理のパターン。
HTTP GET/POST/PUT/DELETEでの単純アクセス。
|HTTPメソッド|内容| |:--|:--|:--| |GET|デバイスあるいは、リソースの情報取得。| |POST|リソースの新規作成。デバイスの操作。| |PUT|デバイスあるいは、リソースの状態変更、設定。| |DELETE|リソースの削除。デバイスの電源OFF。|
例)
アクセスした瞬間の加速度センサーの値を取得（繰り返し値が欲しい場合はポーリング)
PUT/DELETE, WebSocketでのイベント処理
例)
加速度センサーの値に変化があった瞬間の値を連続的に自動取得
PUT/DELETE, URIの直接参照
例)
カメラ映像を要求した場合に、OSやGotAPIの内部構造を経由せずに映像リソースとしてアプリから直接利用
ProfileのAPI仕様書において、リクエストのRESTは、Architectural Styles and the Design of Network-based Software Architectures CHAPTER 5 Representational State Transfer (REST)に基づいたフォーマットで定義している。
アプリケーションはリクエストを送信する際、下記のパラメータを含めること。
| 論理名 | 物理名 | データ型 | 省略 | 設定値 |
|---|---|---|---|---|
| アクセストークン | accessToken | string | 右記参照 | Authorization Create Access Token APIで取得したアクセストークン。Availability APIのみ省略可。それ以外のAPIでは必須。GotAPIの仕様のため、詳細はこちらを参照。 |
- サービスIDを除くリクエストパラメータは、URLエンコードすること。
- マルチパートで送信できるファイルは1つのみなので、その点を考慮した実装をすること。
- HTTPリクエストにマルチパートとuriパラメータを同時に指定した場合、マルチパートが優先され、uriパラメータによるファイル指定は無視されます。
- 各プロファイルにアクセスするために、リクエストのパラメータとしてアクセストークンが必要になります。ただし、Availabilityプロファイル、Authorizationプロファイルは、例外的にアクセストークン無しでもアクセスすることができます。
- Formのデータを送っても、Queryのデータを送っても同じように処理されるが、Queryで送るバイナリーデータは非推奨としている。
| HTTPメソッド |
|---|
| GET |
| PUT |
| POST |
| DELETE |
例)Service Discovery API
GET http://localhost:4035/serviceDiscovery&accessToken=xxxxxxx
例)Notification API
POST http://localhost:4035/notification/notify?serviceId=取得済みサービスID&type=3&body=文字列&accessToken=xxxxxx
URIは、基本的に/api/profile/interface/attributeの4階層で定義される。
ただし、GETメソッドでPOST/PUT/DELETEを操作することもできるため、その場合は以下のように5階層になる。
/api/method/profile/interface/attribute
- profile以降は、profileを含め3階層以上は存在しない。
- method,interface,attributeは省略可能である(/api/profile, /api/profile/attribute)。
- interfaceが存在するときには、attributeは省略不可とする。
各パスのセグメントの説明は以下の通りである。
Device Connect APIは、POSTやPUT,DELETEのAPIをGETで代替操作を行うことができる。
リクエストURIの以下のmethodの場所にget,post,put,deleteを指定することで代替操作を行うことができる。
methodが指定できるのはHTTPメソッドがGETのときのみである。
HTTPメソッドがGET以外のときにリクエストURLにmethodが指定された場合は、リクエストURIが不正であるエラーを返す。
ただし、マルチパートには対応していないため、エラーコード10の不正なリクエストパラメータエラーを返す。
例)
正：GET http://localhost:4035/gotapi/post/humanDetect/detection/body?serviceId=xxxxxx&accessToken=yyyyy
誤：POST http://localhost:4035/gotapi/get/serviceDiscovery
Device Connect APIが使用するAPIの名前を指している。 OMAのGotAPIを元にしているため、apiは「gotapi」を指定している。
例)
- GET http://localhost:4035/gotapi/availability
Device Connect APIは、ユニークな機能ごとにそれぞれprofile名を割り当てる。 Device Connect APIのprofile名は、ローワキャメルケースで定義する。
例)
- GET http://localhost:4035/gotapi/airConditioner?serviceId=xxxxxxx&accessToken=yyyyy
Device Connect APIで提供されるプロファイルで、細分化できる機能がある場合にはinterfaceとして割り当てる。
Device Connect APIのinterface名は、ローワキャメルケースで定義する必要がある。
例)
- POST http://localhost:4035/gotapi/humanDetect/detection/body -d "serviceId=xxxxxx&accessToken=yyyyy"
Device Connect APIで提供されるプロファイルで、取得・操作が可能な属性を持つ場合にattributeとして割り当てる。
Device Connect APIのattribute名は、ローワキャメルケースで定義する必要がある。
例)
- GET http://localhost:4035/gotapi/battery/level?serviceId=xxxxxx&accessToken=yyyyy
- profile、interface、attributeの各セグメントは、以下のことを守らなければならない。
- ローワーキャメルケースで資料は統一しなければならない。
- スネークケースにはしてはならない。
- パスのセグメントに複数単語(2,3単語程度)がある時は、ローワーキャメルケースで単語をつなぎ合わせなければならない。
- 意味のない冗長な単語はなるべく削除する。
- URLにUnixやDOSなどのコマンド名を入れてはいけない。
ただし、Device Connectシステムでは、送られてきたprofile、interface、attributeの大文字小文字を無視して処理を行います。
例)単語の間に「_」や「-」で区切らないこと。
正: GET /gotapi/mediaPlayer
誤: GET /gotapi/media_player
GET /gotapi/media-player
例) Valueをとっても意味が通じるため、冗長である。
正: GET /gotapi/airConditioner/roomTemperature
誤: GET /gotapi/airConditioner/roomTemperatureValue
正: GET /gotapi/powermeter/integratedPower
誤: GET /gotapi/powermeter/integratedPowerValue
例) operationをとっても意味が通じるため、冗長である。
正: GET /gotapi/airConditioner/powerSaving
誤: GET /gotapi/airConditioner/operationPowerSaving
例) mkdirはUnixコマンドであるため使用できない。
正: POST /gotapi/file/directory
誤: POST /gotapi/file/mkdir
- 一般的な略語は使用してもよい。
- 一般的ではない略語、複数の意味がある略語については、Wikiなどに説明を追加しなければならない。
例)
- NFC,BLE
ROIは、「Region Of Image」の意味で使用しているが、「Return On Investment」などの略語の可能性もあるため、説明を追加する必要がある。 以下の例の場合も同様。
例)
- PUT /gotapi/tv
- PUT /gotapi/ecg/onECG
- GET /gotapi/gpio/export/pin[番号]
- 値の範囲が決まっているのならば、/profile/interface/attributeに数字などを使っても良い。
- 可変的な値をattributeなどに使用してはいけない。
- 推奨範囲として0〜10程度の数値を使用しても良い。
例)
- GET /gotapi/gpio/export/pin[番号]
- GET /gotapi/gpio/digital/pin[番号]
- POST /gotapi/gpio/digital/pin[番号]
- PUT /gotapi/gpio/digital/pin[番号]
- DELETE /gotapi/gpio/digital/pin[番号]
- GET /gotapi/gpio/analog/pin[番号]
- POST /gotapi/gpio/analog/pin[番号]
- 同じ綴りのAPIは用意しないようにする必要がある。
- 用意された場合、デバイスプラグイン側の実装により処理が異なる。
例)
- PUT /gotapi/ecg/onECG
- POST /gotapi/ecg/oneCg
- 造語、商品名などは、汎用性のない操作を定義する時に使用する必要がある。
例)
- PUT /gotapi/sphero/quaternion/onQuaternion
- GET /gotapi/tv/enlproperty
- わかりやすさ重視でRESTfulでも動詞をつかってもよい。
- attributeは動詞にしても良い。
- profileだけは名詞にすること。
例)
- POST /gotapi/notification/notify
- POST /gotapi/phone/call
- POST /gotapi/file/send
- 既存のDeviceConnectで定義されているProfileは、予約語とするため、独自Profileを定義するときは、既存のものを使用することはできない。
- 既存のProfileの拡張は、基本的には行えない。
- GitHubのISSUEとしてあげることで、変更が可能になる。
例)filesは予約語なので、使えない。
GET /gotapi/files
- W3C等の既存のAPIを参考にする場合は、それに沿った粒度・ネーミングにする必要がある。
- パス名 • リクエストパラメータ • レスポンスパラメータ程度を参考とする必要がある。
- ローワキャメルケースでない場合など、DeviceConnectの規則に従っていない場合は、従うように修正しなければならない。
例) GotAPI Authorization API
GET /gotapi/authorization/grant
GET /gotapi/authorization/accessToken
例) Mozilla Web Telephony API
POST /gotapi/phone/call
PUT /gotapi/phone/set
PUT /gotapi/phone/onConnect
DELETE /gotapi/phone/onConnect
例) W3C Vibration API
PUT /gotapi/vibration/vibrate
DELETE /gotapi/vibration/vibrate
- Event処理の設定のAPIはattributeがon〜となっている必要がある。
例)
- PUT /gotapi/battery/onChargingChange
- PUT /gotapi/connect/onWifiChange
- GotAPIで定義されているEvent処理のURIの中で、onがついていないものは、そちらを優先する必要がある。
- その場合は、定義されているattributeの頭にonをつけたURIを用意し、どちらのURIが要求された場合も処理を行う仕組みにしてもよい。
- 特に理由がない場合、Event処理のURIのattributeの頭にはonをつけなければならない。
例) GotAPIで定義されている
- PUT /gotapi/health/heart
↓
このようなURIが要求された場合も処理を行わせるようにしてもよい。
- PUT /gotapi/health/onHeart
- Streaming Dataは、Event処理のように見えるが、参照先を返すだけなので、onをつける必要はない。
例)
- PUT /gotapi/mediaStreamRecording/preview
- PUT /gotapi/omnidirectionalImage/roi
ProfileのAPI仕様書において、以下のようなレスポンス、メッセージは本資料下部の例のようなJSONとして返される。 各Profileで対応できないレスポンスのパラメータは、省略すること。 例えば、下記の例で言うとmimeTypeを判別できないデバイスの場合には、mimeTypeが省略されたレスポンスが返される。
Device Connect Managerはレスポンスを返却する際に下記のパラメータを含める。デバイスプラグイン側で含める必要はない。
| 論理名 | 物理名 | データ型 | 省略 | 設定値 |
|---|---|---|---|---|
| マネージャ名 | product | string | - | Device Connect Managerの名前。 |
| バージョン | version | string | - | Device Connect Managerのバージョン名。 |
| HMAC | hmac | string | 右記参照 | Device Connect Managerの正当性を示すための署名。アプリケーションが事前にHMAC生成鍵を送信していなかった場合は省略される。 |
| 処理結果 | result | number | - | 0:正常応答 0以外:異常応答 |
| 論理名 | 物理名 | データ型 | 備考 | |
| イベントオブジェクト | playStatus | object | イベントの内容を保持するオブジェクト | |
| メディアID | mediaId | String | レコードが開始されたメディアのマイムタイプ。このタイプで、動画、音声などを識別する。 | |
| マイムタイプ | mimeType | String | レコードが開始されたメディアのマイムタイプ。このタイプで、動画、音声などを識別する。 | |
| 再生状態 | status | String | ・"play" 再生 ・"mute" ミュート ・"unmute" ミュート解除 ・"pause" 一時停止 ・"resume" 一時停止解除 |
|
| トラック番号 | trackNo | number | ||
| トラック内の再生位置 | pos | number | トラックの再生位置を秒単位で返す。 | |
{
"product":"Device Connect Manager",
"version":"x.x",
"result":0,
"playStatus":{
"mediaId":"mid001",
"mimeType":"audio/mp3",
"status":"play",
"trackNo":5,
"pos":80
}
}
ProfileのAPI仕様書において、リクエストに対するレスポンスは result が 0以外 のとき、以下の項目を含む。
| 論理名 | 物理名 | データ型 | 説明 |
|---|---|---|---|
| エラーコード | errorCode | int | エラー番号 |
| エラーメッセージ | errorMessage | NSString* | エラー内容 |
| エラーコード | エラー内容 |
|---|---|
| 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名が不正 |
DeviceConnectでは、リソースへのアクセス方法として、Webサーバを利用する場合とfilesプロファイルを利用する場合の二つの場合がある。ここでは、それぞれの場合のリソースへのアクセス方法について説明する。
Device Connect APIでは、レスポンスにURIを返却して、アプリから直接デバイスプラグインが立ち上げたサーバにアクセスして、リソースを提供することができる。
以下にWebサーバを利用したリソースの受信についての流れを記す。
- デバイスプラグインは、デバイスから取得したデータをWebサーバのドキュメントルートとして用意されている、端末内のフォルダにファイルとして保存し、そのURIを返却する。
- UIアプリは、返却されたURIに対してデータを取得することで、ファイルのデータを取得することができる。
DeviceConnectAPIでは、クライアント側にサーバを用意する機能を持たないため、Webサーバによるリソースの送信は非推奨としている。
デバイスにあるリソースを取得する方法として、filesプロファイルを使用する方法がある。
各デバイスプラグインが持っているリソースにアクセスするために、DeviceConnectManagerのFilesプロファイルを使用している。
JavaScriptからは、リソースを直接操作することができない。そのために、URIという形にして返却することになる。
そのために、File Receive APIでファイルを取得する際には、Filesプロファイルを経由して取得できるURIにしている。
JavaScriptでは、取得したURIが画像の場合には、imgタグのsrcに設定して画像を表示する。
テキストの場合には、XMLHttpRequestでテキストを取得する。
ここでは、FilesプロファイルをFileProviderという形で表現している。FileProviderは、Android側のFilesProfileを実現しているクラスで、デバイスプラグインで一時的にファイルを保持する機能を持つ。Android側では、FileProviderを使ってDeviceConnectManagerでファイルを送受信を行なっている。iOS側では、NSFileHandleあるいは、AssetsLibraryを使用してファイルの送受信を行なっている。
デバイスにあるリソースをUIアプリから取得する場合の処理の流れを説明する。
ここでのリソースは、デバイスが持っているデータであり、カメラであれば写真データあるいは動画データである。ここでは、配信中のストリーミングデータなどは扱わない。
ファイルのリストは、File List APIで取得することができる。
詳しくは、FileProfileのWikiを参照すること。
- デバイスプラグインは、デバイスから取得したデータを端末内のフォルダにファイルとして保存し、そのURIを返却する。
- DeviceConnectManagerでは、返却されたURIをFilesプロファイルで取得できるURIに変換しUIアプリに返却する。
- UIアプリは、返却されたURIに対してデータを取得することで、ファイルのデータを取得することができる。
UIアプリからデバイスへバイナリデータを送信する場合の処理の流れを説明する。
- UIアプリからDeviceConnectManagerへはマルチパートを使いデータを送信する(すでにアップロードしたデータのURIを渡すことでもデータの送信が可能)。
- DeviceConnectManagerは、送られてきたマルチパートのデータを解析し、バイナリデータ部分をFileProviderに保存してURIを作成する。
- 作成したURIをDeviceConnectメッセージに格納し、デバイスプラグインへ通知する。
- デバイスプラグインでは、FileProviderを経由してバイナリデータを取得し、デバイスに送信する。
| マルチパートサンプル |
|---|
| 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 |
以下に大まかなシーケンス図を示す。
デバイスの情報を、デバイスプラグインを通じて、非同期でHTMLアプリへ配信する機能である。
例えば、ネットワーク検知情報、センサーイベント情報、楽曲再生状態変更(再生/一時停止/再開/停止)情報などの配信情報を指す。イベントの受信を開始するためには、それぞれのプロファイルで定義されているEvent APIをHTMLアプリ側で実行する。
イベントは、WebSocketを通して配信される。WebSocketを開く時に、識別子としてアクセストークンの指定が必要になる。アクセストークンの値は、基本的にAuthorizationで取得した値を指定することが推奨される。ただし、Authorizationを使用していない場合のアクセストークンの値は、可能なかぎり長くランダムな文字列とすることが推奨される。
WebSocketを開く時に指定したアクセストークンは、イベントの配信先の識別子とするために、イベントを登録・解除するときにも指定が必要となる。ただし、WebSocketを閉じる時には必要ない。
アクセストークンを取り直した場合には、WebSocketも作り直す必要があるため、注意すること。
- UIアプリ側でイベントを受け取るためのWebSocketを開く。
- DeviceConnectManagerにイベントの配信登録をする。
- イベントの配信登録を受け取ったデバイスプラグインはデバイスに対してイベント配信要求をする。
- WebSocketを通じて、デバイスからデータを受け取ったデバイスプラグインが配信しているデータを受け取る。
- イベントを停止する場合は、DeviceConnectManagerにイベントの配信解除をする。
- イベントの配信解除を受け取ったデバイスプラグインは、デバイスに対してイベント配信停止要求をする。
- イベントの配信を完全に終了する場合は、WebSocketを閉じる。
イベントのフォーマットについては、[こちら](https://github.com/DeviceConnect/DeviceConnect-JS/wiki/Event-Profile)を参照。
Device Connect APIでは、レスポンスにURIを返却して、アプリから直接デバイスプラグインが立ち上げたサーバにアクセスして、自由なデータのやり取りを提供する。
例えば、カメラのプレビュー画像を取得し続け、Webサーバを通して配信することができる。
PUT /mediaStreamRecording/previewにより、Previewの開始を行う。
DELETE /mediaStreamRecording/previewにより、Previewの停止を行う。
- UIアプリ側でDeviceConnectManagerにストリーミング開始要求をする。
- ストリーミング開始要求を受け取ったデバイスプラグインはデバイスに対してストリーミングの開始を要求をする。
- Webサーバを通じてストリーミングデータの配信を行う。
- デバイスプラグインは、DeviceConnectManagerを経由してUIアプリにストリーミング先のURIを返す。
- UIアプリは、受け取ったURIにアクセスし、ストリーミングデータを取得する。
- ストリーミングを停止する場合は、UIアプリ側でDeviceConnectManagerにストリーミング終了要求をする。
- 終了要求を受け取ったデバイスプラグインは、ストリーミングを停止する。 以下にPreviewの流れを記す。
