API の実行

MQTT のコネクションを確立したら、API を送信できます。

MQTT 経由で API を呼び出す際は、リクエストとレスポンスのそれぞれを、PUBLISH コマンドでやりとりします。機能ガイドの MQTT と HTTPS のマッピング に PUBLISH コマンドによる API の実行例を示します。

ここでは、HTTPS の形式を MQTT に変換する方法の詳細を示します。Thing Interaction Framework（Thing-IF）API リファレンス および REST API ガイド は、HTTPS での実行を想定して記載されています。MQTT プロトコルを利用する際は、以下に示すルールに従ってリクエストとレスポンスの両方を変換します。

ここでは、ステートの登録 の API を例に、変換方法を説明します。他の API も同様の方法で変換できます。

リクエスト

MQTT プロトコルでリクエストを送信するには PUBLISH コマンドをクライアントから送信します。

ステートを登録するコマンドは、リファレンスガイドに以下のように記載されています。この API を PUBLISH コマンドに変換します。

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/states" \
  -d '{"power":true, "presetTemperature":25, "fanspeed":5, "currentTemperature":28, "currentHumidity":65}'

MQTT トピック

MQTT トピック名の階層構造によって実行対象の機能を指定します。PUBLISH コマンドの送信先の MQTT トピックは、HTTPS の URL に対応します。MQTT トピック名 p/{CLIENT_ID}/thing-if/apps/{APP_ID}/ の後に、HTTPS の URL の /{APP_ID}/ 以下のパスをつなげます。

{CLIENT_ID} 部分には、CONNECT コマンドの Client identifier として指定した値（初期登録のレスポンス の "mqttTopic"）を設定します。

上記のステートの登録の例では、curl コマンドの URL から、以下が送信対象の MQTT トピックになります。

p/{CLIENT_ID}/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/states

ペイロード

ペイロードには、実行する API の HTTP 動詞、HTTP ヘッダー、空行、HTTP ボディーを指定します。改行コードは CR LF としてテキスト形式で整形します。

変換ルールは以下のとおりです。

  • 1 行目には、HTTP 動詞を指定します。使いたい API の書式に従って、GET、HEAD、POST、PUT、PATCH、DELETE を指定します。

  • 2 行目以降には、HTTP ヘッダーを記述します。指定する HTTP ヘッダーは、サンプルコードや REST API ガイドで指示があったものを以下のルールで書き換えます。

    • X-Kii-AppID、X-Kii-AppKey ヘッダーは不要です。コネクションが接続先アプリケーションを認識しています。

    • 以下のヘッダーは指定しても無視されます。

      Access-Control-Request-Method、Access-Control-Request-Headers、Connection、Content-Length、Expect、Host、Max-Forwards、Origin、Proxy-Authorization、TE、Transfer-Encoding、Upgrade、Via

    • X-Kii-RequestID として、クライアント側でリクエストに一意となる {REQUEST_ID} を割り当てて、リクエストとレスポンスの対応を取ることができます。API のレスポンスはサーバー側からの PUBLISH コマンドで通知されますが、この際にリクエストで指定した値が X-Kii-RequestID ヘッダーとして返されます。

    • Kii Cloud でのペイロードのサイズの上限は 1 MB です。これ以上のサイズのペイロードを持ったコマンドリクエストとして送信すると、MQTT ブローカー側からコネクションが切断されます。なお、レスポンスのサイズには制限がありません。

  • HTTP ヘッダーと HTTP ボディーの間には空行を 1 行入れます。

  • 最後に HTTP ボディー部分を指定します。

このルールに従って、上記のステート登録の curl コマンドを変換すると、以下のようなペイロードになります。

PUT
Authorization: Bearer {ACCESS_TOKEN}
X-Kii-RequestID: {REQUEST_ID}
Content-Type: application/json

{"power":true, "presetTemperature":25, "fanspeed":5, "currentTemperature":28, "currentHumidity":65}

ここでは curl コマンドに合わせて以下を指定しています。

  • HTTP 動詞は PUT を指定します。

  • HTTP ヘッダーは、curl コマンドのサンプルコードにあるヘッダー 2 点を記述してから、X-Kii-RequestID ヘッダーを追加します。

  • HTTP ボディーは、サンプルコードのものをそのまま指定します。

レスポンス

サーバーからの応答は、サーバー側からの PUBLISH コマンドによって通知されます。

MQTT トピック

PUBLISH コマンドの MQTT トピック名は、リクエストで指定した MQTT トピック名がそのまま返されます。

PUBLISH コマンドは様々な目的で受信するため、サーバー側からの PUBLISH コマンドを受け取った際には、必ず MQTT トピック名をチェックするように実装してください。また、未知の MQTT トピック名を持つ PUBLISH コマンドは、将来の拡張のため無視するように実装してください。

ペイロード

ペイロードには、実行した API の結果が含まれます。HTTP ステータスコード、HTTP ヘッダー、空行、HTTP ボディーが返されます。改行コードは CR LF としてテキスト形式で整形されています。

ステート登録の例では、以下のような情報が PUBLISH コマンドのペイロードとして返されます。これは、HTTP ボディーを含まない返信の例です。

204
Accept-Ranges:bytes
Age:0
Cache-Control:max-age=0, no-cache, no-store
Date:Fri, 27 May 2016 05:44:18 GMT
Connection:keep-alive
X-Kii-RequestID:{REQUEST_ID}

ステート取得のようにHTTP ボディーを含む場合、以下のような形式で返されます。

200
Accept-Ranges:bytes
Age:0
Cache-Control:max-age=0, no-cache, no-store
Content-Type:application/json
Date:Tue, 31 May 2016 04:59:52 GMT
Connection:keep-alive
X-Kii-RequestID:{REQUEST_ID}

{
  "power" : true,
  "presetTemperature" : 25,
  "fanspeed" : 5,
  "currentTemperature" : 28,
  "currentHumidity" : 65
}

HTTPS による REST API の結果との対応は以下のように行います。

  • 1 行目は REST API が返す HTTPS のステータスコードです。成功時が 2xx、クライアントエラーが 4xx など、そのままステータスコードに対応しています。ステータスコードの詳細は Thing Interaction Framework（Thing-IF）API リファレンス の各 API の説明をご覧ください。

  • 2 行目以降は HTTP ヘッダーです。

    • HTTPS で REST API を実行した際に返されるヘッダーのうち、以下のものは MQTT プロトコルでは返されません。

      Access-Control-Allow-Origin、Access-Control-Allow-Credentials、Access-Control-Expose-Headers、Access-Control-Max-Age、Access-Control-Allow-Methods、Access-Control-Allow-Headers、Content-Length、Server、Trailer、Transfer-Encoding、Upgrade、Via

    • X-Kii-RequestID として、リクエスト時に指定した {REQUEST_ID} が返されます。これによってリクエストとの対応が取れます。

  • HTTP ヘッダーと HTTP ボディーの間には空行が 1 行入ります。

  • 最後に HTTP ボディー部分が返されます。

HTTP ボディーがないレスポンスでは、空行以降の情報が返されません。