本文へジャンプします。

ニフクラ ユーザーガイド

クラウド トップ>ユーザーガイド>IoTデバイスハブ>既存のWebサービスへIoTデバイスハブを組み込む

既存のWebサービスへIoTデバイスハブを組み込む

ほとんどの場合、IoTデバイスハブを、IoTシステムのコアクラウドサービスとして利用します。

デバイスとモバイルアプリは、直接IoTデバイスハブと通信します。
IoTデバイスハブには、ユーザーからの登録リクエストとログインリクエストを処理するユーザーアカウントシステムが組み込まれてるので、独自のユーザーデータベースをセットアップする必要はありません。

ただし、既存のWebサービスとそのユーザーアカウントシステムをすでに利用している場合は、IoTデバイスハブを、デバイスの接続・所有権・アクセスの管理のみを行うバックエンドシステムとして利用することができます。

このように、IoTデバイスハブはさまざまな用途に対応しているため、既存のWebサービスとシームレスに連携することが可能です。

システムアーキテクチャー

下図は、IoTデバイスハブやシステムのほかのコンポーネントに関連して、どのようにサーバーを配置できるかを示しています。

ユーザーは、モバイルアプリまたはWebアプリを使って、直接Webサービスと通信します。
サーバーは、ユーザー登録・検証・ログインなどの処理と、ユーザーデータベースの管理を行います。
一方、デバイスは直接IoTデバイスハブと通信します。

IoTデバイスハブを必要とするアクションを実行する場合、ユーザーはWebサービスを呼び出します。
サーバーは、サービスに対して実装した認証スキームを使用してユーザーのリクエストを認証します。

続いて、ユーザーの代わりにサーバーがIoTデバイスハブ APIに対して、適切なRESTリクエストを行って、アクションを実行します。

プロジェクトのセットアップ

このようなシステムを構築するには、ユーザーアカウントを処理するための特別な権限をサーバーに与えるプロジェクトを作成する必要があります。
プロジェクトの作成時に「ユーザーアカウント」オプションで、「他のシステムでユーザを管理します。」を選択してください。

この方法で作成したプロジェクトを「BYOU(Bring-Your-Own-Users)プロジェクト」と呼びます。
プロジェクトの作成後にこのオプションを変更することはできないので注意してください。間違った場合は、プロジェクトを削除して新しいプロジェクト作成してください。

新しく作成したプロジェクトで「設定」の「APIキー」セクションで「+新規」ボタンをクリックし、名前を入力し、保存ボタンをクリックしてください。

作成したAPIキーをクリックして表示される「APIキーの詳細」画面の右上にある編集ボタンをクリックし、パーミッションで「BYOUを扱うことができます」を選択し、保存ボタンをクリックします。

次の操作で使用するため、APIキーをメモして置いてください。

IoTデバイスハブへユーザーをリンクする

ご使用のWebサービスが独自のユーザーデータベースを使っていても、IoTデバイスハブを使用してデバイスの所有権とアクセス制御を管理するには、 アクティブユーザーそれぞれに対して、IoTデバイスハブ内のユーザーエントリーへのリンクを設定する必要があります。

例えば、新しいユーザーがサービスに登録したばかりだとします。
そのユーザーのアカウントエントリーをデータベース内に作成すると、サーバーは、IoTデバイスハブ APIの/usersエンドポイントに対するPOSTリクエストを行って、このユーザーをIoTデバイスハブ内でもセットアップする必要があります。

次のcURLの例に示すように、このリクエストでは、「Authorization HTTPヘッダー」で説明した管理APIキーを使用する必要があります。
(ADMIN_API_KEY、PROJECT_IDは、実際のAPIキーとプロジェクトIDに置き換えてください。)

$ curl -i -N -H "Authorization: ModeCloud ADMIN_API_KEY" -H "Content-Type: application/json" -d '{"projectId":PROJECT_ID}' https://iot-device.jp-east-1.api.cloud.nifty.com/users

リクエストが成功すると、レスポンスは次のようになります。

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Location: /users/26
Date: Wed, 29 Jun 2016 00:03:57 GMT
Content-Length: 99

{"id":77,"projectId":PROJECT_ID,"verified":true,"name":"","creationTime":"2016-06-29T09:03:57.814+09:00"}

上の例では、ID 77を持つユーザーエントリーが作成されています。
続いて、IoTデバイスハブ APIの/auth/userエンドポイントに対するPOSTリクエストを行って、このユーザーのAPIキーを取得します。

この場合も、リクエストのAuthorizationヘッダーで管理APIキーを使用してください。
次に例を示します。(PROJECT_IDは実際のプロジェクトIDに置き換えてください。)

$ curl -i -N -H "Authorization: ModeCloud ADMIN_API_KEY" -d "projectId=PROJECT_ID&userId=77" https://iot-device.jp-east-1.api.cloud.nifty.com/auth/user

レスポンスは次のようになります。ここで、API_KEYはユーザーに割り当てられたAPIキーです。

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Date: Wed, 29 Jun 2016 00:06:28 GMT
Content-Length: 104

{"token":"API_KEY","userId":77}

IoTデバイスハブで割り当てられたユーザーIDとAPIキーの両方を、ユーザーのその他のアカウント情報と共にデータベースに保存する必要があります。

これで、この例のユーザーはIoTデバイスハブのユーザー77にリンクされました。
以降、このユーザーのためにIoTデバイスハブ APIを呼び出する必要がある場合は、常に、サーバーはデータベースからAPIキーを検索し、それをリクエストのAuthorizationヘッダーで使用する必要があります。

IoTデバイスハブ APIの一般的な使い方

上記の手順でユーザーをセットアップしたら、通常のプロジェクトとほぼ同じ方法でIoTデバイスハブ APIを使用できます。
例えば、ユーザーのAPIキーを使用して、APIの呼び出しを行い、ホームの作成・ホームへのデバイスの追加・デバイスへのコマンドの発行などを実行できます。

ただし、メンバーをホームに追加する方法は例外です。
誰かをホームに追加する場合、そのユーザーのユーザーIDがわかっていないと追加できません。

ユーザーが自分のホームにメンバーを追加したい場合は、次の手順で実装できます。

ユーザーデータベースでユーザーを検索します。

既存ユーザーである場合

割り当てられているユーザーIDを取得します。
IoTデバイスハブ APIを呼び出して、ユーザーを新規メンバーとしてホームに追加します。

既存ユーザーでない場合

データベースに新しいユーザーエントリーを作成します。
前述の手順でIoTデバイスハブ内に新規ユーザーをセットアップし、割り当てられたユーザーIDを取得します。
IoTデバイスハブ APIを呼び出して、ユーザーを新規メンバーとしてホームに追加します。

追加された新規メンバーに通知します。

特定のアプリケーションによっては、別の方法でこのフローを実装できます。
例えば、招待者にメールを送信し、その確認を待ってから実際のデータベース操作とAPI操作を実行できます。

イベントの伝搬と処理

ユーザーは、直接IoTデバイスハブと通信するのではなくWebサービスと通信するので、イベントの伝搬と処理の取り扱いには特別な考慮が必要です。

プロジェクトにスマートモジュールを追加することが、解決策の1つです。

スマートモジュールは、Webサービス内の特別なURLを指すEvent Webhookを使って構成する必要があります。

デバイス(または別のスマートモジュール)がイベントを生成すると、常にこのURLが呼び出され、このURLのハンドラーがWebサービスのコンテキストに従ってイベントを解釈して処理します。

例えば、データベースを更新したり、ユーザーにプッシュ通知を送信したりできます。

推奨画面サイズ 1024×768 以上