プッシュ通知利用の準備

プッシュ通知を利用するために必要な準備は以下の 2 つです。

インストール

Kii Cloud に対象となる Thing をインストールします。Kii Cloud は、インストールされた Thing に MQTT ベースのプッシュ通知を送信する各種準備を行います。
MQTT コネクションの確立

プッシュ通知を受け取るための MQTT コネクションを確立します。.

インストール

Thing のインストール

Thing またはアプリ管理者は、Thing をインストールできます。

まず Thing が自身のアクセストークンを用いてインストールを行う例を挙げます。例のように "deviceType" フィールドには "MQTT" を指定します。"development" フィールドには、今回のインストールが開発環境向けなのか配布環境向けなのかを指定します。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.InstallationCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations" \
  -d '{
        "deviceType": "MQTT",
        "development": true
      }'

次にアプリ管理者トークンを使いインストールを行う例を挙げます。この場合は対象 Thing の ThingID を明示的に指定してください。

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.InstallationCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations" \
  -d '{
        "thingID": "{THING_ID}",
        "deviceType": "MQTT",
        "development": true
      }'

いずれの場合も、インストールが成功すると Kii Cloud は 201 応答を返します。

201 Created

Content-Type: application/vnd.kii.InstallationCreationResponse+json
Location: /apps/<appID>/installations/{INSTALLATIN_ID}
{
  "installationID" : "{INSTALLATION_ID}",
  "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID}"
}

インストールの確認

Thing オーナーとアプリ管理者は、完了したインストールの詳細を確認できます。

以下にインストール詳細を確認する例を挙げます。ここでは、確認対象の Installation ID を指定します。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}"

Kii Cloud はインストール詳細を 200 応答として返します。

200 OK

Content-Type: application/vnd.kii.InstallationRetrievalResponse+json
{
  "installationID" : "{INSTALLATION_ID}",
  "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID}"
  "development" : true,
  "thingID" : "{THING_ID}",
  "deviceType" : "MQTT"
}

インストール一覧を取得

Thing オーナーとアプリ管理者は、ある Thing に対して実施されたインストールの一覧を取得できます。

以下にインストール一覧を取得する例を挙げます。ここでは、確認対象の Thing を ThingID で指定します。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations?thingID={THING_ID}"

Kii Cloud はインストール一覧を 200 応答として返します。

200 OK

Content-Type: application/vnd.kii.InstallationsRetrievalResponse+json
{
  "installations" : [ {
    "installationID" : "{INSTALLATION_ID_1}",
    "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID_1}",
    "development" : true,
    "thingID" : "{THING_ID_1}",
    "deviceType" : "MQTT"
  }, {
    "installationID" : "{INSTALLATION_ID_2}",
    "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID_2}",
    "development" : true,
    "thingID" : "{THING_ID_2}",
    "deviceType" : "MQTT"
  } ]
}

インストールの削除

Thing オーナーとアプリ管理者はインストールを削除できます。この際、削除対象のインストールは Installation ID と Installation Registration ID のいずれかで指定します。

まず Intallation ID を使いインストールを削除する例を挙げます。

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}"

次に Intallation Registration ID を使いインストールを削除する例を挙げます。この場合、Registration ID とともに Installation Type（ANDROID、IOS、または MQTT）の指定が必要です。

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/MQTT:{INSTALLATION_REGISTRATION_ID}"

インストールの削除に成功すると Kii Cloud は 204 応答を返します。

MQTT コネクションの確立

Thing プッシュ通知を受け取るには、MQTT ブローカーへの接続および MQTT トピックの購読が必要です。このためには、まず MQTT エンドポイントを Kii Cloud より取得し、取得した情報を元に MQTT コネクションを確立しなければなりません。

MQTT エンドポイントの取得

Thing オーナーとアプリ管理者は MQTT エンドポイントを取得できます。

以下に例を示します。

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}/mqtt-endpoint"

MQTT エンドポイントの準備が完了している場合、Kii Cloud はエンドポイントを 200 応答で返します。応答内の X-MQTT-TTL は、エンドポイント内の MQTT トピックの有効期限（秒）です。

200 OK

Content-Type: application/vnd.kii.MQTTEndpointResponse+json
{
  "installationID" : "{INSTALLATION_ID}",
  "username" : "{USERNAME}",
  "password" : "{PASSWORD}",
  "mqttTopic" : "{MQTT_TOPIC}",
  "host" : "{BROKER_HOST}",
  "portTCP" : {PORT_TCP},
  "portSSL" : {PORT_SSL},
  "portWS" : {PORT_WS},
  "portWSS" : {PORT_WSS},
  "X-MQTT-TTL" : {MQTT_TTL}
}

MQTT エンドポイントの準備は Thing のインストールを契機に開始されます。もし MQTT エンドポイントを取得を要求した時点でエンドポイントの準備ができていない場合、Kii Cloud は次のように 503 応答を返します。

503 Service Unavailable

Content-Type: application/vnd.kii.MQTTEndpointNotReadyException+json
Retry-After: 10
{
  "errorCode" : "MQTT_ENDPOINT_NOT_READY",
  "message" : "MQTT endpoint for  {INSTALLATION_ID} is not ready. Please try again later.",
  "installationID" : "{INSTALLATION_ID}",
  "appID" : "{APP_ID}"
}

応答内の "Retry-After" ヘッダーには、再度リクエストを送信するまでの待ち時間（秒）が入ります。503 応答を受信した場合、この待ち時間の後、再度同じ要求を行ってください。

MQTT コネクションの確立

MQTT エンドポイントの取得が完了すると、MQTT コネクションを確立する（i.e. MQTT ブローカーに接続し MQTT トピックを購読する）ために必要な情報がすべて揃います。

MQTT コネクションの確立には任意の外部ライブラリーが利用できます。利用可能なライブラリーの例は、たとえば MQTT.org が公開しているこちらのリストを参照してください。

接続に必要な情報

MQTT トピック講読の際には、以下の情報を利用します。

接続に必要な情報	設定する値
接続先ホスト名	MQTT エンドポイントの取得レスポンスの "host"
接続先ポート番号	MQTT エンドポイントの取得レスポンスの "portTCP"（TCP 接続）または "portSSL"（SSL/TLS 接続）
WebSocket 接続用ポート番号	MQTT エンドポイントの取得レスポンスの "portWS"（TCP 接続）または "portWSS"（SSL/TLS 接続）
CONNECT コマンドの Keep alive timer	アプリの実装に合わせて送信（キープアライブタイマー参照）
CONNECT コマンドの Client identifier	MQTT エンドポイントの取得レスポンスの "mqttTopic"
CONNECT コマンドの Username	MQTT エンドポイントの取得レスポンスの "username"
CONNECT コマンドの Password	MQTT エンドポイントの取得レスポンスの "password"
SUBSCRIBE コマンドの Topic name	MQTT エンドポイントの取得レスポンスの "mqttTopic"

キープアライブタイマー

MQTT では、コネクションが切れていないことを確認するためにキープアライブタイマーによる死活監視の方法が定められています。

MQTT プロトコルでは、CONNECT コマンドで送信した Keep alive timer 値の 1.5 倍の時間以内に、クライアントから何らかのメッセージを送信しないと、コネクションは自動的に切断されます。この時間内にクライアントからのメッセージ送信がない場合、PINGREQ コマンドを送信する必要があります。実装方法は使用する MQTT ライブラリーのドキュメントを参照してください。

MQTT クライアントの実装後は、送信コマンドがない状態でしばらく放置し、その後、コネクションが切れないことを確認しておくことをお勧めします。コネクションが一定時間で切れる場合、PINGREQ コマンドが送信されていない可能性があります。