概要
- 非推奨:/devicecontrol/notifications → 新:/notification/operations
- 非推奨:/cep/realtime → 新:/notification/realtime
本セクションでは、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 | string | 1 | リクエストメッセージで渡されるメッセージのID |
channel | string | 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 | string | 1 | メッセージのID。応答メッセージと一致する必要があります |
channel | string | 1 | URIとしてのチャネル名。必要な値:/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 | string | 1 | リクエストメッセージで渡されるメッセージのID |
channel | string | 1 | チャネルURIとしてのチャネル名。必要な値:/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 | string | 0..1 | メッセージのID。応答メッセージと一致する必要があります |
channel | string | 1 | チャネル名。必要な値:/meta/connect |
clientId | string | 1 | ハンドシェイク中に受信したクライアント固有のID |
connectionType | string | 1 | 選択された接続タイプ |
advice | Object | 0..1 | 現在の接続メッセージ向けの構成設定パラメータ |
アドバイス
名称 | タイプ | 発生回数 | 説明 |
---|---|---|---|
timeout | int | 0..1 | 接続メッセージの送信とサーバーからの応答の間隔。サーバーにおける現在のリクエスト/応答会話に関するデフォルトの設定を上書きします |
interval | int | 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": "/alarms/208",
"id": "79",
"data": {
"realtimeAction": "UPDATE",
"data": {
"severity": "MAJOR",
"creationTime": "2019-10-29T13:10:21.297Z",
"count": 2,
"history": {
"auditRecords": [],
"self": "https://[..]/audit/auditRecords"
},
"source": {
"self": "https://[..]/inventory/managedObjects/208",
"id": "208"
},
"type": "c8y_Application__BackOff",
"firstOccurrenceTime": "2019-10-29T13:10:21.000Z",
"self": "https://[..]/alarm/alarms/327",
"time": "2019-10-29T13:10:36.000Z",
"id": "327",
"text": "Back-off restarting failed container",
"status": "ACTIVE",
"c8y_Application__Metadata": {
"owner": "management",
"tenant": "management"
}
}
}
},
{
"advice": {
"interval": 0,
"timeout": 5400000,
"reconnect": "retry"
},
"channel": "/meta/connect",
"successful": true
}
]
接続解除
すべてのチャネルからの通知受信を止めたい場合、「/meta/disconnect」チャネルへメッセージを送信します。
リクエスト
名称 | タイプ | 発生回数 | 説明 |
---|---|---|---|
id | string | 0..1 | メッセージのID。応答メッセージと一致する必要があります |
channel | string | 1 | URIチャネル名。必要な値:/meta/disconnect |
clientId | string | 1 | ハンドシェイク中に受信したクライアント固有のID |
応答例 :
POST /cep/realtime
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/json
[
{
"channel": "/meta/disconnect",
"clientId": "Un1q31d3nt1f13r",
}
]
応答
名称 | タイプ | 発生回数 | 説明 |
---|---|---|---|
id | string | 0..1 | リクエストメッセージで渡されるメッセージのID |
channel | string | 1 | URIチャネル名。必要な値:/meta/disconnect |
successful | boolean | 1 | 接続解除オペレーションの結果 |
clientId | string | 1 | ハンドシェイク中に受信したクライアント固有のID |
error | string | 0..1 | 接続解除失敗理由 |
応答例 :
HTTP/1.1 200 OK
Content-Type: application/json
[