Postmanを使用したMeasurement/Eventのデータ取得方法

投稿日 / 投稿者名

2018.8.1 / 磯和 七海

はじめに

本レポートは、Things Cloud の利用例をより知っていただくための実利用レポートとして作成したものです。
Things Cloud は極力後方互換性を持つよう開発されていますが、今後のリリースにより、一部画面やコマンド、手順などが変更となったり、利用できない可能性があることをあらかじめご了承ください。
なお、作成にあたり、以下バージョンを用いています。

  • ver.8.15.8(backend/UI)

難易度 ★


概要

本セクションでは、API経由でのMeasurement/Eventデータの取得方法をご紹介します。
プログラミング不要のPostmanを使ってMeasurement/Eventデータを取得し、取得したデータの見方を解説します。 

前提条件

  • HTTP通信について基礎的な理解があること。
  • インターネットにつながるPCに以下をインストールしていること。
    • Postman(バージョン6.1.4)



所要時間(目安)

この手順に沿って、Measurement/Eventデータ取得する場合の所要時間。

  • 約20分

習得できること

今回は、Postmanを使ってMeasurement/Eventデータを取得する方法を学びます。例として、"Cumulocity API" のMeasurementとEventを使用します。

【取得イメージ】
右下のテキストボックスに取得したデータが入ります。
また、赤丸で囲んだところに、HTTPステータスコードが入ります。正しく取得できた場合、Status:200 OKと表示されます。



1.Postmanの環境設定

Postmanおよび重要なREST APIコマンドのサンプルをセットアップするには、こちらをクリックします。
画面の指示にしたがって、Postmanに "Cumulocity API" フォルダをダウンロードします。
"Collections" タブを押して、 "Cumulocity API" フォルダを開いてください。
例として、"Measurement" サブフォルダを開き、 "Get collection of Measurement" をクリックしてください。

次に、Postmanのプレースホルダを設定し、どの Things Cloud アカウントに接続するかを指定します。
プレースホルダとは、 "{{url}}/measurement/measurements" などの "url" 部分を指します。
以下の手順にしたがって設定することで、同じテナントから他のデータを取得する時に毎回アカウント入力する手間が省けます。
(以下で紹介するアカウント以外にもヘッダー情報をプリセットしておく機能があります。 画面右側のヘッダータブを押すと、keyとvalueを入力できます。)



PostmanからThings CloudにAPIリクエストを実行できるようにするために、まずは最初に以下の項目を設定します。

  1. 使用しているテナントのURL
  2. アカウント情報

【入力例】

手順

  1. 右上にある歯車のマークをクリックしてください。
  2. "Manage Environments" を選び、"Add" をクリックしてください。
  3. environment の名前(例えばテナント名)を入力してください。
  4. key に "url" と入力し、value に "https://{{テナント名}}.je1.thingscloud.ntt.com" を入力してください。
  5. 次のkeyに "auth" と入力し、value に入力するREST要求の値を準備します。REST要求の値は以下の手順にしたがって入手してください。
    Authorizationヘッダーの設定
    1. 例として、ユーザー名を "me" 、パスワードを "secret" とします。
    2. "me:secret" の形で"Base 64エンコード"をしてください。(Basic認証)
      無料でエンコードできるウェブサイトもあります。
    3. テキストは "bWU6c2VjcmV0" になります。
  6. "auth" の値に "Basic bWU6c2VjcmV0" を入力してください。
  7. "Add" をクリックし、ダイアログをクローズしてください。
  8. 新しく作成した environment が右上のドロップダウン(最初は "No environment" になっています)から選べるようになります。

以上で環境設定は終了です。

【環境設定がうまくいかないときは、こちらをご確認ください】

  • URLは正しく入力されていますか? (最後に/を入れないでください)
  • keyには小文字の "url" と "auth" が入力されていますか?
  • "ユーザー名:パスワード"の形で入力し、Base 64エンコードをしていますか?
  • 上記の手順で得られた値の前に、"Basic (半角スペース)"を入力していますか? (6.参照)



2.MeasurementデータをGETする

Postmanの "Collections" タブを押して、 "Cumulocity API" フォルダを開いてください。
例として、"Mesurement" サブフォルダを開き、 "Get collection of Measurement" をクリックしてください。
画面右側のSend(青色のボタン)をクリックしてください。
表示されたBodyダブの内容がMeasurementデータです。

【データ取得イメージ】


取得したデータの項目紹介

例として、Measurementが以下のように表示されている時を紹介します。

{
    "time": "2018-05-23T15:40:45.004+09:00",
    "id": "88893",
    "self": "https://{{テナント名}}/measurement/measurements/88893",
    "source": {
        "id": "88887",
        "self": "https://{{テナント名}/inventory/managedObjects/88887"
    },
    "type": "c8y_DistanceIRMeasurement",
    "c8y_DistanceMeasurement": {
        "distance": {
            "unit": "mm",
            "value": 500
        }
    }
}
項目 種別 説明
time String メジャーメントの時間
id String メシャーメントを一意に識別する番号
(メジャーメントID)
self URI このリソースへのリンク
source ManagedObject デバイスID(ManagedObjectのID)
(オブジェクトは「id」および「self」のプロパティを含む)
c8y_DistanceMeasurement Object フラグメントの名前
(オブジェクトは「distance(フラグメントシリーズ)」のプロパティを含む)
フラグメントの詳細はこちらをご覧ください
type String このメジャーメント種別を端的に示す種別名
unit String メジャーメントの単位
(今回は「mm」)
value Number 個々のメジャーメントの値

この表の詳細はこちらで参照できます。

さまざまなMeasurementのGET方法

先ほど紹介した "Get collection of Measurement" 以外にもデータの範囲を指定して取得することができます。

【Measurementサブフォルダ】

名称 内容
collection of measurement 全てのメジャーメントのデータを取得する
specific measurement メジャーメントIDを指定してデータを取得する
measurements for time range "YYYY-MM-DD" の形式で取得したい期間の年月日を指定する
measurement series デバイスのIDと取得したい期間の年月日を指定する



3.EventデータをGETする

Postmanの "Collections" タブを押して、 "Cumulocity API" フォルダを開いてください。
"Event" サブフォルダを開き、 "Get collection of events" をクリックしてください。
画面右側のSend(青色のボタン)をクリックしてください。
表示されたBodyダブの内容がEventデータです。

【データ取得イメージ】


取得したデータの項目紹介

例として、Eventが以下のように表示されている時を紹介します。

{
    "creationTime": "2018-05-14T16:05:09.027+09:00",
    "time": "2018-05-14T16:05:08.700+09:00",
    "id": "10311",
    "self": "https://{{テナント名}}/event/events/10311",
    "source": {
        "id": "10309",
        "name": "RaspPi",
        "self": "https://{{テナント名}}/inventory/managedObjects/10309"
    },
    "text": "c8y.lx.agent.Agent: Starting drivers",
    "type": "c8y_DeviceLog"
}
項目 種別 説明
creationTime String イベントがデータベース内で作成された時間
time String イベントの時間
id String イベントを一意に識別するID
(イベントID)
self URI このリソースへのリンク
source ManagedObject イベント発生源のデバイスID(ManagedObjectのID)
(オブジェクトは「id」、「self」、「name」、および「type」のプロパティを含む)
text String
type String このイベント種別を端的に示す種別名

この表の詳細はこちらで参照できます。

Postmanを使ったMeasurement/Eventデータ取得方法の紹介は以上です。