Hello REST!

Hello REST!

概要

このセクションでは、Things Cloudでデバイス表現を作成する方法と、その後、関連するメジャーメントデータを送信する方法の基本的な例を示します。

すべての手順は、RESTインターフェースを呼び出すことによって実行されます。これらのRESTコールは、CURL ステートメントによってコマンドラインで実行できます。

前提条件

このチュートリアルを実行するには、次の前提条件が満たされているかどうかを確認してください。

  • Things Cloudにアクセスするための有効なテナント、ユーザー、パスワードを保持している。
  • コマンドラインツールのCURLがシステムにインストールされている。

RESTコールを実行する

次に、2つのRESTコールのシーケンスを実行します。詳細は次で説明します:

  • ステップ1:Things Cloudのインベントリに新しいデバイスを作成する
  • ステップ2:そのデバイスに関連するメジャーメントデータを送信する

実際には、これらのステップは 「デバイスエージェント」 によって実行されます。

ステップ1は、デバイスが初めてThings Cloudに接続されたときに1回だけ実行されます。

その後、このステップを実行したときに返される内部IDによってデバイスを参照することで、そのデバイスに関連するアクションを実行することができる。

新しいデバイスの作成

Things Cloudのインベントリに新しいデバイスを作成するには、次のREST要求が必要です:

POST /inventory/managedObjects HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
Accept: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
Authorization: Basic <<Base64 encoded credentials <tenant ID>/<username>:<password> >>
...
{
    "c8y_IsDevice" : {},
    "name" : "HelloWorldDevice"
}

この呼び出しは、次のcurlステートメントを実行することによって実行できます:

curl -v -u <username>:<password> \
   -H 'Accept: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9' \
   -H 'Content-type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9' \
   -X POST \
   -d '{"c8y_IsDevice":{},"name":"HelloWorldDevice"}' \
   http://<tenant-ID>.cumulocity.com/inventory/managedObjects

<username>, <password> と <tenant-ID> をThings Cloudに登録するときにユーザーに与えられる適切な認証情報に置き換えます。 Things Cloud Web GUIへのアクセスに使用するものと同じ認証情報を使用してREST呼び出しを実行することができます。

次のような応答が表示されます:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9
Authorization: Basic <<Base64 encoded credentials <tenant ID>/<username>:<password> >>
...
{
    "id": "1231234"
    "lastUpdated": "2014-12-15T14:58:26.279+01:00",
    "name": "HelloWorldDevice",
    "owner": "<username>",
    "self": "https://<tenant-ID>.cumulocity.com/inventory/managedObjects/1231234",
    "c8y_IsDevice": {},
    ...
}

デバイスを作成する場合、Things CloudはIDを生成します。このIDは、デバイスを参照するために以降の呼び出しで必要になります。 このIDは、応答の中に「ID」属性と値のペアとしてあります。

メジャーメントデータの送信

デバイスが作成された後、メジャーメントデータを送信できます。

この例では、特定の時間に収集された摂氏単位の温度測定値を送信します:

POST /measurement/measurements
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
Accept: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
...
{
    "c8y_TemperatureMeasurement": {
        "T": {
            "value": 21.23,
            "unit":"C"
        }
    },
    "time": "2014-12-15T13:00:00.123+02:00",
    "source": {
        "id": "1231234"
    },
    "type":"c8y_PTCMeasurement"
}

idの値を、最初の手順で取得した適切な値に置き換えます。

さらに、時間値を最近のタイムスタンプに更新し、後でThings Cloud UIでメジャーメントを見つけやすくする必要があります。 リファレンスガイドで説明されているタイムスタンプ値のデータ形式に注意してください。

curl -v -u <username>:<password> \
   -H 'Accept: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9' \
   -H 'Content-type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9' \
   -X POST \
   -d '{"c8y_TemperatureMeasurement":{"T":{"value":21.23,"unit":"C"}},"time":"2014-12-15T13:00:00.123+02:00","source":{"id":"1231234"},"type":"c8y_PTCMeasurement"}' \
   http://<tenant-ID>.cumulocity.com/measurement/measurements/

この要求に対する応答は次のようになります:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json; charset=UTF-8; ver=0.9
...
{
    "id": "4711",
    "self": "https://<tenant-ID>.cumulocity.com/measurement/measurements/4711",
    "source": {
        "id": "1231234",
        "self": "https://<tenant-ID>.cumulocity.com/inventory/managedObjects/1231234"
    },
    "time": "2014-12-15T12:00:00.123+01:00",
    "type": "c8y_PTCMeasurement",
    "c8y_TemperatureMeasurement": {
        "T" : {
            "unit" : "C",
            "value" : 21.23
        }
    }
}

必要に応じて、メジャーメントの送信を繰り返すことができます。要求を再送信する前に、タイムシリーズを作成するためにタイムスタンプ(属性'time'の値)を更新する必要があります。

以上で完了です。Things Cloud UIにデバイス管理アプリケーションを入力し、「すべてのデバイス」ページでデバイスを選択し、「メジャーメント」タブに切り替えます。ここにメジャーメントデータが表示されます。

データが表示されない場合は、送信したメジャーメントで使用したタイムスタンプを含めるために、フィルタ設定を「先週」などに変更する必要があります。

詳細

ここで示したRESTコールのシーケンスは、デバイスの統合で説明した手順を短縮したものにすぎません。 最初のステップ(新規デバイスの作成)は「スタートアップフェーズ 」の一部ですが、ステップ2(メジャーメントの送信)はサイクルフェーズを指します。

現実世界のエージェントの実装に必要な情報については、デバイスの統合を参照してください。