アラーム

概要

アラームインターフェースは以下の3つの要素で構成されます。

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

アラーム API

アラーム API [application/vnd.com.nsn.cumulocity.alarmApi+json]

名称 タイプ 発生回数 説明
self URL 1 このリソースへのリンク
alarms AlarmCollection 1 すべてのアラームのコレクション
alarmsForStatus AlarmCollection URI template 1 特定の状態にあるすべてのアラームの読み取り専用コレクション(プレースホルダー{status}。許可される値については後述「アラーム」の要素をご覧ください)
alarmsForSource AlarmCollection URI template 1 特定のソースオブジェクトに関するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{source}、インベントリ内のオブジェクトの固有ID)
alarmsForSourceAndStatus AlarmCollection URI template 1 特定の状態にあるソースオブジェクトに関するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{source}、{status})
alarmsForTime AlarmCollection URI template 1 特定の期間におけるすべてのアラームから成る読み取り専用コレクション(プレースホルダー{dateFrom}、{dateTo})
alarmsForStatusAndTime AlarmCollection URI template 1 特定の状態および期間に該当するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{status}、{dateFrom}、{dateTo})
alarmsForSourceAndTime AlarmCollection URI template 1 特定のソースおよび期間に該当するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{source}、{dateFrom}、{dateTo})
alarmsForSourceAndStatusAndTime AlarmCollection URI template 1 特定のソース、状態および期間に該当するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{source}、{status}、{dateFrom}、{dateTo})
alarmsForSourceWithAssetsAndWithDevices AlarmCollection URI template 1 特定のソースおよびその子に該当するすべてのアラームから成る読み取り専用コレクション (プレースホルダー{source}、{withSourceAssets}、{withSourceDevices})
alarmsForSeverity AlarmCollection URI template 1 特定の重要度に該当するすべてのアラームから成る読み取り専用コレクション(プレースホルダー{severity})
alarmsForResolved AlarmCollection URI template 1 解決済みのすべてのアラームから成る読み取り専用コレクション(プレースホルダー{resolved})

GET - アラーム API リソースの取得

応答本体: application/vnd.com.nsn.cumulocity.alarmApi+json

要求されるロール: ROLE_ALARM_READ

リクエスト例:

GET /alarm
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarmApi+json;ver=…
Content-Length: …
{
    "self" : "<<AlarmAPI URL>>",
    "alarms" : { "self" :"<<AlarmCollection URL>>" },
    "alarmsForStatus" : "<<AlarmCollection URL>>?status={status}",
    "alarmsForSource" : "<<AlarmCollection URL>>?source={source}",
    "alarmsForSourceAndStatus" : "<<AlarmCollection URL>>?source={source}&status={status}",
    "alarmsForTime" : "<<AlarmCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForStatusAndTime" : "<<AlarmCollection URL>>?status={status}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceAndTime" : "<<AlarmCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceAndStatusAndTime" : "<<AlarmCollection URL>>?source={source}&status={status}&dateFrom={dateFrom}&dateTo={dateTo}",
    "alarmsForSourceWithAssetsAndWithDevices": "<<AlarmCollection URL>>?source={source}&withAssets={withAssets}&withDevices={withDevices}"
    "alarmsForResolved": "<<AlarmCollection URL>>?resolved={resolved}",
    "alarmsForSeverity": "<<AlarmCollection URL>>?severity={severity}",
}

通知

アラーム通知は特定のデバイスにおけるアラームの監視を許可します 通知を受信するための基本プロトコルは「リアルタイム通知」セクションに記載されています。URLは以下の通りです。

/cep/realtime

すべてのデバイスのアラームに関する通知を受信するには、チャネル接続に、デバイスのマネージドオブジェクトID、またはプレースホルダとして「 * 」を含む必要があります。

/alarms/<<deviceId>>

さらに、アラームオブジェクトへの応答には「realtimeAction」が含まれ、指定されたオブジェクトになったアクション(CREATE、UPDATE、またはDELETE)を識別します。削除(DELETE)の場合、データは、削除されたアラームのIDのみ包含することになります。

応答例:

HTTP/1.1 200 OK 
Content-Type: application/json
[
  {
    "channel": "/alarms/12345", 
    "successful": true, 
    "error": "", 
    "data": [{
      "realtimeAction": "UPDATE",
      "data": {
        "id": "1",
        "self": "...",
        "source": { 
          "12345"
        },
        "type": "c8y_UnavailabilityAlarm",
        "text": "I am an alarm",
        "severity": "MINOR",
        "status": "CLEARED",
        "firstOccurrence": true,
        "count": 1
      }
    }], 
    "clientId": "Un1q31d3nt1f13r" 
  }
]

要求されるロール: ROLE_ALARMS_READ

アラームコレクション

アラームコレクション [application/vnd.com.nsn.cumulocity.alarmCollection+json]

名称 タイプ 発生回数 説明
self URI 1 このリソースへのリンク
alarms Alarm 0..n アラームのリスト(下記参照)
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 アラームの前のページへのリンク(あれば)
next URI 0..1 アラームの次のページへのリンク(あれば)

GET - アラームコレクションの取得

応答本体: AlarmCollection

要求されるロール: ROLE_ALARM_READ

リクエスト例:

GET /alarm/alarms
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...
Content-Length: ...

{
  "self" : "...",
  "next" : "...",
  "prev" : "...",
  "alarms": [
    {
      "id" : "10",
      "self" : "...",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_events_TamperEvent",
      "time" : "2011-09-06T12:03:27.845Z",
      "text" : "Tamper sensor triggered",
      "status" : "ACTIVE",
      "severity" : "MAJOR",
      "source": { "id" : "12345", "self" : "..." },
      "count":1,
      "history": { ... }
    },
    {
      "id" : "11",
      "self" : "...",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_events_BatteryWarning",
      "time" : "2011-09-06T12:04:27.845Z",
      "text" : "Low battery level",
      "status" : "ACTIVE",
      "severity" : "MINOR",
      "source": { "id" : "1122", "self" : "..." },
      "count":1,
      "history": { ... }
    }
  ],
  "statistics" : {
    "totalPages" : 8,
    "pageSize" : 5,
    "currentPage : 1
  }
}

POST - 新規アラームの作成

リクエスト本体: Alarm

応答本体: Alarm

要求されるロール: ROLE_ALARM_ADMIN またはソースオブジェクトの所有権

リクエスト例:

POST /alarm/alarms
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...

{
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "com_mycorp_MyProp" : { ... }
}

応答例:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
Location: <<URL of new alarm>>

{
  "id" : "10",
  "self" : "<<URL of new alarm>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "count": 1,
  "com_mycorp_MyProp" : { ... }
  "history" : { ... }
}

POSTリクエストの場合、ソースパラメータ(“source”)はidのみ有することを要求されます。

新規アラームの「id」と「creationTime」はサーバーによって生成され、応答においてPOSTオペレーションへ返されます。

アラーム抑制:ソースデバイスが保守モードの場合、アラームは作成されず、Things Cloud のイベント処理エンジンにも報告されません。新規アラーム生成のためPOSTリクエストを行った際、デバイスが保守モードであると、“self” リンクは以下のようになります。

{
    "self" : "<<URL of new alarm>>/null",
}

アラーム重複除外:ソース(“source”)およびタイプ(“type”)が同じで、アクティブ(“active”)または認知状態(“acknowledged”)のアラームが存在する場合、新規アラームは作成されません(クリア(“cleared”)状態のアラームでは無効)。代わりに、既存のアラームは「count」プロパティの加算によって更新され、時間プロパティも更新されます。さらに、他の変化も一切無視され、アラーム履歴も更新されません。 初めて発生したアラームは「firstOccurrenceTime」に記録されます。

DELETE - アラームコレクションの削除

DELETEメソッドはアラームコレクションの削除を可能にします。適用可能なクエリパラメータは次のものになります。

名称 タイプ 説明
status String コンマで区切られたアラームの状態:たとえば、ACTIVE,CLEAREDなど
source String ソースデバイスID
withSourceAssets Boolean trueの場合、関連付けられたソースアセットのアラームも削除される。このパラメータが提示された場合sourceの定義が必要
withSourceDevices Boolean trueの場合、関連付けられたソースデバイスのアラームも削除される。このパラメータが提示された場合sourceの定義が必要
resolved Boolean trueの場合、解決された(CLEARED状態の)アラームのみ削除される。ACTIVE または ACKNOWLEDGED状態のものはfalseとなる
severity String アラーム重要度。たとえば、MINORなど
dateFrom String アラームが発生した時間と日時
dateTo String アラームが終了した時間と日時
type String アラームのタイプ

リクエスト本体: N/A

応答本体: N/A

要求されるロール: ROLE_ALARM_ADMIN

リクエスト例:

 DELETE: /alarm/alarms....
 Host: ...
 Authorization: Basic ...

応答例:

HTTP/1.1  204 NO CONTENT

注意: パラメーターを指定せずにこのエンドポイントを呼び出すことは可能ですが、すべてのアラームが削除されるため、お勧めしません。

PUT - アラームコレクションの一括アップデート

PUTメソッドでアラームコレクションの更新ができます。現在、アラームのステータスのみ変更できます。

リクエスト本体:

  { status: <new_status> }

応答体: N/A

要求されるロール: ROLE_ALARM_ADMIN

応答ステータス:

リクエスト例: アクティブ状態のアラームを全てクリアする

 PUT: /alarm/alarms?status=ACTIVE
 Host: ...
 Authorization: Basic ...
 {
    "status": "CLEARED"
 }

応答例:

 HTTP/1.1  202 Accepted

エンドポイントではクエリパラメータが使用されます。既存のすべてのアラームを誤って更新しないように、処理には少なくとも1つのクエリパラメータが必要です。

使用可能なクエリ・パラメータは次のとおりです:

この操作には多くの時間がかかるため、処理後最長0.5秒以内に要求が戻され、プラットフォームではバックグラウンド・プロセスとして更新が続行されます。

アラームは、メンテナンスモードの場合でも更新できます。

アラーム

アラーム [application/vnd.com.nsn.cumulocity.alarm+json]

名称 タイプ 発生回数 説明 PUT/POST
id String 1 アラームを一意に識別します なし
self URI 1 このリソースへのリンク なし
creationTime String 1 アラームがデータベース内で作成された時間。 なし
type String 1 このアラームイベントのタイプを識別します 例:「com_cumulocity_events_TamperEvent」 POST: 必須
PUT: なし
time String 1 アラームの時間 POST: 必須
PUT: なし
text String 1 アラームを説明するテキスト POST: 必須
PUT: なし
source ManagedObject 1 アラームの発生源となったマネージドオブジェクト。オブジェクトは「id」プロパティを含みます POST: 必須
PUT: なし
status String 0..1 アラームの状態:ACTIVE、ACKNOWLEDGEDまたはCLEARED。状態が表示されなかった場合、新規アラームの状態はACTIVEとなります。すべて大文字でなければなりません。 POST: 任意
PUT: 任意
severity String 1 アラームの重大度:CRITICAL、MAJOR、MINORまたはWARNING。すべて大文字でなければなりません。 POST: 必須
PUT: 任意
count Long 1 このアラームが送信された回数。 なし
firstOccurrenceTime String 1 このアラームが最初に発生した時間(すなわち「count」が1になった時間)。 なし
history AuditRecordCollection 1 レガシー。使用不可 なし
* Object 0..n イベントの付加的プロパティ。  

GET - アラームの取得

応答本体: Alarm

要求されるロール: ROLE_ALARM_READ

リクエスト例:

GET /alarm/alarms/<<alarmId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.alarm+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
{
  "id" : "10",
  "self" : "<<Alarm URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACTIVE",
  "severity" : "MAJOR",
  "source" : { "id" : "12345", "self" : "..." },
  "com_mycorp_MyProp" : { ... }
  "history" : { }
}

PUT - アラームの更新

アラームが変更されると新たな監査記録(“audit record”)が発生します。監査記録には更新をトリガーしたユーザー名とアプリケーションが記載されます。アラームの監査リストを取得するには次の要求を使用します: GET /audit/auditRecords?source=

注記:更新しても何も変化がない(すなわちデータベースにすでに存在するデータと同じデータがリクエスト本体に含まれる)場合、監査記録は追加されず、通知も送られません。

テキスト、ステータス、重要度、カスタムプロパティのみ変更できます。変更不可能なフィールドへの要求は無視されます。

リクエスト本体: Alarm

応答本体: Alarm

要求されるロール : ROLE_ALARM_ADMIN or owner of source object

リクエスト例:

PUT /alarm/alarms/<<alarmId>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
{
  "severity" : "minor"
}

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
Content-Length: ...
{
  "id" : "10",
  "self" : "<<Alarm URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACKNOWLEDGED",
  "severity" : "MINOR",
  "source" : { "id" : "12345", "self" : "..." },
  "history" : { }
}