リアルタイム通知

概要

本セクションでは、Things Cloudにおけるリアルタイム通知サービスすべてに共通する側面を説明します。

各サービスは固有の接続チャネル名形式とURLを有しており、これらについてはRESTインターフェース関連資料の「通知」セクションに記載されています。リアルタイム通知は以下を対象に利用可能です。

リアルタイム通知APIは、制限のあるネットワーク上における、WebブラウザやモバイルデバイスなどクライアントへのThings Cloudからの応答性の良い通信を可能にします。クライアントはいわゆるチャネルに接続してメッセージを受信します。これらのチャネルは Things Cloudにより、イベント言語または新たに作成されたオペレーションで埋められます。加えて、特定のシステムチャネルがクライアントとの初期ハンドシェイク、チャネルへの接続、チャネルからの離脱および接続に使用されます。通信メカニズムとして、HTTPSまたはWSS上でのBayeuxプロトコルが使用されます。

注記:ロングポーリングを使用する際、すべてのPUT/POSTリクエストについて、Acceptヘッダーを使用すべきであり、さもなければ空の応答本体が返されます。

ハンドシェイク

リアルタイム通知クライアントは「/meta/handshake」チャネルにメッセージを送信することにより、接続交渉を開始します。応答として、クライアントは「clientId」を受信し、これが会話を識別する役割を果たしますが、これはあらゆる非ハンドシェイクリクエストにおいて渡されなければなりません。Webソケットを使用する場合は、認証オブジェクトを含む 「ext」プロパティも送信する必要があります。基本認証の場合、base64で暗号化された「トークン」が証明書として使用されます。OAuth認証の場合、リクエストにはアクセス・トークンを保持する許可名を持つCookieが必要です。さらに、XSRFトークンをハンドシェークメッセージの一部として転送する必要があります。

{ "ext": { "com.cumulocity.authn": { "token": "" "tfa": "", "xsrfToken": "", } "systemOfUnits": "" } }

Property Value
token Base 64 encoded credentials
tfa Optional two factor authentication token
xsrfToken Required for OAuth authentication
systemOfUnits Optional system of units. Possible values are "imperial" or "metric"

Request

名称 種別 発生回数 説明
id Integer 1 メッセージのID。応答メッセージと一致する必要があります。
channel URI 1 チャネル名。必要な値:/meta/handshake
ext Object 1 ハンドシェイクに渡される認証オブジェクト。(ウェブソケット上のみ)
version String 1 クライアントが使用するBayeuxプロトコルのバージョン
minimumVersion String 0..1 クライアントが要求する最低限のサーバー側Bayeuxプロトコルのバージョン
supportedConnectionTypes Array 1 クライアントがサポートする接続種別のリスト
advice Object 0..1 セッション構成設定パラメータ

Advice

名称 種別 発生回数 説明
timeout Integer 0..1 接続メッセージの送信とサーバーからの応答の最大間隔(ミリ秒単位)。 サーバーのデフォルトのセッション設定をオーバーライドします。デフォルト値:5400000、最大値:7200000
interval Integer 0..1 クライアントがロングポーリング要求の終了から次のポーリング要求の開始まで待機する必要がある時間(ミリ秒単位)。 セッションのサーバーのデフォルト設定をオーバーライドします。 設定されていない場合、サーバーは次の接続要求まで時間として最大10秒間許容します。デフォルト値:0

リクエスト例:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "ext": {
      "com.cumulocity.authn": {
        "token": "<base64 encoded credentials>"
      }
    }
    "version": "1.0",
    "mininumVersion": "1.0beta",
    "supportedConnectionTypes": ["websocker","long-polling"],
    "advice":{"timeout":120000,"interval":30000}
  }
]

応答

名称 種別 発生回数 説明
id Integer 1 リクエストメッセージにおいて渡されるメッセージのID
channel URI 1 チャネル名。必要な値:/meta/handshake
version String 0..1 サーバーが使用するBayeuxプロトコルのバージョン
minimumVersion String 0..1 サーバーが要求する最低限のクライアント側Bayeuxプロトコルのバージョン
supportedConnectionTypes Array 0..1 クライアントとサーバー双方がサポートする接続種別(すなわちクライアントのオプションとサーバーのオプションの交差)
clientId String 0..1 サーバーによって生成される一意のクライアントID
successful Boolean 1 ハンドシェイクの結果
error String 0..1 ハンドシェイク失敗理由

応答成功例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "version": "1.0",
    "minimumVersion": "1.0beta",
    "supportedConnectionTypes": ["websocker"],
    "clientId": "Un1q31d3nt1f13r",
    "successful": true
  }
]

応答失敗例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/handshake",
    "successful": false,
    "error":"403::Handshake denied"
  }
]

チャネル接続

通知クライアントは、Things Cloudサーバーからの出力メッセージを受信するための希望チャネルを指定した上で、チャネル接続メッセージを送信することができます。クライアントは接続リクエストに成功するとメッセージを受信することになります。

チャネル名の形式は、リアルタイム通知サービスを使用するREST APIによって異なります。詳しくは以下のセクションをご覧ください。

  • リアルタイムステートメント
  • デバイス制御

リクエスト

名称 種別 発生回数 説明
id Integer 1 メッセージのID。応答メッセージと一致する必要があります。
channel String 1 チャネル名。必要な値:/meta/subscribe
clientId String 1 ハンドシェイク中に受信したクライアントの一意のID
subscription String 1 接続チャネル名

リクエスト例:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/subscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/alarms/overHeatAlarms"
  }
]

応答

名称 種別 発生回数 説明
id Integer 1 リクエストメッセージにおいて渡されるメッセージのID
channel URI 1 チャネル名。必要な値:/meta/subscribe
clientId String 1 クライアントの一意のID
subscription String 1 チャネル名
successful Boolean 1 チャネル接続の結果
error String 0..1 チャネル接続失敗理由

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/subscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/alarms/overHeatAlarms",
    "successful": true,
    "error": ""
  }
]

チャネル接続解除

チャネルからの通知受信を止めたい場合、チャネル接続時に使用したものと同じ形式のチャネル名を指定した上で、「/meta/unsubscribe」にメッセージを送信します。

リクエスト

名称 種別 発生回数 説明
id Integer 1 メッセージのID。応答メッセージと一致する必要があります。
channel URI 1 チャネル名。必要な値:/meta/unsubscribe
clientId String 1 ハンドシェイク中に受信したクライアントの一意のID
subscription String 1 チャネル名

リクエスト例:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/unsubscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/CepModuleName/CepStatementName"
  }
]

応答

名称 種別 発生回数 説明
id Integer 1 リクエストメッセージにおいて渡されるメッセージのID
channel URI 1 チャネル名。必要な値:/meta/unsubscribe
clientId String 1 クライアントの一意のID
subscription String 1 接続チャネル名
successful Boolean 1 チャネル接続解除の結果
error String 0..1 チャネル接続解除失敗理由

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/unsubscribe",
    "clientId": "Un1q31d3nt1f13r",
    "subscription": "/CepModuleName/CepStatementName",
    "successful": true,
    "error": ""
  }
]

接続

Bayeuxクライアントがサーバーにおけるハンドシェイク交換を確認し、所望のチャネルへの接続を完了したら、「/meta/connect」チャネルへのメッセージ送信によって接続が確立されます。このメッセージは、ハンドシェイク応答においてサーバーから返される任意のチャネル経由で送信可能です。接続チャネルへのリクエストは応答後すぐに返答され、この処理は繰り返されます。

リクエスト

名称 種別 発生回数 説明
id Integer 0..1 メッセージのID。応答メッセージと一致する必要があります。
channel URI 1 チャネル名。必要な値:/meta/connect
clientId String 1 ハンドシェイク中に受信したクライアントの一意のID
connectionType String 1 選択された接続種別
advice Object 0..1 現在の接続メッセージ向けの構成設定パラメータ

Advice

名称 種別 発生回数 説明
timeout Integer 0..1 接続メッセージの送信とサーバーからの応答の最大間隔。サーバーにおける現在のリクエスト/応答会話に関するデフォルトの設定を上書きします。
interval Integer 0..1 サーバーがクライアントから次の接続メッセージを受信しない場合にセッションを閉じるまでの期限 サーバーにおける現在のリクエスト/応答会話に関するデフォルトの設定を上書きします。

リクエスト例:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/connect",
    "clientId": "Un1q31d3nt1f13r",
    "connectionType": "long-polling",
    "advice":{"timeout":1200000,"interval":30000}
  }
]

応答

名称 種別 発生回数 説明
id Integer 0..1 リクエストメッセージにおいて渡されるメッセージのID
channel URI 1 チャネル名
clientId String 1 クライアントの一意のID
successful Boolean 1 接続結果
data Array 1 チャネルからの通知のリスト
error String 0..1 接続失敗理由

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/cepModuleName/cepStatementName",
    "successful": true,
    "error": "",
    "data": [{
       "id" : "10",
       "self" : "...",
       "creationTime" : "2011-09-06T12:03:27.927+02:00",
       "type" : "com_cumulocity_model_DoorSensorEvent",
       "time" : "2011-09-06T12:03:27.845+02:00",
       "text" : "Door sensor was triggered.",
       "com_othercompany_Extension" : { ... },
       "source":{ "id":"12345", "self": "..." }
    }],
    "clientId": "Un1q31d3nt1f13r"
  },{
    "channel": "/cepModuleName/cepStatementName",
    "successful": true,
    "error": "",
    "data": [{
       "id" : "11",
       "self" : "...",
       "creationTime" : "2011-09-06T12:03:27.927+02:00",
       "type" : "com_cumulocity_model_DoorSensorEvent",
       "time" : "2011-09-06T12:03:27.845+02:00",
       "text" : "Door sensor was triggered.",
       "com_othercompany_Extension" : { ... },
       "source":{ "id":"12345", "self": "..." }
    }],
    "clientId": "Un1q31d3nt1f13r"
  },
  {
    "channel":"/meta/connect",
    "successful":true
  }
]

接続解除

すべてのチャネルからの通知受信を止めたい場合、「/meta/disconnect」にメッセージを送信します。

リクエスト

名称 種別 発生回数 説明
id Integer 0..1 メッセージのID。応答メッセージと一致する必要があります。
channel URI 1 チャネル名。必要な値:/meta/disconnect
clientId String 1 ハンドシェイク中に受信したクライアントの一意のID

応答例:

POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
  {
    "channel": "/meta/disconnect",
    "clientId": "Un1q31d3nt1f13r",
  }
]

応答

名称 種別 発生回数 説明
id Integer 0..1 リクエストメッセージにおいて渡されるメッセージのID
channel URI 1 チャネル名。必要な値:/meta/disconnect
successful Boolean 1 接続解除オペレーションの結果
clientId String 1 ハンドシェイク中に受信したクライアントの一意のID
error String 0..1 接続解除失敗理由

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/meta/disconnect",
    "clientId": "Un1q31d3nt1f13r",
    "successful": true
  }
]

ネットワークトラフィック

ロングポーリング経由での通知のリスニングは、タイムアウトの選択に応じて一定のトラフィックを生じます。下表は、タイムアウトを1時間、リクエスト間の間隔なしと想定した場合のロングポーリングリクエストによって生じるトラフィックのリストです。計算には受信した通知およびセッション再接続は含まれません。

期間 トラフィック
7 kB
50 kB
210 kB

ハンドシェイクまたは接続の間、クライアントはタイムアウトや間隔などデフォルトのサーバー接続設定を上書きすることができます。ロングポーリングトランスポートの場合、クライアントはタイムアウト値を渡すことにより、ロングポーリングリクエスト期間を変更することができます。タイムアウト値を長めにすると、リクエスト/応答メッセージの送信に必要なトラフィックが減りますが、接続喪失の原因となるおそれがあります。またクライアントは間隔を長めに設定し、最後の応答の受信後に次の接続メッセージの送信を保留することもできます(その代わり、双方向性が低下します)。