デバイスインテグレーション

概要

RESTはHTTP (S) とTCPをベースにした非常にシンプルでセキュアなプロトコルです。現在、非常にシンプルなデバイスから大規模なITに至るまで、すべてのネットワーク・プログラミング環境でサポートされている事実上のインターネット標準となっています。RESTを紹介している多くの本の中の一つにRESTful Web Servicesがあります。

このセクションでは、Things Cloud のRESTインターフェースを使用してデバイスをThings Cloudにインターフェースする方法を説明します。RESTインターフェースの使用に関する一般的な情報と、RESTを使用したThings Cloud上でのアプリケーション開発に関する情報については、Microservice SDKガイドを参照してください。

この説明は、各インターフェースの詳細を説明しているリファレンスガイドと密接に関連しています。リファレンスガイドの関連する章はとくに次のとおりです。

- REST実装は、すべての一般的な概念のリファレンスです。 - デバイス管理ライブラリは、デバイス管理のデータ・モデルを指定します。 - センサー・ライブラリ は、センサーとコントロールのデータ・モデルを指定します。

Java ME/SE、JavaScript、またはC/C++を使用して開発する場合は、Things Cloudの機能にさらに簡単にアクセスできるよう、このガイドの関連する章も確認してください。また、サポートされている開発ボードを使用する場合は、デバイスガイド内の該当する説明も参照してください。

デバイスインテグレーション

デバイスをThings Cloudに統合するための基本的なライフサイクルは、コンセプトガイドのインターフェースデバイス で説明されています。このセクションでは、このライフサイクルがRESTレベルでどのように実装されるかを示します。ライフサイクルは、スタートアップフェーズとサイクルフェーズの2つのフェーズで構成されます。

スタートップフェーズでは、デバイスをThings Cloudに接続し、インベントリ内のデバイスデータを更新します。また、操作に必要なクリンナップタスクも実行します。 このフェーズは次のステップで構成されています。

  • ステップ0:デバイス資格情報がまだ要求されていない場合は要求します。
  • ステップ1:デバイスがすでに登録されているかどうかを確認します。
  • ステップ2:登録されていない場合は、インベントリにデバイスを作成し、
  • ステップ3:デバイスを登録します。
  • ステップ4:登録されている場合、インベントリのデバイスを更新します。
  • ステップ5:子デバイスを検出し、インベントリでそれらのデバイスを作成または更新します。
  • ステップ6:再起動が必要なオペレーションを終了し、新しいオペレーションをサブスクライブします。

Startup phase

次に、サイクルフェーズへと続きます。インベントリを継続的に更新し、メジャーメント、アラーム、イベントを書き込み、必要に応じて操作を実行します。これは、デバイスの電源が切れるまで実行されるデバイスの「メインループ」となります。ループは次のステップで構成されています。

サイクルフェーズ

データの参照モデルについては、デバイス管理ライブラリおよびリファレンスガイド内のセンサー・ライブラリを参照してください。

スタートアップフェーズ

ステップ0:デバイス認証情報を要求する

Things Cloudへのすべてのリクエストは認証される必要があるので、デバイスからのリクエストも認証される必要があります。個々の認証情報をデバイスに割り当てる場合は、デバイス認証情報APIを使用して新しい認証情報を自動的に生成できます。これを行うには、最初の起動時にAPIを介してデバイスの認証情報を要求し、それ以降の要求に備えてデバイス上のローカルに保存します。

このプロセスは次のように動作します。

  • Things Cloudは、各デバイスが何らかの固有のIDを持つことを前提としています。適切なデバイス識別子は、ネットワークアダプタのMACアドレス、モバイルデバイスのIMEI、またはハードウェアシリアル番号となります。
  • 新しいデバイスを使用する場合は、この固有IDをThings Cloudの「デバイス登録」に入力し、デバイスを起動します。
  • デバイスはThings Cloudに接続し、固有IDを繰り返し送信します。そのため、Things Cloudでは静的認証情報を提供しており、supportにて問い合わせることができます。
  • 「デバイス登録」よりデバイスからの接続を受け入れることができ、その場合Things Cloudは生成された認証情報をデバイスに送信します。
  • デバイスは、以降のすべての要求にこれらの認証情報を使用します。

デバイス側の視点から見ると、これは単一のRESTリクエストです:

POST /devicecontrol/deviceCredentials
Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Authorization: Basic ...
{
  "id" : "0000000017b769d5"
}

デバイスはこの要求を繰り返し発行します。ユーザーがまだデバイスを登録して受け入れていない間、要求は「404 Not Found」を返します。デバイスが受け入れられると、次の応答が返されます:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.deviceCredentials+json;ver=...
Content-Length: ...
{
  "id" : "0000000017b769d5",
  "self" : "<<URL of new request>>",
  "tenantId" : "test",
  "username" : "device_0000000017b769d5",
  "password" : "3rasfst4swfa"
}

これで、デバイスはテナントID、ユーザー名、パスワードを使用してThings Cloudに接続できます。

ステップ1:デバイスが登録済みかどうかを確認する

デバイスの固有IDは、デバイスをインベントリに登録するためにも使用されます。登録はID APIを用いて行います。ID APIでは、各管理対象オブジェクトをタイプで識別される複数の識別子に関連付けることができます。たとえば、ハードウェアシリアル番号の場合は「c8y_シリアル」、MACアドレスの場合は「c8y_MAC」、IMEIの場合は「c8y_IMEI」となります。

デバイスがすでに登録されているかどうかを確認するには、デバイス識別子とそのタイプを使用して、ID APIのGET要求を使用します。次の例では、ハードウェアシリアル番号「0000000017b769d5」のRaspberry Piをチェックしています。

GET /identity/externalIds/c8y_Serial/raspi-0000000017b769d5 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.externalId+json; charset=UTF-8; ver=0.9
...
{
    "externalId": "raspi-0000000017b769d5",
    "managedObject": {
        "id": "2480300",
        "self": "https://.../managedObjects/2480300"
    },
    "self": "https://.../identity/externalIds/c8y_Serial/raspi-0000000017b769d5",
    "type": "c8y_Serial"
}

MACアドレスはグローバルで固有であることが保証されていますが、ハードウェアのシリアル番号は異なるハードウェア間で重複する可能性があることに注意してください。したがって、上記の例では、シリアル番号の前に「raspiー」を付けています。

この場合、デバイスはすでに登録されており、ステータスコード200が返されます。応答では、インベントリ内のデバイスへのURLが「managedObject。自己」に返されます。このURLは、後でデバイスを操作するために使用できます。

デバイスがまだ登録されていない場合は、404ステータスコードとエラーメッセージが返されます。

GET /identity/externalIds/c8y_Serial/raspi-0000000017b769d6 HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: application/vnd.com.nsn.cumulocity.error+json;charset=UTF-8;ver=0.9
...
{
    "error": "identity/Not Found",
    "info": "https://www.cumulocity.com/guides/reference-guide/#error_reporting",
    "message": "External id not found; external id = ID [type=c8y_Serial, value=raspi-0000000017b769d6]"
}

ステップ2:インベントリにデバイスを作成する

上記のステップ1で、デバイスを表すマネージドオブジェクトが存在しないことが示された場合、マネージドオブジェクトをThings Cloudに作成します。マネージドオブジェクトは、デバイスのインスタンスとメタデータの両方を記述します。インスタンスデータには、ハードウェアおよびソフトウェア情報、シリアル番号、デバイス構成データが含まれます。メタデータは、サポートされている操作など、デバイスの機能を記述します。

マネージドオブジェクトを作成するには、インベントリ APIのマネージドオブジェクトコレクションに対してPOST要求を出します。次の例では、Linuxエージェントを使用してRaspberry Piを作成しています:

POST /inventory/managedObjects HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
Accept: application/vnd.com.nsn.cumulocity.managedObject+json
...
{
    "name": "RaspPi BCM2708 0000000017b769d5",
    "type": "c8y_Linux",
    "c8y_IsDevice": {},
    "com_cumulocity_model_Agent": {},
    "c8y_SupportedOperations": [ "c8y_Restart", "c8y_Configuration", "c8y_Software", "c8y_Firmware" ],
    "c8y_Hardware": {
        "revision": "000e",
        "model": "RaspPi BCM2708",
        "serialNumber": "0000000017b769d5"
    },
    "c8y_Configuration": {
        "config": "#Fri Aug 30 09:13:56 BST 2013\nc8y.log.eventLevel=INFO\n..."
    },
    "c8y_Mobile": {
         "imei": "861145013087177",
        "cellId": "4904-A496",
        "iccid": "89490200000876620613"
    },
    "c8y_Firmware": {
        "name": "raspberrypi-bootloader",
        "version": "1.20130207-1"
    },
    "c8y_Software": {
        "pi-driver": "pi-driver-3.4.5.jar",
        "pi4j-gpio-extension": "pi4j-gpio-extension-0.0.5.jar",
        ...
    }
}

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;charset=UTF-8;ver=0.9
...
{
    "id": "2480300",
    "lastUpdated": "2013-08-30T10:12:24.378+02:00",
    "name": "RaspPi BCM2708 0000000017b769d5",
    "owner": "admin",
    "self": "https://.../inventory/managedObjects/2480300",
    "type": "c8y_Linux",
    "c8y_IsDevice": {},
    ...
    "assetParents": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2480300/assetParents"
    },
    "childAssets": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2480300/childAssets"
    },
    "childDevices": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2480300/childDevices"
    },
    "deviceParents": {
        "references": [],
        "self": "https://.../inventory/managedObjects/2480300/deviceParents"
    }
}

上記の例では、デバイスの多数のメタデータ項目が含まれています。

  • 「c8y_IsDevice」は、Things Cloudのデバイス管理を使用して管理できるデバイスをマークします。
  • 「com_cumulocity_model_Agent」はThings Cloudエージェントを実行しているデバイスをマークします。このようなデバイスは、ルーティングのために自身とその子を対象とするすべての操作を受け取ります。
  • 「c8y_SupportedOperations」は、このデバイスを再起動して構成できることを示しています。また、ソフトウェアやファームウェアのアップデートも実行できます。

詳細についてはリファレンスガイド内のデバイス管理ライブラリを参照してください。

デバイスが正常に作成された場合は、ステータスコード201が返されます。この例のように、元の要求に「Accept」ヘッダーが含まれている場合は、今後の要求でそのオブジェクトを参照するためのIDとURLを含む、作成されたオブジェクト全体が返されます。返されるオブジェクトには、デバイスに子を追加できる子デバイスと子アセットのコレクションへの参照も含まれます(下記参照)。

ステップ3:デバイスを登録する

新しいデバイスを作成後、ステップ1で説明したように、そのデバイスを組み込み識別子と関連付けることができます。これにより、次回の電源投入後にデバイスがThings Cloud内にあることを確認できます。

上記の例に続き、次では新しく作成したデバイス「2480300」をハードウェアシリアル番号に関連付けます:

POST /identity/globalIds/2480300/externalIds HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.externalId+json
Accept: application/vnd.com.nsn.cumulocity.externalId+json
...
{
    "type" : "c8y_Serial",
    "externalId" : "raspi-0000000017b769d5"
}

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.externalId+json;charset=UTF-8;ver=0.9
...
{
    "externalId": "raspi-0000000017b769d5",
    "managedObject": {
        "id": "2480300",
        "self": "https://.../inventory/managedObjects/2480300"
    },
    "self": "https://.../identity/externalIds/c8y_Serial/raspi-0000000017b769d5",
    "type": "c8y_Serial"
}

ステップ4:インベントリ内のデバイスを更新する

上記のステップ1でデバイスが以前に登録されていると返された場合は、デバイスのインベントリ表現が実際のデバイスの現在の状態に対して最新のものであることを確認する必要があります。このためのPUT要求がインベントリ内のデバイスのURLへ送信されます。変更可能なフラグメントのみが転送されることに注意してください。(フラグメントの詳細については、クームシティのドメインモデル を参照してください。)

たとえば、デバイスのハードウェア情報は通常変更されませんが、ソフトウェアのインストールが変更されている可能性があります。したがって、デバイスの再起動後にインベントリ内のソフトウェア情報を最新の状態にすることは理にかなっています:

PUT /inventory/managedObjects/2480300 HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json
...
{
    "c8y_Software": {
        "pi-driver": "pi-driver-3.4.6.jar",
        "pi4j-gpio-extension": "pi4j-gpio-extension-0.0.5.jar"
    }
}

HTTP/1.1 200 OK

エージェントからデバイス名を更新しないでください。エージェントはデバイスのデフォルト名を作成してインベントリで識別できるようにしますが、ユーザーはこの名前を編集または、アセット管理の情報で更新するべきです。

ステップ5:子デバイスを検出し、インベントリでそれらを作成または更新する

センサネットワークの複雑さに応じて、デバイスは、関連する子デバイスを有することができます。家庭のさまざまな部屋にさまざまなセンサーやコントロールを設置するホームオートメーションゲートウェイなどがその良い例です。子デバイスの基本登録方法は、子デバイスが通常エージェントインスタンスを実行しないというところまでは、メインデバイスの登録と同じです(したがって、「com_cumulocity_model_Agent」フラグメントは除外されます)。デバイスを子にリンクするには、オブジェクトの作成時に返された子デバイスのURLにPOSTリクエストを送信します(上記参照)。

たとえば、「https://.../inventory/managedObjects/2543801」というURLを持つ子デバイスがすでに作成されているとします。このデバイスを親デバイスとリンクするには、次のコマンドを発行します。

POST /inventory/managedObjects/2480300/childDevices HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.managedObjectReference+json
{ "managedObject" : { "self" : "https://.../inventory/managedObjects/2543801" } }

HTTP/1.1 201 Created

最後に、URLにDELETEリクエストを発行することによって、デバイスと参照を削除することができます。たとえば、作成したばかりの親デバイスから子デバイスへの参照を削除するには、次のコマンドを発行します:

DELETE /inventory/managedObjects/2480300/childDevices/2543801 HTTP/1.1

HTTP/1.1 204 No Content

この場合、インベントリ内のデバイス自体は削除されず、参照のみが削除されます。デバイスを削除するには、次のコマンドを発行します:

DELETE /inventory/managedObjects/2543801 HTTP/1.1

HTTP/1.1 204 No Content

この要求は、登録情報、メジャーメント、アラーム、イベント、および操作を含む、デバイスに関連するすべてのデータも削除します。通常、デバイスを自動的に削除することはお勧めできません。たとえば、デバイスの接続が一時的に失われただけの場合、通常そのデバイスに関連するすべての履歴情報を失いたくないでしょう。

操作方法

Things Cloudの各操作は、実行フローを通じて循環されます。Things Cloudアプリケーションを介して操作が作成されると、保留状態になります(つまり、実行のためにキューに入れられてはいても、まだ実行されていない状態です)。エージェントが操作を選択して実行を開始すると、その操作にはThings Cloudで「実行中」というマークが付けられます。その後、エージェントは、デバイスまたはその子に対して操作を実行します(たとえば、デバイスを再起動したり、リレーを設定したりします)。その後、デバイスまたはその子の新しい状態を反映してインベントリを更新するでしょう (例:インベントリ内のリレーの現在の状態を更新します)。次に、エージェントはThings Cloud内の操作を「成功」または「失敗」のいずれかとしてマークし、場合によってはエラーを表示します。

Operation status diagram

この実行フローの利点は、オフラインで一時的に範囲外のデバイスをサポートすることです。また、再起動が必要な操作 (ファームウェアのアップグレードなど) をデバイスでサポートすることもできます。再起動後、デバイスは以前に実行した内容を知る必要があるため、すべてのEXECUTING操作を照会して正常に実行されたかどうかを確認する必要があります。また、キューに入れられる可能性のある新しい操作をリッスンする必要もあります。

ステップ6:操作を終了して購読する

まだ実行中状態にある操作をクリンナップするには、エージェントIDおよび状況別に操作を照会します。 この例では、要求は次のようになります:

GET /devicecontrol/operations?agentId=2480300&status=EXECUTING HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.operationCollection+json;; charset=UTF-8; ver=0.9
...
{
    "next": "https://.../devicecontrol/operations?agentId=2480300&status=EXECUTING",
    "operations": [
        {
            "creationTime": "2013-08-29T19:49:15.239+02:00",
            "deviceId": "2480300",
            "id": "2593101",
            "self": "https://.../devicecontrol/operations/2480300",
            "status": "EXECUTING",
            "c8y_Restart": {
            }
        }
    ],
    "statistics": {
        "currentPage": 1,
        "pageSize": 2000
    },
    "self": "https://.../devicecontrol/operations?agentId=2480300&status=EXECUTING"
}

再起動はうまくいったようです--もとに戻りました。操作を「成功」に設定します。

PUT /devicecontrol/operations/2480300 HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.operation+json
{
    "status": "SUCCESSFUL"
}

HTTP/1.1 200 OK

次に、Things Cloudで作成された新しい操作をリッスンします。Things Cloudのリアルタイムデータをリッスンするためのメカニズムは、リファレンスガイドのリアルタイムの通知に記述されており、標準Bayeuxプロトコルに基づいています。まず、ハンドシェイクが必要です。ハンドシェイクはThings Cloudに、エージェントが通知に対応しているプロトコルを伝え、クライアントIDをエージェントに割り当てます。

POST /devicecontrol/notifications HTTP/1.1
Content-Type: application/json
...
[ {
    "id": "1",
    "supportedConnectionTypes": ["long-polling"],
    "channel": "/meta/handshake",
    "version": "1.0"
} ]

HTTP/1.1 200 OK
...
[ {
    "id": "1",
    "supportedConnectionTypes": ["websocket","long-polling"],
    "channel": "/meta/handshake",
    "version": "1.0",
    "clientId": "139jhm07u1dlry92fdl63rmq2c",
    "minimumVersion": "1.0",
    "successful": true
}]

その後、それぞれのデバイスのエージェントは操作を実行する為の通知にサブスクライブする必要があります。これは、サブスクリプションチャネルとしてデバイスのIDを持つPOST要求を使用して行われます。この例では、Raspberry Piがエージェントを実行し、IDは2480300です。

POST /devicecontrol/notifications HTTP/1.1
Content-Type: application/json
...
[ {
    "id": "2",
    "channel": "/meta/subscribe",
    "subscription": "/2480300",
    "clientId":"139jhm07u1dlry92fdl63rmq2c"
}]

HTTP/1.1 200 OK
...
[ {
    "id":"2",
    "channel": "/meta/subscribe",
    "subscription": "/2480300",
    "successful": true,
} ]

最後に、デバイスは接続し、操作が送信されるまで待機します。

POST /devicecontrol/notifications HTTP/1.1
Content-Type: application/json
...
[ {
    "id": "3",
    "connectionType": "long-polling",
    "channel": "/meta/connect",
    "clientId": "139jhm07u1dlry92fdl63rmq2c"
} ]

この要求は、操作が発行されるまで保留にします。つまり、HTTPサーバーはすぐには応答しませんが、デバイスの操作が行われるまで待機します(ロングポーリング)。

新しい操作をサブスクライブする前に、保留中の操作が存在する可能性に注意してください。これらをすべて照会する必要があります。そして、クエリとサブスクリプションの間の操作が失われないよう、サブスクリプションの後に実行されます。この技術的な処理は、以前に説明した「実行」操作と同じですが、代わりに「保留」を使用します。

GET /devicecontrol/operations?agentId=2480300&status=PENDING HTTP/1.1

サイクルフェーズ

ステップ7:操作を実行する

ここで、エージェントに対する操作がキューに入れられたとします。これにより、上記で発行した長いポーリング要求が操作とともに返されます。次は、1回の設定操作での応答例です:

HTTP/1.1 200 OK
...
[
    {
        "id": "139",
        "data": {
            "creationTime":"2013-09-04T10:53:35.128+02:00",
            "deviceId": "2480300",
            "id": "2546600",
            "self": "https://.../devicecontrol/operations/2546600",
            "status": "PENDING",
            "description": "Configuration update",
            "c8y_Configuration": { "config": "#Wed Sep 04 10:54:06 CEST 2013\n..." }
        },
        "channel": "/2480300"
    }, {
        "id": "3",
        "successful": true,
        "channel": "/meta/connect"
    }
]

エージェントは操作を選択すると、PUT要求を使用して操作をThings Cloudの「実行中」状態に設定します(前述の「失敗」の例を参照)。それはデバイス上で操作を実行し、Things Cloudインベントリの可能な更新を実行します。最後に、結果に応じて操作を「成功」または「失敗」に設定します。その後、前述のように「/devicecontrol/notifications」に再接続し、次の操作を待ちます。

キューに入れられた操作が失われないように、デバイスは10秒以内にサーバーに再接続する必要があります。これは、Things Cloudがリアルタイム・データをバッファーする時間です。間隔は、ハンドシェイク時に指定できます。

ステップ8:インベントリの更新

デバイスのインベントリ内容は継続的な変更の対象となりますが、通常、デバイスの現在の状態を表します。例として、GPSチップを搭載したデバイスを考えてみましょう。このデバイスは、インベントリ内の現在の場所を最新の状態に保ちます。同時に、位置の追跡を維持するために、位置の更新とイベントを報告します。技術的にこのような更新は、ステップ4と同じ要求で報告されます。

ステップ9:メジャーメントを送信する

Things Cloudに新しいメジャーメントを作成するには、メジャーメントを含むPOST要求を発行します。次の例は、信号強度のメジャーメントを作成する方法を示しています:

POST /measurement/measurements HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json
...
{
    "source": { "id": "2480300" },
    "time": "2013-07-02T16:32:30.152+02:00",
    "type": "huawei_E3131SignalStrength",
    "c8y_SignalStrength": {
        "rssi": { "value": -53, "unit": "dBm" },
        "ber": { "value": 0.14, "unit": "%" }
    }
}

HTTP/1.1 201 Created

ステップ10:イベントを送信する

同様に、イベントにはPOST要求を使用します。次の例は、GPSセンサからの位置更新を示しています。

POST /event/events HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.event+json
...
{
    "source": { "id": "1197500" },
    "text": "Location updated",
    "time": "2013-07-19T09:07:22.598+02:00",
    "type": "queclink_GV200LocationUpdate",
    "c8y_Position": {
        "alt": 73.9,
        "lng": 6.151782,
        "lat": 51.211971
    }
}

HTTP/1.1 201 Created

Things Cloudのすべてのデータタイプは、追加フラグメントという形で任意の拡張を含むことができることに注意してください。この場合、イベントには位置が含まれますが、自己定義フラグメントを追加することもできます。

ステップ11:アラームを送信する

アラームは、解決するために人の介入を必要とする可能性が最も高いイベントを表します。たとえば、デバイスのバッテリの電力が不足した場合、誰かがデバイスのバッテリを交換する必要があります。アラームの作成は、技術的にはイベントの作成と非常によく似ています。

POST /alarm/alarms HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json
Accept: application/vnd.com.nsn.cumulocity.alarm+json
...
{
    "source": { "id": "10400" },
    "text": "Tracker lost power",
    "time": "2013-08-19T21:31:22.740+02:00",
    "type": "c8y_PowerAlarm",
    "status": "ACTIVE",
    "severity": "MAJOR",
}

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json
...
{
    "id": "214600",
    "self": "https://.../alarm/alarms/214600",
    ...
}

ただし、同じようなアラームがシステム内ですでに有効になっている場合は、デバイスのアラームを作成しない方がよいでしょう。多数のアラームを作成すると、ユーザーインタフェースがいっぱいになり、すべてのアラームを手動でクリアする必要が生じる場合があります。上の例は、Raspberry Piのアクティブアラームを見つけるためのものです。

GET /alarm/alarms?source=2480300&status=ACTIVE HTTP/1.1

イベントとは異なり、アラームは更新できます。問題が解決した場合 (例:バッテリが交換され、電源が復旧した場合)、対応するアラームが自動的にクリアされ、手動での作業が不要になります。これは、アラームのURLへのPUT要求によって実行できます。上記のアラーム作成の例では、「承諾」ヘッダーを使用して、応答内の新しいアラームのURLを取得しました。このURLを使用してアラームをクリアできます。

PUT /alarm/alarms/214600 HTTP/1.1
Content-Type: application/vnd.com.nsn.cumulocity.alarm+json
...
{
    "status": "CLEARED"
}

HTTP/1.1 200 OK

イベントの送信、またはアラームの発生のどちらを選べば良いかわからない場合は、単にイベントを発生させ、ユーザーがイベントをアラームに変換するかどうかをイベント言語で決定できるようにすると良いでしょう。