Raspberry PiからMindSphereへ (3)内部からAPIを使う

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

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

[他はこちらからご覧になられます。](https://developer.mindsphere.io/apis/index.html)

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](https://developer.mindsphere.io/concepts/concept-roles-scopes.html)

また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](https://github.com/devinoue/APITester)

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

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



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

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

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

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

```bash
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データをコピペしてください

```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にアクセスします。