Watson IoT Platform と Cloudant を連携させる

# はじめに
　Watson IoT Platform (Internet of Things Platform) は、IBM Cloud を基盤とする IoT のためのプラットフォームです。センサー等のデバイスから得られるデータの収集・蓄積・可視化など、様々な機能を提供しています。
　提供する機能の一つとして、同じく IBM Cloud で提供される NoSQL型DBの Cloudant と連携する機能があり、デバイスから収集したデータをリアルタイムに保管することができます。
　本記事では、その連携方法について解説します。

# 前提
- IBM Cloud のアカウントを所有していること
- IBM Cloud 上で Watson IoT Platform のインスタンスを作成済みであること
- IBM Cloud 上で Cloudant NoSQL DB のインスタンスを作成済みであること

# 連携方法
以下の手順で Watson IoT Platform と Cloudant を連携させることができます。
　1. APIキーの発行
　2. Service binding の設定
　3. Connector の設定
　4. Destination の設定
　5. Forwarding ルール の設定

# 1. APIキーの発行
まずは、Watson IoT Platform の API を呼び出すための APIキーを発行します。

- Watson IoT Platform のインスタンスを開き、画面左のメニューから「Apps」を開きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/c83774c7-9cfa-0149-20e4-69bf1d888ebd.png)

- 「Browse API Keys」と書かれたページが表示されるので、右上の「Generate API Key」のボタンをクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/043f822d-265f-0303-5c35-064ee2657bbe.png)

- 「Description」を記述して次に進みます。ここで「API Key Expires」を ON にすると、APIキーの有効期限を設定できます。
- API呼び出しを行うアプリケーションのロールを選択して、「Generate Key」でAPIキーを発行します。アプリケーションのロールは実際に作成するアプリケーションの役割を選択しますが、ここでは「Standard Application（標準アプリケーション）」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/414c649f-900f-0f88-085d-e96587f61854.png)

- APIキーが発行されます。「API key」と「Authentication Token」は後の手順で使用するのでメモします。特に「Authentication Token」は後から確認することができないので注意します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/2b9be2be-ed66-4ecc-1202-f3aa2cbf24fe.png)


# 2. Service binding の設定
　1の手順で発行したAPIキーを使用して API を呼び出し、Cloudant 連携の設定を行います。通常は Curl や Postman 等のツールなどを使用して API を呼び出すと思いますが、Watson IoT Platform の APIリファレンス の 「Try it out」を使う方法が簡単なので、本記事ではそちらの方法を紹介します。

- 下記のURLの組織名を埋めてアクセスします。
    - https://{Watson IoT Platform の組織名}.internetofthings.ibmcloud.com/docs/index.html 
     
- 「IBM Watson IoT Platform REST APIs」というページが開くので、「Historian Connector」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/c55be5f9-bacf-bdfb-58df-3feff50075d6.png)


- Swagger の APIリファレンスが開きます。「Authorize」ボタンを選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/dfc4f881-a439-b857-ea11-c42309564be4.png)

- Username と Password の入力が求められますが、Username には、1の手順でメモした「API key」、Password には「Authentication Token」を入力して、「Authorize」をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/fc25475e-1882-a1a1-10b4-ffce5b44a4db.png)

- 認証が成功し、API 呼び出しが可能な状態になりました。

ここから、「Try it out」を利用して、実際に API を呼び出していきます。

- Services の「Register a service」を開き、「Try it out」をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/e72b5008-73f1-ef7f-59da-db0b54358f33.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/e62faec9-85d6-8893-0023-d29c4cac5468.png)

- 「Parameters」の「Example Values」に必要な情報を入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/7a079d8a-21de-2d1b-e2e0-b995fb78d3a6.png)

    - 「name」は作成する Service binding の名前です。
    - 「type」は "cloudant" と設定します。
    - 「credentials」は連携する Cloudant の Credential情報です。Cloudant のインスタンスを開き、「Service credentials」タブから取得することができます。
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/20c633c1-39b7-b1e6-8a4d-ba5e11c2bc1a.png)

- 「Execute」を押下してAPI呼び出しを行うと「Responses」に結果が返ってきます。成功すると201のステータスコードが返ってきます。ここで、Response body の「id」は次の「3. Connector の設定」で「serviceId」として使用するのでメモしておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/122591/95dbef58-1c39-efb5-65dc-25b16c22ed8c.png)

以降の手順でも同様に「Try it out」を利用します。

# 3. Connector の設定
- HistorianConnectors の「Create a connector」を開き、「Try it out」をクリックします。
- 「Parameters」の「Example Values」に必要な情報を入力します。
    - 「name」は作成する Connecter の名前です。
    - 「serviceId」は 2 の手順の最後にメモした「id」の値を記述します。
    - 「timezone」は Cloudant に保管されるデータのタイムスタンプが準拠するタイムゾーンです。日本時間にするには "JST" と記述します。
- 「Execute」を押下してAPI呼び出しを行うと「Responses」に結果が返ってきます。成功すると201のステータスコードが返ってきます。ここで、Response body の「id」は以降の手順で使用するのでメモしておきます。

# 4. Destination の設定
- Destinations の「Create a destination for a historian connector」を開き、「Try it out」をクリックします。
- 「connectorId 」に 3 の手順の最後にメモした「id」の値を記述します。
- 「Parameters」の「Example Values」に必要な情報を入力します。
    - 「name」は作成する Destination の名前です。Cloudant に作成されるDB名（テーブル名）に使用されます。
    - 「type」は "cloudant" と設定します。
    - 「configuration」では、Cloudant に保管されるデータをどの期間保持するかを設定します。設定した期間より古いデータは自動的に削除されます。「configuration」内のパラメーターとしては、保持期間の単位（日単位、週単位など）を設定する「bucketInterval」と保持日数を設定する「retentionDays」が設定できます。
    - 「configuration」の例1（データを1日分保持する設定）
        - {"bucketInterval": "DAY","retentionDays": 1}
    - 「configuration」の例2（データを2週分保持する設定）
        - {"bucketInterval": "WEEK","retentionDays": 14}
- 「Execute」を押下してAPI呼び出しを行うと「Responses」に結果が返ってきます。成功すると201のステータスコードが返ってきます。
- Cloudant 内のデータの保管先（テーブル）を振り分ける場合、例えばデバイスごとにデータを分けて保管したい場合などは、この Destination を複数作成します。

# 5. Forwarding ルール の設定
- Forwarding Rules の「Create a forwarding rule for a historian connector」を開き、「Try it out」をクリックします。
- 「connectorId 」に 3 の手順の最後にメモした「id」の値を記述します。
- 「Parameters」の「Example Values」に必要な情報を入力します。
    - 「name」は作成する Forwarding ルール の名前です。
    - 「type」は "event" と設定します。
    - 「selector」では、データの収集元（デバイスなど）の設定を記述することができます。「selector」内のパラメーターとしては、Watson IoT Platform で設定するデバイスタイプの「deviceType」と収集するイベントの識別子である「eventId」が設定できます。
    - 「selector」の例（センサーで人を検知したデータを収集する設定）
        - {"deviceType": "sensor","eventId": "detect_human"}
- 「Execute」を押下してAPI呼び出しを行うと「Responses」に結果が返ってきます。成功すると201のステータスコードが返ってきます。

# 終わりに
　1~5の設定が完了すると、Watson IoT Platform で収集したデータが自動的に Cloudant に保管されるようになっているはずです。
　Cloudant には、日毎に「iotp_{{Watson IoT Platform の組織名}_{Destination名}_yyyy-mm-dd」という名前で DB（テーブル）が作成され、そこにデータが保管されます。

# 参考
- 公式ドキュメント「Data store connector for Cloudant NoSQL DB」
    - https://www.ibm.com/support/knowledgecenter/SSQP8H/iot/platform/reference/dsc/cloudant.html