FAQ:REST API


質問
回答
APIによるデバイス登録方法を教えてください。 簡易的な登録手順は以下の通りです。
①インベントリAPIでデバイスを登録します。
(POST){{url}}/inventory/managedObjects/
②デバイス管理の[すべてのデバイス]に登録したデバイスが表示されます。
③登録したデバイスの[システムID]より、APIで外部IDを登録します。
(POST){{url}}/identity/globalIds/{{deviceId}}/externalIds
{{deviceId}}にデバイスの[システムID]を入力します。
{{url}}はどの Things Cloud アカウントに接続するかを示し、使用しているテナントの URL を指定します。
Postman の環境設定で{{url}}を設定する方法については、「開発者レポート」をご参照ください。
Postmanを使用したMeasurement/Eventのデータ取得方法

リクエストを実行したユーザーがデバイスのowner(所有者)となり、デバイスはownerのロールに基づいて各種APIアクセスが可能となります。
詳細はThings Cloud OpenAPI仕様をご参照ください。
Inventory > Managed objects > POST - マネージドオブジェクトを作成する
Identity > ExternalIDs > POST - 外部IDを作成する

よりセキュリティに配慮した、デバイスごとに異なる認証情報を払い出す方法(推奨)もあります。
デバイスSDKガイド > RESTデバイスインテグレーション > デバイスインテグレーション
SmartRESTのエンドポイント(host名、port番号)について教えてください。 SmartRESTにはSmartREST1.0、SmartREST2.0があり、いずれもcsv形式での API 接続が可能ですが、接続方法および仕様が異なります。

◆ SmartREST1.0
内部的にはプロキシとして構築されていますが、エンドポイントは通常のREST APIと同様です。したがって、hostはREST-API同様、portは「443」です。APIエンドポイントは「/s」です。
詳細は「デバイスSDKガイド」をご参照ください。
RESTインターフェイスの使用法 > SmartRESTの使用
詳細は「リファレンスガイド」をご参照ください。
SmartREST > 概要

◆ SmartREST2.0
MQTT向けのcsvインターフェースとなり、SmartREST1.0に比較してより多くのテンプレートが利用可能です。SmartREST2.0を利用するためには、MQTTによる接続が必要です。hostはREST-API 同様、portは「8883」または「443」です。
詳細は「デバイスSDKガイド」をご参照ください。
MQTTデバイスインテグレーション > MQTT実装
デバイスIDを表すパラメータを教えてください。 デバイスのIDを表すパラメータはAPIエンドポイントにより複数種類があり、異なる名称を用いているケースがあります。主な例は、以下の通りです。

インベントリ API
始めに、インベントリにマネージドオブジェクトとして保存されます。マネージドオブジェクトAPIにて、c8y_IsDevice:{} をbodyに含めPOSTすると、デバイスとしてマネージドオブジェクトが作成されます。その際のレスポンスに含まれるidが、デバイスのIDを示しています。
また、マネージドオブジェクトのGETをする際のdeviceIdは、デバイスのIDを指定します。
詳細は「デバイスSDKガイド」をご参照ください。
RESTデバイスインテグレーション > Hello REST! > RESTコールを実行する

メジャーメント/イベント/アラーム API
メジャーメント、イベントやアラームAPIでは、一覧取得するAPI(GET)を実行すると、レスポンスにsourceが含まれます。計測値やアラームなどデータの発生元となったマネージドオブジェクト(デバイス)情報がsourceに格納されており、このsourceの中のidが、メジャーメント等が格納されているデバイスのIDとなります。

デバイス制御 API
デバイス制御API中のオペレーションで指定されているdeviceIdは、デバイスのIDを指定しています。

また、Things Cloudの[デバイス管理]から各デバイスのdeviceIdを[システムID]によって確認することができます。
APIでデバイス情報を取得する方法を教えてください。 デバイス情報はインベントリAPIにて取得できます。以下はインベントリAPI取得例です。

特定のデバイス情報の取得方法
(GET){{url}}/inventory/managedObjects/{{deviceId}}
指定したdeviceIdのデバイス情報が取得できます。

デバイス一覧情報の取得方法
(GET){{url}}/inventory/managedObjects?fragmentType=c8y_IsDevice
デバイスはc8y_IsDeviceフラグメントタイプを持ったマネージドオブジェクトなので、
?fragmentType=c8y_IsDeviceをURLの末尾に指定することにより、デバイスの一覧情報が取得できます。
詳細はThings Cloud OpenAPI仕様の Inventory API をご参照ください。

メジャーメント/イベント/アラームの各APIは情報をGETする際、URL末尾にsource=[deviceId]を追記すると、指定deviceIdの各情報が表示されます。以下はメジャーメントAPIでの取得例です。
(GET){{url}}/measurement/measurements?source=[deviceId]
APIでPOSTできるMeasurementデータの最大サイズを教えてください。 Things CloudのMeasurementデータの最大サイズは、データベースエンジンのMongoDBの仕様に基づき16MBです。参考として、MongoDBドキュメンテーションをご参照ください。
デバイス位置や移動軌跡はどうすれば設定できますか? Things Cloud では、デバイス位置(現在地)と、移動軌跡それぞれを管理することができます。

◆ デバイス位置(現在地)
以下のような形式で inventory API により設定できます。

(例)
(PUT){{url}}/inventory/managedObjects/{{device-id}}
{
    “c8y_Position”: {
      “alt”: 67,
      “lng”: 6.15173,
      “lat”: 51.211977
    }
}
詳細はThings Cloud OpenAPI仕様をご参照ください。
Inventory > Managed objects > PUT - マネージドオブジェクトを更新する

◆ 移動軌跡
移動軌跡の登録方法については、FAQ: 地図ウィジェットでデバイスアイコンが「undefined」と表示されて、正しく日時が表示されません。をご参照ください。
Things Cloudのドメインモデル>インベントリ
センサー・ライブラリ > 位置確認特性