ここでは、実際にAPIを使ってMobility Cloud のデータを管理する方法を示します。
まず初めに、テスト用デバイスのAPIキー（アクセストークン）を使いデータをアップロードします。次に、アプリケーションにログインしたユーザーのAPIキーを使い、テスト用デバイスから登録したデータを確認します。
Mobility Cloud にデータを表示するためには、イベント(event)、 位置情報(location)、運転記録(session) のデータ登録が最低限必須となります。他のデータについては、お使いのデバイスに合わせて必要に応じて登録してください。
Collectionの作成
各アセット毎に最初に1回だけ行う必要があります。ここでは、Home ID=2227, Asset ID=1のアセットに対して、最低限（イベント、位置情報、運転記録）のCollcetionを作成します。
太字下線部分は、それぞれ先にメモしたHome ID、APIキー、Asset IDに変更してください。
https://dev.tinkermode.com/platform/api/time-series-database#create-a-time-series-collection
curl -X POST https://api.tinkermode.com/homes/2227/smartModules/tsdb/collections \ -H 'authorization: ModeCloud v1.xxx' \ -d '{"id": "event:asset-1","timeZone": "Asia/Tokyo"}'
{"homeId":2227,"id":"event:asset-1","moduleId":"tsdb","timeZone":"Asia/Tokyo","valueNames":[]}
curl -X POST https://api.tinkermode.com/homes/2227/smartModules/tsdb/collections \ -H 'authorization: ModeCloud v1.xxx' \ -d '{"id": "session:asset-1","timeZone": "Asia/Tokyo"}'
{"homeId":2227,"id":"session:asset-1","moduleId":"tsdb","timeZone":"Asia/Tokyo","valueNames":[]}
curl -X POST https://api.tinkermode.com/homes/2227/smartModules/tsdb/collections \ -H 'authorization: ModeCloud v1.xxx' \ -d '{"id": "location:asset-1","timeZone": "Asia/Tokyo"}'
{"homeId":2227,"id":"location:asset-1","moduleId":"tsdb","timeZone":"Asia/Tokyo","valueNames":[]}
|
データの登録
イベント（event）の登録
登録したいインシデントのJSONオブジェクトを作成してください。collectionIdに含まれるAsset IDは先にメモしたAsset IDに変更してください。timestamp は ISO-8601 書式 で指定してください。"valueNames"の項目の順番と"values"の順番、"tagNames"の項目の順番と"tags"の順番は対応している必要があります。
/tmp/event.json
{ "eventType": "sensor_data", "eventData": { "collectionId": "event:asset-1", "valueNames": ["assetId", "heading", "lat", "lon", "operatorId", "speed", "type"], "tagNames": ["addr", "name", "timestamp", "uuid", "value"], "records": [{ "timestamp": "2021-02-26T01:13:22Z", "values": [1, 45, 35.661000, 139.757000, 2334, 30, 1201], "tags": ["", "Unsafe Driver Condition", "2021-02-26T01:12:22Z", "20c49eac-b677-477c-a08d-69737f7d17c0", "{\"triage\":10,\"condition\":2}"] }] } } |
作成したJSONオブジェクトを、MODEのEventエンドポイントに送信してください。
太字下線部分は、テスト用デバイスのDevice ID、APIキーに変更してください。
https://dev.tinkermode.com/platform/api/homes#send-event-to-a-home
TSDB(時系列データベース)のログを確認し、INFOが出力されたことを確認してください。ERRORの場合、メッセージを確認し、JSONオブジェクトを修正して再度実行してください。
位置情報（location）の登録
同様に、locationのJSONオブジェクトを作成してください。locationにはタグがありません。その場合、tagNamesとtagsは省略できます。また、以下の例に示すとおり、複数のレコードはまとめて送信することができます。
/tmp/location.json
{ "eventType": "sensor_data", "eventData": { "collectionId": "location:asset-1", "valueNames": ["heading", "lat", "lon", "speed"], "records": [{ "timestamp": "2021-02-26T01:12:22Z", "values": [45, 35.661000, 139.757000,10] }, { "timestamp": "2021-02-26T01:13:22Z", "values": [70, 35.662000, 139.757000,20] }, { "timestamp": "2021-02-26T01:14:22Z", "values": [90, 35.663000, 139.757000,30] } ] } }
|
作成したJSONオブジェクトを、MODEのEventエンドポイントに送信してください。
太字下線部分は、テスト用デバイスのDevice ID、APIキーに変更してください。
https://dev.tinkermode.com/platform/api/homes#send-event-to-a-home
運転履歴（session）の登録
同様に、sessionのJSONオブジェクトを作成してください。太字下線部分は、テスト用のAsset ID、Device ID、User IDを指定してください。
/tmp/session.json
{ "eventType": "sensor_data", "eventData": { "collectionId": "session:asset-1", "valueNames": ["assetId", "deviceId", "operatorId"], "records": [{ "timestamp": "2021-02-26T01:12:22Z", "values": [1, 35515, 2334] }] } } |
作成したJSONオブジェクトを、同様にMODEのEventエンドポイントに送信してください。
Mobility Cloud にログインし、登録したデータが参照できることを確認してください。登録されたデータが全て参照できるようになるまでには最大4時間程度の時間がかかる場合があります。詳しくは、Time Series Database TSDBの注意事項：An Important Note Regarding Data Availabilityをご確認ください。
時系列データの取得
TSDBが提供するAPIとユーザーAPIキーを利用することで、データを取得したり削除したりCSV形式でダウンロードしたりすることができます。
エンドポイントのURLのhomeId, moduleId, collectionIdには、以下の通り指定してください。
homeId | そのアセットが所属するHomeId。URLから確認可能。 |
moduleId | TSDBインスタンスのID。Mobility Cloud の場合、常に”tsdb” |
collectionId | 取得したいデータのCollection ID。 |
例えば、2021-02-26 5:00(UTC)から遡って20件分のインシデントを取得したい場合、以下のとおり指定してください。authorizationには、ユーザーAPIキーを指定してください。
curl -X GET 'https://api.tinkermode.com/homes/2227/smartModules/tsdb/collections/event:asset-1/data?&ts=2021-02-26T05:00:00.000Z&limit=-20&selectValues=assetId,operatorId,heading,lat,lon,speed,type&selectTags=addr,name,uuid,value' -H 'authorization: ModeCloud v1.xxxx' |
