Skip to content

2. Specification

Jump to bottom
小林伸郎 edited this page Feb 2, 2017 · 17 revisions

はじめに

Device Connectシステムは、マルチOS、マルチプラットフォームのランタイム環境上において、スマートデバイスと接続するためのAPI (RESTful) を提供します。これにより、スマートデバイスとの接続方法・連携方法の利便性を向上することを目的としています。

Device Connectシステムが提供する機能一覧は以下の通りです。

  • 連携可能な周辺機器一覧を表示する機能
  • 接続I/F（Bluetooth, BLE, Wi-Fi, NFC）の違いのわかりにくさの解消
  • 機器プロファイルによる統一的なAPI
  • ユーザによるアプリケーション認可機能
  • etc.
構成図

APIアクセスデザインパターン

Device Connectシステムでは、シンプルで手軽なHTTP通信と、効率的なWebSocket通信によるイベント処理を行い操作できるようにします。
以下の3つのデザインパターンを元にAPIの設計を行っています。

  • One shot data
  • Event driven data
  • Streaming data

One shot data

シンプルなRESTでDevice Conenct Managerにアクセスすることで、ウェアラブルデバイスやIoTデバイスの情報を取得、操作を行います。

例) アクセスした瞬間の心拍センサーの値を取得
Sequence of One shot data

Event driven data

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

例) 心拍センサーの値に変化があった瞬間の値を連続的に自動取得
Sequence of Event data

Streaming data

Device Connect Managerは、各デバイスプラグインがWebサーバを立ち上げたURIをアプリケーションに中継します。
アプリケーションでは、受け取ったURIを直接参照することで、Device Connect Managerを経由せずに映像リソースなどのデータを受信します。

例) カメラ映像を要求した場合に、OSやGotAPIの内部構造を経由せずに映像リソースとしてアプリから直接利用
Sequence of Streaming data

アプリケーションと各デバイスプラグインが立ち上げたWebサーバ間の通信においては、特に規定は行なっていません。
デバイスプラグインの仕様に合わせて、アプリケーションが処理する必要があります。

Device Connect Manager

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

GotAPI

Device Connect Managerは OMA GotAPI v1.1 上で定義されている機能を実装しています。
詳しくは、GotAPIの資料を参照してください。

GotAPI Interface

GotAPIでは、標準化したAPIを定義しています。
Device Connectシステムでは、GotAPIが定義している以下のAPIを実装しています。

Availability API

GotAPIサーバ(Device Connect Manager)が起動しているか確認します。

Authorization API

GotAPI Auth Serverにユーザ認可を求めます。
ユーザに認可された場合にアクセストークンを取得することができます。
Availability、Authorization以外のAPIにアクセスする場合には、ここで取得したアクセストークンを一緒に送らないとアクセスすることができません。

Grant

クライアントIDを生成します。

AccessToken

アクセストークンを生成します。

ServiceDiscovery API

GotAPIサーバ(Device Connect Manager)に接続されているサービス(デバイス)一覧を取得します。

例) ServiceDiscoveryでサービスを検索します。

GET /gotapi/servicediscovery?accessToken=xxxxx HTTP/1.1
Host: localhost:4035
Origin: www.example.com

{
    "product":"Device Connect Manager",
    "version":"x.x",
    "result":0,
    "services":[
        {
            "id":"device1.localhost.deviceconnect.org",
            "name":"Service1",
            "type":"Bluetooth",
            "online":true,
            "config":""
        },
        {
            "id":"device2.localhost.deviceconnect.org",
            "name":"Service2",
            "type":"WiFi",
            "online":false,
            "config":""
        }
    ]
}

ServiceInformation API

GotAPIサーバ(Device Connect Manager)からサービス(デバイス)の詳細な情報を取得します。

例) ServiceDiscoveryで発見したサービスのidを指定して詳細な情報を取得します。

GET /gotapi/serviceinformation?accessToken=xxxxx&serviceId=device1.localhost.deviceconnect.org HTTP/1.1
Host: localhost:4035
Origin: www.example.com

{
    "product":"Device Connect Manager",
    "version":"x.x",
    "result":0,
    "connect":{
        "wifi":true
    },
    "supports":[
        "system",
        "battery",
        "vibration"
    ],
    "supportApis": [
        // 省略
    ]
}

GotAPI セキュリティ

リクエストの発行元を明示

OMA GotAPI v1.1 の規定に従い、アプリケーションは、リクエストにOriginヘッダを付加する必要があります。
GotAPIのセキュリティ機能であるアプリケーション認可機能やホワイトリスト機能は、Originヘッダの情報を元に処理されます。

HTMLアプリケーションとNativeアプリケーションで付加するヘッダが異なります。

  • HTMLアプリケーションの場合

RFC6454上で定義されるOriginをOriginヘッダに指定します。

GET /gotapi/availability HTTP/1.1
Host: 127.0.0.1:4035
Origin: http://xxx.example.com/
  • Nativeアプリケーションの場合

X-GotAPI-OriginヘッダにNativeアプリケーションの識別子(Androidの場合はパッケージ名等)を指定します。

GET /gotapi/availability HTTP/1.1
Host: 127.0.0.1:4035
X-GotAPI-Origin: com.example.android.app

なお、本機能はDevice Connect Managerの設定画面で有効/無効を切り替えることができます。
本機能を無効にした場合は、Originが不要になるためにアプリケーション認可機能やホワイトリスト機能も同時に無効になります。

なお、Device Connect Managerでは、両方のヘッダが指定された場合は、Originヘッダを優先して使用します。

アプリケーション認可機能

ユーザーが認可していないアプリケーションからのアクセスをブロックする機能です。

アプリケーションは、初めてDevice Connectシステムにアクセスする際、ユーザーからの認可とともに、アクセストークンを取得する必要があります。
アクセストークン無しでデバイスにアクセスしようとした場合、Device Connectシステムはアプリケーションに対してエラーを返却します。

なお、本機能はDevice Connect Managerの設定画面で有効/無効を切り替えることができます。

ホワイトリスト機能

ホワイトリストに含まれないアプリケーションからのアクセスを禁止する機能です。 また、ユーザに対してアプリケーションのホワイトリスト管理機能及びUIと本機能の有効/無効を操作するUIを提供します。
これによりユーザ操作によって切り替え可能にします。

本機能が有効になっている場合、アプリケーションから受信したリクエストメッセージのOriginヘッダをチェックし、Originがホワイトリストに含まれていない場合、エラーを返却します。

HMACサーバ検証機能

アプリケーション側で、Device Connectシステムの正当性を検証できるように、アプリケーションからのリクエストへの応答にHMACを付加します。
本機能の使用・不使用はアプリケーション側に委ねられています。

セキュリティ

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

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

リクエスト

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

共通パラメータ

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

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

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

HTTPメソッド一覧

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

HTTPメソッド
GET
PUT
POST
DELETE

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

Access-Control-Allow-Origin: *

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

リクエストURIの規則

Device Connect では、以下の規則に基づいて、Device Connect APIを定義します。

1. セグメント階層

URIは、/api/profile/interface/attributeのセグメントで定義します。

  • interfaceとattributeは省略可能である。
  • interfaceが存在する時は、attributeは省略不可とする。
例) interfaceとattributeが省略された場合
/api/profile

例) interfaceが省略された場合
/api/profile/attribute

例) 省略がない場合
/api/profile/interface/attribute
セグメントの説明
セグメント 省略 説明
api - Device Connect APIが使用するAPIの名前を指します。
OMAのGotAPIを元にしているため、apiは「gotapi」を指定しています。
profile - ユニークな機能ごとにそれぞれprofileを割り当てます。
interface ○ 提供されるプロファイルで、細分化できる機能がある場合にはinterfaceとして割り当てます。
attribute ○ 提供されるプロファイルで、取得・操作が可能な属性を持つ場合にattributeとして割り当てます。
セグメント構成の例外

Device Connectでは、GETメソッドを用いて、POST/PUT/DELETEを操作できるようにするために、以下のようなセグメントを定義します。

/api/method/profile/interface/attribute
セグメント 省略 説明
method ○ PUT、POST、DELETEの代替操作を行うためのメソッドを指定します。 
例) GETメソッドで、PUT操作相当を行う
GET /gotapi/put/mediaPlayer/play

2. URIの命名規則

api、profile、interface、attributeの各セグメントは、以下の命名規則に基づき定義します。

  • ローワーキャメルケースで定義する。
  • セグメントは複数単語(2,3単語程度)に収める。
  • 意味のない冗長な単語はなるべく使用しない。
  • UnixやDOSなどのコマンド名を使用しない。
例) ローワーキャメルケースで定義する。
正: PUT /gotapi/mediaPlayer/play

誤: PUT /gotapi/meida_payer/play
　  PUT /gotapi/meida-payer/play

ただし、Device Connectシステムでは、profile、interface、attributeの大文字小文字を無視して処理を行います。

3. 一般的な略語

一般的な略語は使用して良いこととします。

例) 一般的な略語
PUT /gotapi/tv
PUT /gotapi/ecg/onECG

一般的でない略語や複数の意味を持つような単語を使用する場合には、その旨をWikiなどで説明します。

例) 一般的でない略語
PUT /gotapi/omnidirectionalImage/roi

ROIは、「Region Of Image」の意味で使用していますが、「Return On Investment」などの略語の可能性もあるため、説明を追加する必要があります。

4. 数値

値の範囲が決まっているのならば、/profile/interface/attributeに数値などを含めても良いこととします。

  • 可変的に数値を変えられるような数値は使用してはいけない。
  • 推奨としては、0〜10程度の範囲とする。
例) GPIOのピン番号
GET /gotapi/gpio/export/pin0
GET /gotapi/gpio/export/pin1
GET /gotapi/gpio/export/pin2

5. 同じ綴り

同じ綴りのAPIは用意しないようにします。

例) onECGとoneCgで同じ綴り
PUT /gotapi/ecg/onECG
PUT /gotapi/ecg/oneCg

6. 商品名等

造語、商品名などは、汎用性のない操作を定義する時に使用します。

例) Spheroのデバイスの機能を使用する
PUT /gotapi/sphero/quaternion/onQuaternion

Spheroは、アメリカ Spheroのアメリカおよびその他の国における登録商標または商標です。

7. 動詞

RESTでは動詞を使用してはいけないが、Device Connectでは分かりやすさを重視して使用しても良いこととします。

  • profileは名詞にする。
  • interface、attributeは動詞を使用しても良い。
例) attributeに動詞を使用
POST /gotapi/notification/notify
POST /gotapi/phone/call

8. 予約語

既存のGotAPIやDevice Connectで定義されているProfileは、予約語となるために独自Profileで使用することはできない。

例) 既に定義されているプロファイル
GET /gotpai/availibity
GET /gotpai/files
など

9. イベント

イベント処理の設定を行うAPIは、attributeにonというプレフィックスを付けます。

例) イベントの登録
PUT /gotapi/battery/onChargingChange
PUT /gotapi/deviceOrientation/onDeviceOrientation

例) イベントの解除
DELETE /gotapi/battery/onChargingChange
DELETE /gotapi/deviceOrientation/onDeviceOrientation
イベントの例外

GotAPIで定義されているイベント処理では、onが付かない場合があります。

例) GotAPIで定義されているAPI
PUT /gotapi/health/heart

レスポンス

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

共通パラメータ

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"
}

HAMC

エラーレスポンス

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

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

論理名 物理名 データ型 備考
エラーコード errorCode 数値 エラーを識別するためのコード
エラーメッセージ errorMessage 文字列 エラーの内容
エラーレスポンス例
{
    "product" : "Device Connect Manager",
    "version" : "2.0.0",
    "result" : 0,
    "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名が不正

デバイスプラグイン

Device Connect Managerと連携して周辺機器を操作、および、イベントを送信するアプリケーションになります。
スマートフォン内で周辺機器毎のAndroidもしくはiOSアプリケーションとして構成されます。

Clone this wiki locally