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を作成する

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

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

◆ SmartREST2.0
MQTT向けのcsvインターフェースとなり、SmartREST1.0に比較してより多くのテンプレートが利用可能です。SmartREST2.0を利用するためには、MQTTによる接続が必要です。hostはREST-API 同様、portは「8883」または「443」です。
詳細は「リファレンスガイド」をご参照ください。
SmartREST 2.0 ＞ 概要

詳細は「デバイス統合ガイド」をご参照ください。
MQTTデバイスインテグレーション ＞ MQTT実装
デバイスIDを表すパラメータを教えてください。 デバイスのIDを表すパラメータはAPIエンドポイントにより複数種類があり、異なる名称を用いているケースがあります。主な例は、以下の通りです。

インベントリ API
始めに、インベントリにマネージドオブジェクトとして保存されます。マネージドオブジェクトAPIにて、c8y_IsDevice:{} をbodyに含めPOSTすると、デバイスとしてマネージドオブジェクトが作成されます。その際のレスポンスに含まれるidが、デバイスのIDを示しています。
また、マネージドオブジェクトのGETをする際のdeviceIdは、デバイスのIDを指定します。
詳細は「デバイス統合」をご参照ください。
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のドメインモデル＞インベントリ
・センサー・ライブラリ ＞ 位置確認特性