アラーム

概要

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

  • 「アラームAPI」リソースは、すべてのアラームまたは指定されたデバイスおよび/または指定された状態のアラーム情報取得できるよう、アラームコレクションにURIおよびURIテンプレートを返します。
  • 「アラームコレクション」リソースはアラーム情報の取得、新規アラームの作成を可能にします。
  • 「アラーム」リソースは、アラームワークフローを通じてクエリ、修正および進行が可能な個々のアラームを表わします。

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

アラームAPI

AlarmAPI [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 URItemplate 1 特定のソースおよびその子に該当するすべてのアラームから成る読み取り専用コレクション (プレイスホルダー?{source}、{withAssets}、{withDevices}).
alarmsForSeverity AlarmCollection URI template 1 特定の重要度に該当するすべてのアラームから成る読み取り専用コレクション(プレイスホルダー?{severity}).
alarmsForResolved AlarmCollection URI template 1 解決済みのすべてのアラームから成る読み取り専用コレクション(プレイスホルダー{resolved}).

AlarmAPIリソースの取得

応答本体: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}",
    "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)。削除の場合、データは、削除されるアラームの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

アラームコレクション

AlarmCollection [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 - 新規アラームの作成

リクエスト本体:アラーム

応答本体:アラーム

要求されるロール: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
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オペレーションへ返されます。

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

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

アラーム重複除外:ソース("source")および種別("type")が同じで、有効状態("active")または認知状態("acknowledged")のアラーム(解除されるための動作を行わない)が存在する場合、新規アラームは作成されず、既存のアラームは「count」プロパティの加算によって更新され、時間プロパティも更新されます。この場合、他の変化は一切無視され、アラーム履歴は更新されません。最初のアラーム発生は「firstOccurrenceTime」に記録されます。

DELETE - アラームコレクションをDELETEする

DELETEメソッドはアラームコレクションの削除を可能にします。適用可能なクエリパラメータはGETメソッドの場合と同じです。

リクエスト本体: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

応答ステータス:

  • 200 - if the process has completed, all alarms have been updated
  • 202 - if process continues in background

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

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

応答例:

 HTTP/1.1  202 Accepted

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

許容されるクエリ・パラメータは次のとおりです:

  • status
  • source
  • resolved
  • severity
  • dateFrom
  • dateTo

この操作には多くの時間がかかるため、処理後最大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" : { }
}

アラームを更新する

アラームが変更されると新たな監査記録("audit record")が発生し、これは「履歴」コレクションに追加されます。該当する場合、更新をトリガーしたユーザー名とアプリケーションが監査記録に記載されます。アラームの監査リストを取得するには次の要求を使用します: GET /audit/auditRecords?source=

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

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

リクエスト本体:アラーム

応答本体:アラーム?

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

リクエスト例:

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" : { }
}