APIリファレンス

デバイスアプリケーション・Webアプリケーション向け共通API

HTTP REST API

ログイン

デバイスアプリケーション・Webアプリケーション向けのHTTP REST APIの実行に必要なセッショントークンを取得するためのAPIです。

項目説明
URIhttp://{ホスト名 }:{ポート }/api/1/{テナント名 }/api/broker/login
HTTPメソッドPOST
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • Content-Type: application/json (必須)
リクエストボディ登録したいデバイスデータを含む以下のJSONデータを送信します。各プロパティの設定は任意です。
username : 接続に用いるデバイスアカウントのIDを指定します。
password : 接続に用いるデバイスアカウントのIDを指定します。
レスポンスボディ以下の情報を含むJSONが返却されます。
sessionToken : セッショントークン
備考なし

デバイスの状態取得

指定したデバイスIDのDevice Phantomを取得します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}/{deviceId}
HTTPメソッドGET
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディなし
レスポンスボディDevice PhantomのJSONデータが返却されます
備考なし

デバイスの状態削除

指定したデバイスIDのDevice Phantomを削除します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}/{deviceId}
HTTPメソッドDELTE
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディなし
レスポンスボディなし
備考なし

デバイス向けAPI

デバイス向けAPIはデバイスがデバイスデータを送信するためのAPIとCAPが保持する最新データをデバイスが取得するためのAPIの2種類があります。各APIはHTTPとMQTTのプロトコルに対応しています。

なお、{}で括った箇所は実行したいAPIの対象に合わせて設定してください。{deviceId}と書かれた箇所は、サービス運用画面で登録したデバイスアカウントのIDを指定します。

HTTP REST API

デバイスデータの送信

デバイスがCAPにデバイスデータを送信するためのAPIです。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}/{deviceId}/reported
HTTPメソッドPUT
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
  • Content-Type: application/json (必須)
リクエストボディ登録したいデバイスデータを含む以下のJSONデータを送信します。各プロパティの設定は任意です。
deviceId : デバイスIDを指定します。 attributes.reported : センシングデータを設定します。 metadata.reported : センシングデータのメタデータを設定します。
レスポンスボディなし
備考なし

アクチュエーション指示の取得

デバイスがアクチュエーション指示を取得するAPIです。アクチュエーション指示がない場合は、発生するまで一定時間待機します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}/{deviceId}/event
HTTPメソッドGET
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディなし
レスポンスボディJSON形式で目標状態値，最後に報告された状態値，状態の設定値とデバイスの最新状態の差分，メタデータなどを受信します。
詳細は「Device Phantomの仕様理解」を参照して下さい
備考本APIは定期的に呼び出し(ポーリング)して利用することを推奨します。アクチュエーション指示が発生した場合は，HTTP ステータスコード：200 OKと共にアクチュエーション指示が得られます。アクチュエーション指示が発生しない場合，REST APIは一定時間ブロックした後に，HTTP ステータスコード：204 No Contentを返します．

MQTT API

MQTT用のAPIは非同期で処理されるため、APIの呼び出し(処理実行)と結果取得(結果確認)はそれぞれ異なるトピックを用いて実施する必要があります。 APIの呼び出しは対象となるトピックにpublishし、結果の取得は対象となるトピックをsubscribeします。 結果の取得や確認を行う場合は、APIを呼び出す前にsubscribeを実施して、結果の待ち受け状態にしてから、APIのリクエスト送信してください。

デバイスデータの送信

デバイスデータの送信 (API呼び出し)

デバイスがCAPにデバイスデータを送信するためのAPIです。

項目説明
トピックeventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/report
送信データ登録したいデバイスデータを含む以下のJSONデータを送信します。各プロパティの設定は任意です。
deviceId : デバイスIDを指定します。 attributes.reported : センシングデータを設定します。 metadata.reported : センシングデータのメタデータを設定します。

デバイスデータ送信の結果取得

項目説明
トピック成功/失敗を確認するため、以下のトピック指定でサブスクライブします
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/report/+
・IoT Event Hubが受理した場合、以下のトピックにデータが返却されます
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/report/accepted
・IoT Event Hubが拒否した場合、以下のトピックにデータが返却されます
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/report/rejected
受信データacceptedの場合、Device PhantomのJSONを受信します
rejectedの場合は以下のプロパティを持つJSONを受信します。
  • code: サーバが出力するエラーコード
  • message: エラーメッセージ

Device Phantomの取得

デバイスデータの取得指示 (API呼び出し)

デバイスがDevice Phantomの値の取得するAPIです。

項目説明
トピックeventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/get
送信データ空データ

デバイスデータの取得指示の結果取得

項目説明
トピック成功/失敗を確認するため、以下のトピック指定でサブスクライブします
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/get/+
・IoT Event Hubが受理した場合、以下のトピックにデータが返却されます
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/get/accepted
・IoT Event Hubが拒否した場合、以下のトピックにデータが返却されます
eventhub/v1/{ホスト名}/{deviceType}/{deviceId}/phantom/get/rejected
受信データacceptedの場合、Device PhantomのJSONを受信します
rejectedの場合は以下のプロパティを持つJSONを受信します。
  • code: サーバが出力するエラーコード
  • message: エラーメッセージ

Actuationの取得

デバイスがCAPからアクチュエーション指示を取得するAPIです。subscribeでアクチュエーション指示のイベント発生を待つため、API呼び出し(publish)は不要です。

項目説明
トピックeventhub/v1/{ホスト名}/{ deviceType }/{deviceId}/phantom/actuate
受信データDevice PhantomのJSONを受信します

Web アプリケーション向けAPI

Web アプリケーション向けに提供するAPIです。

HTTP REST API

期待するデバイス状態の設定

WebアプリケーションからCAPへ期待するデバイスの状態の設定を行うAPIです。CAPはデータ受信後にDevice Phantomの登録・更新を行います。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}/{deviceId}/desired
HTTPメソッドPUT
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディリクエストボディ 登録したいデバイスデータを含む以下のJSONデータを送信します。各プロパティの設定は任意です。
deviceId : デバイスIDを指定します。 attributes.desired: 期待するデバイスの状態の設定値を設定します。 metadata.desired : 期待するデバイスの状態の設定情報のメタデータを設定します。
レスポンスボディなし
備考なし

デバイスIDの一覧取得

指定したデバイスタイプに含まれるデバイスIDの一覧を返します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/deviceids/{deviceType}
HTTPメソッドGET
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディなし
レスポンスボディJSON形式．{ "deviceIds": [ "デバイスID0", "デバイスID1", … ] }
備考なし

デバイス検索

条件によるデバイスの検索を行います。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/query/{deviceType}
HTTPメソッドPOST
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディ文字列 (SQLクエリ) ※を設定します。クエリの仕様については後述の説明を参照ください。
レスポンスボディJSON形式。クエリ結果の文字列を { "result": ["クエリ結果文字列1", "クエリ結果文字列2", …] } というJSONで返します。
個々のクエリ結果文字列の仕様はIoT Event Hubの仕様を参照して下さい
備考なし

デバイス検索のクエリについて

CAPでは以下の例のようなSQLライクなクエリでの検索が実行可能です。

{
  "sql": “select * from <デバイスタイプ名> where <デバイスタイプに登録したailias名> > 条件”
}

"sql": "select * from、 where の文字列は固定値です。<>の値はCAPに設定した内容に合わせてください。

クエリでは複数のデバイスタイプを利用した副問い合わせも可能です。

{
  “sql”: “select * from <デバイスタイプ名> XX <デバイスタイプ名> XX where XX.<デバイスタイプ XXに登録したailias名> in (select YY.<デバイスタイプ YYに登録したalias名> form <デバイスタイプ名> YY where YY.value < 条件式)”
}

デバイスの状態一括削除

指定したデバイスタイプのDevice Phantomを一括削除します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/broker/devices/{deviceType}
HTTPメソッドDELETE
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
リクエストボディなし
レスポンスボディなし
備考なし

蓄積データのクエリによる取得(同期)

蓄積したデータを検索し、返します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/query/{データ保存先名}
HTTPメソッドGET
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
  • order: ソートを行うキー名を指定します。昇順で検索する場合はキー名を指定します。降順で検索する場合はキー名の前に"-"を付与して指定します。複数のキーを指定するときは、キー名を優先順に","で区切ります。
  • limit: 返却する検索数の上限を指定します。デフォルト値は100件です。limitパラメータを指定しなかった場合、上限は100件となります。limitパラメータに-1を指定した場合は上限無しとなります。
  • skip: 検索結果の先頭からのスキップ数を指定します。デフォルト値は0件です。
リクエストボディなし
レスポンスボディクエリ結果の文字列を {"results": ["クエリ結果文字列1", "クエリ結果文字列2", …], "currentTime": "クエリ実行時刻"} という形式のJSONで返します。
備考なし

蓄積データのクエリによる更新(同期)

蓄積したデータを検索し、指定したJSONで更新します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/query/{データ保存先名}
HTTPメソッドPUT
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
  • Content-Type: application/json(必須)
  • X-Full-Update: JSONの置換動作/更新動作をtrue/falseで指定します。(任意)
    trueを指定すると置換動作となります。デフォルト値はfalseで更新動作です。
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
  • order: ソートを行うキー名を指定します。昇順で検索する場合はキー名を指定します。降順で検索する場合はキー名の前に"-"を付与して指定します。複数のキーを指定するときは、キー名を優先順に","で区切ります。
  • limit: 更新対象とする検索数の上限を指定します。デフォルト値は100件です。limitパラメータを指定しなかった場合、上限は100件となります。limitパラメータに-1を指定した場合は上限無しとなります。
  • skip: 検索結果の先頭からのスキップ数を指定します。デフォルト値は0件です。
リクエストボディ更新するJSONデータ (必須)
レスポンスボディなし
備考なし

蓄積データのクエリによる削除(同期)

蓄積したデータを検索し、削除します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/query/{データ保存先名}
HTTPメソッドDELETE
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
  • X-Query-Safeguard: クエリパラメータを指定しない場合の動作をtrue/falseで指定します。 (任意)
    falseを指定すると、クエリパラメータを指定しない場合の動作が全件削除となります。 デフォルト値はtrueです。
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
リクエストボディなし
レスポンスボディ{"result": "ok", "deletedObjects": <削除されたデータ数>}
備考なし

蓄積データの取得(非同期)

蓄積したデータを検索し、結果を非同期で返します。本APIは以下の流れで使用します。

  1. リクエストを送信します。

  2. レスポンスボディのstatusUrlプロパティの値のURLにアクセスしてstatusの値を確認し、値が"DONE"になるまで待ちます。
    リクエスト受付時のstatusの値は"RUNNING"です。処理が完了するとstatusの値が"DONE"になります。 statusの値が"DONE"になるまでの時間は蓄積データの量やクエリ内容によって変わります。

  3. statusの値が"DONE"になっていることを確認後、レスポンスボディのresultUrlプロパティの値のURLにアクセスして検索結果を取得します。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/asyncquery/{データ保存先名}
HTTPメソッドGET
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
  • order: ソートを行うキー名を指定します。昇順で検索する場合はキー名を指定します。降順で検索する場合はキー名の前に"-"を付与して指定します。複数のキーを指定するときは、キー名を優先順に","で区切ります。
  • limit: 返却する検索数の上限を指定します。デフォルト値は100件です。limitパラメータを指定しなかった場合、上限は100件となります。limitパラメータに-1を指定した場合は上限無しとなります。
  • skip: 検索結果の先頭からのスキップ数を指定します。デフォルト値は0件です。
リクエストボディなし
レスポンスボディ以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • query: リクエストされたクエリ文字列
  • statusUrl: 実行状況のステータスを表すファイルのURL
  • resultUrl: 検索結果ファイルのURL
statusUrlのファイル内容以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • status: “RUNNING”/”DONE”/”CANCEL”のいずれかの値
  • description: 実行中断の理由 (statusが“CANCEL”となった場合のみ)
resultUrlのファイル内容{"results": ["クエリ結果文字列1", "クエリ結果文字列2", …], "currentTime": "クエリ実行時刻"} という形式のJSON。
備考なし

蓄積データの更新(非同期)

蓄積したデータを検索し、結果を非同期で更新します。本APIは以下の流れで使用します。

  1. リクエストを送信します。

  2. レスポンスボディのstatusUrlプロパティの値のURLにアクセスしてstatusの値を確認し、値が"DONE"になるまで待ちます。\ リクエスト受付時のstatusの値は"RUNNING"です。処理が完了するとstatusの値が"DONE"になります。statusの値が"DONE"になるまでの時間は蓄積データの量やクエリ内容によって変わります。

  3. statusの値が"DONE"になっていれば、蓄積データの更新処理は完了しています。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/asyncquery/{データ保存先名}
HTTPメソッドPUT
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
  • Content-Type: application/json(必須)
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
  • order: ソートを行うキー名を指定します。昇順で検索する場合はキー名を指定します。降順で検索する場合はキー名の前に"-"を付与して指定します。複数のキーを指定するときは、キー名を優先順に","で区切ります。
  • limit: 更新対象とする検索数の上限を指定します。デフォルト値は100件です。limitパラメータを指定しなかった場合、上限は100件となります。limitパラメータに-1を指定した場合は上限無しとなります。
  • skip: 検索結果の先頭からのスキップ数を指定します。デフォルト値は0件です。
リクエストボディ更新するJSONデータ (必須)
レスポンスボディ以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • query: リクエストされたクエリ文字列
  • statusUrl: 実行状況のステータスを表すファイルのURL
statusUrlのファイル内容以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • status: “RUNNING”/”DONE”/”CANCEL”のいずれかの値
  • description: 実行中断の理由 (statusが“CANCEL”となった場合のみ)
備考なし

蓄積データの削除(非同期)

蓄積したデータを検索し、結果を非同期で削除します。本APIは以下の流れで使用します。

  1. リクエストを送信します。

  2. レスポンスボディのstatusUrlプロパティの値のURLにアクセスしてstatusの値を確認し、値が"DONE"になるまで待ちます。 リクエスト受付時のstatusの値は"RUNNING"です。処理が完了するとstatusの値が"DONE"になります。statusの値が"DONE"になるまでの時間は蓄積データの量やクエリ内容によって変わります。

  3. statusの値が"DONE"になっていれば、蓄積データの削除処理は完了しています。

項目説明
URIhttp://{ホスト名}:{ポート}/api/1/{テナント名}/api/storedata/asyncquery/{データ保存先名}
HTTPメソッドDELETE
HTTPヘッダ
  • X-Application-Id: アプリケーションID(必須)
  • X-Application-Key: アプリケーションキー(必須)
  • X-Session-Token: セッショントークン(必須)
  • X-Query-Safeguard: クエリパラメータを指定しない場合の動作をtrue/falseで指定します。 (任意)
    falseを指定すると、クエリパラメータを指定しない場合の動作が全件削除となります。デフォルト値はtrueです。
クエリパラメータ
  • filter: 検索条件をJSON形式で指定します。JSONの内容はURLエンコードを行う必要があります。
リクエストボディなし
レスポンスボディ以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • query: リクエストされたクエリ文字列
  • statusUrl: 実行状況のステータスを表すファイルのURL
statusUrlのファイル内容以下のプロパティを持ったJSON形式。
  • id: リクエストごとに発行されるID
  • status: “RUNNING”/”DONE”/”CANCEL”のいずれかの値
  • description: 実行中断の理由 (statusが“CANCEL”となった場合のみ)
備考なし