MindSphere APIとは？

MindSphereが用意しているREST API群のことです。
たくさんありますが、一部抜粋すると以下のようなものを利用することができます。

Asset Management(アセットのデータ取得・登録・削除)
IoT Time Series(時系列データの取得・登録・削除)
Identity Management(ユーザーのデータ取得・登録)

他はこちらからご覧になられます。

APIからかなりの多くの操作ができると同時に手軽に使用できるので、今回はこれを使用していきます。

使用したいAPIを登録する

APIのロールを登録する

ランチパッドからDeveloper Cockpitを開きます。
次にAuthorization Managementをクリックし、Applicationペインから自分のアプリケーション(raspiapp)を選択します。

右のペインにスコープとロールの一覧が出ますのでAdd Core Roleをクリック。
開いたモーダルのRole Nameにmdsp:core:assetmanagement.adminと入力。
ADMINにチェックを入れてください。

次にもう一度Add Core Roleをクリックし、
Role Nameにmdsp:core:iot.timAdminと入力。
ADMINにチェックを入れてください。

APIのロールを設定するとは？

以上で行った作業は、アプリケーション(今回はraspiapp)に、使用したいAPIを申告することです。
アプリケーションは初期設定では一部のAPIしか使用できません。これはアプリケーションを安全に運用するため方策で、そのため使用したいAPIだけを、この画面で登録します。

今回は２つのAPIのロールを登録しました。まずmdsp:core:iot.timAdminというロールで、これは時系列データを扱うIoT Time Series APIの入力・読み込みに関するロールです。Adminとあるように、読み込むだけでなく書き込むこともできます。

次のcore:assetmanagement.adminというロールは、Assetのデータをやり取りするAsset Management APIのロールで、やはりこれも読み込みと書き込みができるロールです。

全てのロールとAPIの関係を知りたいときは以下のドキュメントで一覧することができます。

Roles & Scopes for Applications

またADMINだけにチェックを入れたのは、Adminロールを持ったユーザーだけが使用でき、Userロールには使用できないようにするためです。このロールはSettingsでユーザーに設定したときのアプリケーションのロールで、APIのロールとは異なります。
少し混乱するかもしれませんが、MindSphereには特有のロールが二種類あります。

API特有ロールとは？

ロールには大きく分けて2種類あります。
今回設定したのはAPIのロールです。
それに対して、以前の記事でSettingsからユーザーに設定したものはアプリケーションのロールです。

特にこの２つはそれぞれAPI特有ロールと、アプリケーション特有ロールと呼ばれています
分かりにくいので表にまとめると以下の通りです。

名前	機能	設定場所
アプリケーション特有ロール	ユーザーに対するアプリケーションのアクセス権限	Settings
API特有ロール	アプリケーションに対するAPIのアクセス権限	Developer Cockpit > Authorization Management

この２つはそれぞれ独立しているので、開発者はアプリケーション特有ロールと、API特有ロールの両方を設定する必要があります。

APIを内部から使用してみる

APIを使用するには？

今回はアプリケーション内部からAPIを使用してみます。
APIに使用する言語は何でもいいのですが、今回はPHP製のAPIテスターを使用します。

Githubにテスターのセットをアップしていますので、こちらからDLして前々回に作ったローカルのディレクトリraspiappに保存してください。
API Tester

構成としては以下のようになったと思います

raspiapp/
├.bp-config/
├tester.php
├index.html
└manifest.yml

次にmanifest.ymlを開き、以下の内容をコピペしてください(変更箇所は最終行の一行だけです)

applications:
  - name: raspiapp
    instances: 1
    host: rashost
    memory: 100MB
    buildpack: php_buildpack

PHPを使用するため、buildpackキーの値をphp_buildpackにしました。
この箇所だけ変更すれば、RubyやPythonが使えるようになります。

さて、前回同様CF CLIでアップロードします。
CFにログインしてから、以下のコマンドを実行してください。

cf push

これでランチパッドからraspiappアイコンをクリックして開くと、前回の「Hello World!」ページが開くので、そのURLの末尾にtester.phpと付け加えてください。以下のようなURLになると思います(regionがeu1の場合)。

https://{テナント名}-raspiapp-{テナント名}.eu1.mindsphere.io/tester.php

バックエンドで内部から使用する場合

APIを使用するには何種類か作法があります。
今回はPHPを使用してバックエンドから、そしてアプリケーションから(=MindSphere内部から)APIにアクセスします

APIテスターに以下のURLをセットして、「送信」をクリックしてください。

https://{テナント名}-raspiapp-{テナント名}.eu1.mindsphere.io/api/assetmanagement/v3/assets

これでResponseのHTTP codeが200なら成功です。
アプリケーションからAPIにアクセスして、assetの登録データを取得できました。
あくまでこれはassetの登録データであって、assetの中身である時系列データではないのでご注意ください。
もしも正しいURLにも関わらず失敗する場合は、一度ランチパッドの右上のログアウトをクリックしてから、もう一度ログインしてください。

時系列データを書き込む

最終的にはRasAssetアセットに、Raspberry Piから時間と温度のデータを入れ込みます。現在は空っぽのこのアセットに、データの書き込みと読み込みをしてみましょう。

まずは書き込みをしますがその前にAsset IDを取得します。これは文字通り、アセット特有のIDナンバーです。

ランチパッドからAsset Managerに進んでください。
RasAssetを選択すると、URLが以下のように変わります

https://[テナント]-assetmanager.eu1.mindsphere.io/entity/[Parent ID]/details/extended/asset?selected=[Asset ID]

selectedというクエリ以降の英数字がAsset IDになります。
これをコピーしてメモを取っておいてください。

テスターに戻り以下の部分を変更してください。
これ以外はデフォルトのままで大丈夫

項目	内容
形式	PUT
URL	https://[テナント名]-raspiapp-[テナント名].eu1.mindsphere.io/api/iottimeseries/v3/timeseries/[Asset ID]/

最後の「パラメータ」というフォームには以下のJSONデータをコピペしてください

[
	{
		"_time": "2019-02-26T05:07:32.000Z",
		"temperature":27.34
	}
]

ブラケット([]の記号)を忘れずにコピーしてください。
"_time"が時間(ISO8601形式)です。テスターの左下にある「現在時刻(ISO8601) 」というやつがそれです。
"temperature"には気温のデータとして「27.34」と設定しています。
この"temperature"はAspectで設定した変数ですね。

これで「送信」を押してください。
無事に書き込めたらHTTPコードが204として返ってきます。

時系列データを読み込む

書き込みが終わったら、次は読み込みをします。

こちらは以下のように設定してください。
さっき使ったパラメータの内容は削除しても大丈夫です(残していても影響はありません)

項目	内容
形式	GET
URL	https://[テナント名]-raspiapp-[テナント名].eu1.mindsphere.io/api/iottimeseries/v3/timeseries/[Asset ID]/

メソッドをGETにします。
これで送信して、先程送信したデータが返ってくればOKです。

これでAPIを通じて、気温のデータを読み書きすることに成功しました！

今やったことはなに？

今やったことはMindSphereサーバでデプロイしたアプリケーションraspiappの中からAPIにアクセスしてみるということです。
あくまでMindSphere内部からのアクセスです。
つまり、Raspberry Piのローカルのような外部からではないということです。
現状、Raspberry Piからはこのページは見ることが出来ません。ブラウザからMindSphereアカウントでログインすれば別ですが、ログインしていない状態ではこのアプリケーション特有ロールがないためアクセスできません。
Raspberry Piからアクセスするには、このアプリケーション特有ロールがなくてもアクセスする必要が出てきますので、そのために必要な「認可」をAPIで取得する必要があります。

次回

次回からは外部からAPIにアクセスします。