ここでは、実際に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


curl -i -X PUT https://api.tinkermode.com/devices/35515/event \

-H 'authorization: ModeCloud v1.xxx' \

-d @/tmp/event.json



TSDB(時系列データベース)のログを確認し、INFOが出力されたことを確認してください。ERRORの場合、メッセージを確認し、JSONオブジェクトを修正して再度実行してください。



位置情報(location)の登録

同様に、locationのJSONオブジェクトを作成してください。locationにはタグがありません。その場合、tagNamestagsは省略できます。また、以下の例に示すとおり、複数のレコードはまとめて送信することができます。


/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


curl -i -X PUT https://api.tinkermode.com/devices/35515/event \

-H 'authorization: ModeCloud v1.xxx' \

-d @/tmp/location.json



運転履歴(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'