リアルタイム通知

概要

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

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

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

注記:ロングポーリングを利用する場合、PUT / POSTリクエストに対して「accept」ヘッダーを使用する必要があります。そうでない場合は、空の応答本体が返されます。

備考: ロングポーリングインターフェイスは、カスタムアプリケーションがThings Cloudからまれにしか発生しないイベントをポーリングするためのメカニズムとして設計されています。 ロングポーリングインターフェイスは、Things Cloudから大容量のデータ(>100kB/秒)や高頻度のデータ(>50 events/秒)をストリーミングするのに適してはいません。 このようなユースケースでは、ロングポーリングの使用はサポートされません。

ハンドシェイク

リアルタイム通知クライアントは「/meta/handshake」チャネルにメッセージを送信することにより、接続交渉を開始します。応答として、クライアントは「clientId」を受信し、これが会話を識別する役割を果たしますが、これはあらゆる非ハンドシェイクリクエストにおいて渡されなければなりません。

WebSocket を使用する場合は、認証オブジェクトを含む 「ext」プロパティも送信する必要があります。基本認証の場合、base64で暗号化された「トークン」が証明書として使用されます。OAuth認証の場合、リクエストにはアクセス・トークンを保持する認可名を持つCookieが必要です。さらに、XSRFトークンをハンドシェイクメッセージの一部として転送する必要があります。

{
  "ext": {
    "com.cumulocity.authn": {
      "token": "<base64 encoded credentials>",
      "tfa": "<tfa token>",
      "xsrfToken": "<xsrf token>",
    },
    "systemOfUnits": "<system of units>"
  }
}
プロパティ
token Base 64 エンコードされた認証情報
tfa 任意の二段階認証トークン
xsrfToken OAuth 認証に必須
systemOfUnits 任意の単位システム。値は次のいずれか:“imperial”、“metric”

リクエスト

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

リクエスト例:

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": ["websocket","long-polling"]
  }
]

応答

名称 タイプ 発生回数 説明
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.0",
    "supportedConnectionTypes": ["websocket"],
    "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/<Device ID>"
      }
    ]

応答

名称 タイプ 発生回数 説明
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/<Device ID>",
        "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 現在の接続メッセージ向けの構成設定パラメータ

アドバイス

名称 タイプ 発生回数 説明
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
  }
]