MQTT 経由での API の利用

MQTT プロトコルだけで Thing を実装するには、このページの実装方法に従います。

MQTT 経由での API の利用は、Thing から Thing Interaction Framework の機能を利用することを目的に設計されています。ユーザーのアクセストークンを使って操作したい場合や、Kii Cloud SDK の機能範囲を使用したい場合は HTTPS による通信が必要です。

通信の概要

MQTT で通信するように Thing を実装するには、以下の手順に従います。

  1. Thing の初期登録を行って接続先を取得する

    まず、デフォルトの MQTT ブローカーに匿名で接続して Thing の 初期登録 を行います。レスポンスとして、初期登録の結果と、リクエスト受付用の MQTT ブローカーの情報を取得できます。

    Kii Cloud ではデフォルトの MQTT ブローカーを用意しており、それらは固定の URL を持っています。一度、この MQTT ブローカーに匿名でアクセスし、使用する Thing を初期登録してから、実際のリクエストに使用する MQTT ブローカーへの接続情報を取得します。

  2. 接続して API を利用する

    得られた MQTT ブローカーに接続します。

    この MQTT ブローカーが実際に処理を受け付けるサーバーです。実際の Thing の制御に必要なリクエストは新しく接続したコネクションの上で送信されます。

通信例は以下のとおりです。

API のリクエストとレスポンスはどちらも PUBLISH コマンドで扱います。この際、PUBLISH コマンドのペイロードでリクエストやレスポンスの詳細情報を扱います。

以下にペイロードの概要を示します。ペイロードの指定方法の詳細は、Thing-IF 向け REST API ガイドの MQTT プロトコルだけでの実装 をご覧ください。

MQTT と HTTPS のマッピング

Kii Cloud の API は、HTTPS での利用を前提に設計されています。MQTT 経由で API を使用するには、HTTPS のリクエストとレスポンスを MQTT プロトコルにマッピングする必要があります。

リクエストは PUBLISH コマンドによって行います。PUBLISH コマンドでは、以下のように API のパラメーターを指定します。

  • PUBLISH コマンドの送信先の MQTT トピックを使って、リクエスト先 REST API の URL 階層を指定します。詳細は下記の MQTT トピック をご覧ください。

  • PUBLISH コマンドのペイロードによって、HTTP 動詞（POST/GET など）、HTTP ヘッダー、HTTP ボディーをテキスト形式で指定します。

Kii Cloud は、受け取った PUBLISH コマンドのペイロードを HTTPS 形式で解釈して機能を実行し、レスポンスをサーバー側からの PUBLISH コマンドにマッピングし直して返します。

  • MQTT クライアントが受け取る PUBLISH コマンドに含まれる MQTT トピック名は、リクエストで使用した MQTT トピック名です。

  • PUBLISH コマンドのペイロードには、HTTPS のステータスコード、HTTP ヘッダー、HTTP ボディーがテキスト形式で含まれます。

リクエストとレスポンスの対応付け

PUBLISH コマンドでは、ペイロードで指定するリクエスト ID によって、リクエストとレスポンスを対応付けることができます。

MQTT クライアントは、リクエストの際にコネクション内で一意になるようなリクエスト ID を生成し、X-Kii-RequestID ヘッダーとして指定します。API の実行後、サーバーはレスポンスの PUBLISH コマンドの HTTP ヘッダーに同じ ID を返します。クライアントは、受け取ったレスポンスとリクエストとの対応を取ることができます。

リクエスト ID は、クライアント側で解釈しやすい任意の文字列として生成することができます。

MQTT トピック

MQTT 経由で API を実行する場合、MQTT トピックは実行したい API の階層に従って複数個存在します。これらの MQTT トピックとの間で PUBLISH コマンドを直接送受信します。

下の図では、Thing Interaction Framework（Thing-IF）API リファレンス に示す REST API の階層に対応して、MQTT トピックを 3 個示しています。各 MQTT トピックは、REST API に定義されている機能に従って、図のような機能を持っています。

例えば、一番上の MQTT トピックは、REST API の /targets/thing:{targetID}/states に対応する MQTT トピックであるため、ステートの登録とステートの取得という 2 つの機能を実行できます。なお、2 つの機能のうち、実行される機能は PUBLISH コマンドのペイロードに記述した HTTP 動詞によって決まります。

プッシュ通知の併用

Thing Interaction Framework の機能を Thing で利用するには、Thing での処理がステートの登録のみである場合を除いて、プッシュ通知の併用が前提となります。Thing がモバイルアプリからの コマンド を受け取るためには、プッシュ通知が必要なためです。

プッシュ通知を利用するには、以下のように実装します。

  • デフォルト MQTT サーバーへの初期登録の際、MQTT トピック名が取得できます。API 実行用の MQTT ブローカーに接続した際、その MQTT トピックをプッシュ通知用として SUBSCRIBE コマンドで講読します。

  • プッシュ通知はサーバーからの PUBLISH コマンドで行われます。PUBLISH コマンドの MQTT トピック名がプッシュ通知用の MQTT トピックの名前と同じ場合、PUBLISH コマンドはプッシュ通知であることを表します。ペイロードをプッシュ通知の詳細情報として解釈します。

MQTT プロトコルでプッシュ通知を扱う方法は、MQTT 経由でのプッシュ通知の利用 をご覧ください。