デバイス制御

概要

デバイス制御インターフェースは以下の3つの要素で構成されます。

注記:
デバイスのオペレーションの作成/読み出し/更新を行うため、デバイスはいずれかのエージェントの「childDevices」階層に属していなければなりません。 エージェントをインベントリ内で作成する場合、フラグメント「com_cumulocity_model_Agent」を有するマネージドオブジェクトを作成する必要があります。

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

デバイス制御API

デバイス制御API [application/vnd.com.nsn.cumulocity.devicecontrolApi+json]

名称 タイプ 発生回数 説明
self URL 1 このリソースへのリンク
operations OperationCollection 1 すべてのオペレーションのコレクション
operationsByStatus OperationCollection URI template 1 特定の状態にあるすべてのオペレーションの読み取り専用コレクション(プレースホルダー {status}、許可される値については後述の「オペレーション」の要素をご覧ください)
operationsByAgentId OperationCollection URI template 1 特定のエージェントを対象とするすべてのオペレーションの読み取り専用コレクション(プレースホルダー {agentId}、エージェントの固有IDを使用)
operationsByAgentIdAndStatus OperationCollection URI template 1 特定のエージェントを対象とするすべてのオペレーションの読み取り専用コレクション(プレースホルダー {agentId} と{status})
operationsByDeviceId OperationCollection URI template 1 特定のデバイス上で実行されるすべてのオペレーションの読み取り専用コレクション(プレースホルダー{deviceId}、デバイスの固有IDを使用)
operationsByDeviceIdAndStatus OperationCollection URI template 1 特定の状態にあり、特定のデバイス上で実行されるべきすべてのオペレーションの読み取り専用コレクション(プレースホルダー{deviceId} と {status})

GET - デバイス制御APIリソースの取得

応答本体: devicecontrolApi

要求されるロール: ROLE_DEVICE_CONTROL_READ

リクエスト例:

GET /devicecontrol
Host: ...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.devicecontrolApi+json;ver=...
Content-Length: ...
{
  "self" : "<<DeviceControl API URL>>",
   "operations" : { "self" :"<<OperationsCollection URL>>" },
   "operationsByStatus" : "<<OperationsCollection URL>>?status={status}",
   "operationsByAgentId" : "<<OperationsCollection URL>>?agentId={agentId}",
   "operationsByAgentIdAndStatus" : "<<OperationsCollection URL>>?agentId={agentId}&status={status}",
   "operationsByDeviceId" : "<<OperationsCollection URL>>?deviceId={deviceId}"
   "operationsByDeviceIdAndStatus" : "<<OperationsCollection URL>>?deviceId={deviceId}&status={status}"
}

オペレーションコレクション

オペレーションコレクション [application/vnd.com.nsn.cumulocity.operationCollection+json]

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

オペレーションコレクションに関する注記

POST - オペレーションの作成

リクエスト本体: Operation

応答本体: Operation

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

リクエスト例:

POST /devicecontrol/operations/
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...
Authorization: Basic ...
{
  "deviceId" : "1234",
  "com_cumulocity_model_WebCamDevice": {
    "name": "take picture",
    "parameters": {
      "duration": "5s",
      "quality": "HD"
    }
  }
}

応答例:

HTTP/1.1 201 Created
Location: <<URL of new operation>>
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
Content-Length: ...
{
  "id" : "123",
  "self" : "<<URL of new operation>>",
  "deviceId" : "1234",
  "status" : "PENDING",
  "creationTime" : "2011-09-06T12:03:27.927+02:00",
  "com_cumulocity_model_WebCamDevice" : {
    "name" : "take picture",
    "parameters" : {
      "duration" : "5s",
      "quality" : "HD"
    }
  }
}

GET - オペレーションコレクションの取得

応答本体: OperationCollection

要求されるロール: ROLE_DEVICE_CONTROL_READ

リクエスト例: すべてのオペレーションの取得

GET /devicecontrol/operations
Accept: application/vnd.com.nsn.cumulocity.operationCollection+json;ver=...
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.operationCollection+json;ver=...
Content-Length: ...
{
  "self" : "<<This OperationCollection URL>>",
  "operations" : [
    {
      "id" : "123",
      "self" : "<<This Operation URL>>",
      "deviceId" : "1234",
  "deviceName" : "WebCamDevice",
      "status" : "PENDING",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "com_cumulocity_model_WebCamDevice" : {
        "name" : "take picture",
        "parameters" : {
          "duration" : "5s",
          "quality" : "HD"
        }
      }
    },
    {
      "id" : "124",
      "self" : "<<This Operation URL>>",
      "deviceId" : "1234",
      "deviceName" : "DiscreteStateDevice",
      "status" : "PENDING",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "com_cumulocity_model_DiscreteStateDevice" : {
            "state" : "off"
      }
    }
  ],
  "statistics" : {
    "pageSize" : 5,
    "currentPage : 1
  }
}

DELETE - オペレーションコレクションの削除

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

リクエスト本体: N/A

応答本体: N/A

要求されるロール: ROLE_DEVICE_CONTROL_ADMIN

リクエスト例:

 DELETE: /devicecontrol/operations ....
 Host: ...
 Authorization: Basic ...

応答例:

HTTP/1.1  204 NO CONTENT

オペレーション

オペレーション [application/vnd.com.nsn.cumulocity.operation+json]

名称 タイプ 発生回数 説明 PUT/POST
id String 1 オペレーションを固有に識別します なし
self URI 1 このリソースへのリンク なし
creationTime String 1 オペレーションがデータベース内で作成された時間 なし
deviceID String 1 このオペレーションが実施されるべき対象デバイスを識別します POST: 必須 PUT: なし
deviceExternalIDs ExternalIDCollection 0..n 対象デバイスの外部ID。識別情報インターフェース参照 なし
bulkOperationId String 1 bulkOperationIdに対するリファレンス(このオペレーションが一括オペレーションから予定されていた場合) なし
status String 1 オペレーションの状態。SUCCESSFUL、FAILED、EXECUTING、PENDINGのいずれかになります POST: なし PUT: 必須
failureReason String 0..1 失敗の理由 なし
* Object 1..n デバイス上で実施予定のオペレーションを表す付加的プロパティ POST: 任意 PUT: 任意

注記: PUT のステータスが"failed"の場合のみ failureReason がオプションとなります。

「deviceExternalIDs」コレクションに組み込まれる「ExternalID」には「type」および「externalId」のプロパティが含まれます。

PUT - オペレーションの更新

リクエスト本体: Operation

応答本体: n/a.

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

リクエスト例:

PUT /devicecontrol/operations/<<operationId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
{
  "status" : "SUCCESSFUL"
}

GET - オペレーションの取得

応答本体: Operation

要求されるロール: ROLE_DEVICE_CONTROL_READ

リクエスト例:

GET /devicecontrol/operations/<<operationId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.operation+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.operation+json;ver=...
Content-Length: ...
{
  "id" : "123",
  "self" : "<<This Operation URL>>",
  "deviceId" : "1243",
  "status" : "PENDING",
  "creationTime" : "2011-09-06T12:03:27.927+02:00",
  "com_cumulocity_model_WebCamDevice" : {
    "name" : "take picture",
    "parameters" : {
      "duration" : "5s",
      "quality" : "HD"
    }
  }
}

SMSを介したデバイス制御

SMSを介してオペレーションを送信するには、デバイス管理オブジェクトにフラグメントが含まれている必要があります。

    "c8y_CommunicationMode": {
        "mode": "SMS"
    }

または、オペレーションに次のプロパティが含まれている必要があります。

    "deliveryType": "SMS"

通知

デバイス制御APIに対し、リアルタイム通知を受ける方法は2つあります。 通知を受ける基本的なプロトコルは、 “リアルタイム通知” に記載されています。

エージェントでのオペレーション受信

エージェントでは、リアルタイム通知でほぼ即時に自分宛てのオペレーションを受け取ることができます。制御関連の通知については、次のURLを使用してください。

/devicecontrol/notifications

チャネル接続におけるサブスクリプションには、オペレーションを受け取るエージェントのマネージドオブジェクトIDを含める必要があります。

/<<agentId>>

例えば、ID “5” をもつエージェントに対する新規オペレーションに対する通知を受けるには、チャネル接続におけるサブスクリプションとして、次の文字列を設定します。

/5

要求されるロール: ROLE_DEVICE_CONTROL_READ

デバイスでのオペレーション受信

このエンドポイントは新しく生成されたオペレーションだけではなく、デバイスに対する、削除を含むすべての更新を受け取ります。URLは次の通りです。

/cep/realtime

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

/operations/<<deviceId>>

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

応答例:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/operations/12345",
    "successful": true,
    "error": "",
    "data": [{
      "realtimeAction": "CREATE",
      "data": {
        "id": "1",
        "deviceId": "12345",
        "self": "...",
        "creationTime": "2011-09-06T12:03:27.927+02:00",
        "status": "PENDING",
        "time": "2011-09-06T12:03:27.845+02:00",
        "description": "Deactivate motion tracking",
        "c8y_MotionTracking": { ... }
      }
    }],
    "clientId": "Un1q31d3nt1f13r"
  }
]

要求されるロール: ROLE_DEVICE_CONTROL_READ

一括オペレーションコレクション

一括オペレーションコレクション [application/vnd.com.nsn.cumulocity.bulkOperationCollection+json]

名称 タイプ 発生回数 説明
self URL 1 このリソースへのリンク
bulkOperations Operations 0..n 一括オペレーションのリスト(下記参照)
statistics PagingStatistics 1 ページング統計に関する情報
prev URI 0..1 一括オペレーションの前のページへのリンク(あれば)
next URI 0..1 一括オペレーションの次のページへのリンク(あれば)

POST - 一括オペレーションの作成

リクエスト本体: Bulk Operation

応答本体: Bulk Operation

要求されるロール: ROLE_BULK_OPERATION_ADMIN

リクエスト例:

POST /devicecontrol/bulkoperations
Content-Type: application/vnd.com.nsn.cumulocity.bulkOperation+json
Accept: application/vnd.com.nsn.cumulocity.bulkOperation+json
Authorization: Basic ...
{
 "operationPrototype":{
   "description": "Restart device",
   "c8y_Restart": {}
 },
 "creationRamp":45,
 "groupId":"10205",
 "startDate":"2015-05-01T22:21:22"
}

応答例:

HTTP/1.1 201 Created
Location: <<URL of new operation>>
Content-Type: application/vnd.com.nsn.cumulocity.bulkOperation+json

{
 "id":2,
 "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/2",
 "operationPrototype":{
   "description": "Restart device",
   "c8y_Restart": {}
 },
 "creationRamp":45,
 "groupId":"10205",
 "startDate":"2015-05-01T22:21:22"
 "progress":
   {
   "pending":0, "failed":0, "executing":0, "successful":0, "all":1
   },
 "status":"ACTIVE"
}

GET - 一括オペレーションコレクションの取得

リクエスト本体: N/A

応答本体: BulkOperationCollection

要求されるロール: ROLE_BULK_OPERATION_READ

リクエスト例: 全てのオペレーションコレクションの取得

GET /devicecontrol/bulkoperations
Accept: application/vnd.com.nsn.cumulocity.bulkOperationCollection+json
Authorization: Basic ...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.bulkOperationCollection+json
Content-Length: ...
{
  "self" : "<<This BulkOperationCollection URL>>",
  "bulkOperations" : [
    {
     "id":2,
     "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/2",
     "operationPrototype":{
       "description": "Restart device",
       "c8y_Restart": {}
     },
     "creationRamp":45,
     "groupId":"10205",
     "startDate":"2015-05-01T22:21:22"
     "progress":
       {
        "pending":0, "failed":0, "executing":0, "successful":0, "all":1
       },
     "status":"ACTIVE",
    },
    {
     "id":3,
     "self":"https://dev.cumulocity.com/devicecontrol/bulkoperations/3",
     "operationPrototype":{
       "description": "Send Command",
       "c8y_Command": {
         "text": "Do something"
       }
     },
     "creationRamp":15,
     "groupId":"10201",
     "startDate":"2015-05-05T22:21:22"
     "progress":
       {
        "pending":0, "failed":0, "executing":0, "successful":0, "all":5
       },
     "status":"ACTIVE",
    }
  ],
  "statistics" : {
    "pageSize" : 5,
    "currentPage : 1
  }
}

デフォルトでは、クエリ一括オペレーションのエンドポイントはCANCELLEDオペレーションを返しません。 それらのオペレーションを、付加的なクエリパラメーター「withDeleted=true」を追加することによって、応答に含めることができます。

一括オペレーション

一括オペレーションAPIは、デバイスグループ上でのオペレーションを、指定された時間に実行することを可能にします。 オペレーションが作成される都度の遅延時間を指定する必要があります。 一括オペレーションは、作成される時点での状態はACTIVEです。 すべてのオペレーションが作成されると、一括オペレーションはCOMPLETEDの状態になります。 作成済みの一括オペレーションは、削除することにより取り消すこともできます。

一括オペレーションを作成する場合、2通りのモードで実行することができます。

ヒント:

一括オペレーションAPIは、標準のデバイス制御APIと異なるロール(BULK_OPERATION_READとBULK_OPERATION_ADMIN)を必要とします。

一括オペレーション [application/vnd.com.nsn.cumulocity.bulkOperation+json]

名称 タイプ 発生回数 説明 PUT/POST
id String 1 オペレーションを固有に識別します なし
self URI 1 このリソースへのリンク なし
groupId String 1 このオペレーションが実施されるべき対象グループを識別します POST: なし PUT: なし
failedParentId String 1 オペレーションをリスケすべき原因となった、失敗した一括オペレーションを識別します POST: なし PUT: なし
startDate String 1 オペレーションを作成すべき時間 POST: 必須 PUT: なし
creationRamp Number 1 すべてのオペレーション作成間の遅延 POST: 必須 PUT: なし
operationPrototype OperationRepresentation 1 グループ内の各デバイスについて実行されるオペレーション POST: 必須 PUT: なし
status String 1 一括オペレーションの状態。可能な値:ACTIVE、COMPLETED、DELETED なし
progress BulkOperationProgressRepresentation 1 処理されたオペレーションの件数に関する情報を格納します なし

PUT - 一括オペレーションの更新

すでに開始した一括オペレーションを更新すると、そのオペレーションはキャンセルされ、新規の一括オペレーションとして作成/計画します。

リクエスト本体: Bulk Operation

応答本体: n/a.

要求されるロール: ROLE_BULK_OPERATION_ADMIN

リクエスト例:

PUT /devicecontrol/bulkoperations/<<bulkoperationId>>
Host: ...
Authorization: Basic ...
Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json
{
  "creationRamp" : 15
}

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json

{
  "id" : "123",
  "self" : "<<This BulkOperation URL>>",
  "groupId" : "124301",
  "status" : "ACTIVE",
  "startDate" : "2011-09-06T12:03:27",
  "operationPrototype":{
    "description": "Restart device",
    "c8y_Restart": {}
  },
  "creationRamp":15,
  "progress":
    {
     "pending":0, "failed":0, "executing":0, "successful":0, "all":2
    }
}

GET - 一括オペレーションの取得

応答本体: Bulk Operation

要求されるロール: ROLE_BULK_OPERATION_READ

リクエスト例:

GET /devicecontrol/bulkoperations/<<bulkoperationId>>
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.bulkoperation+json;ver=...

応答例:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.bulkoperation+json

{
  "id" : "123",
  "self" : "<<This BulkOperation URL>>",
  "groupId" : "124301",
  "status" : "ACTIVE",
  "startDate" : "2011-09-06T12:03:27",
  "operationPrototype":{
    "description": "Restart device",
    "c8y_Restart": {}
  },
  "creationRamp":15,
  "progress":
    {
     "pending":0, "failed":0, "executing":0, "successful":0, "all":2
    }
}

DELETE - 一括オペレーションの削除

リクエスト本体: N/A.

応答メッセージ本体: N/A.

要求されるロール: ROLE_BULK_OPERATION_ADMIN

リクエスト例: 一括オペレーションを削除

DELETE /devicecontrol/bulkoperations/<<id>>
Authorization: Basic ...

応答例:

HTTP/1.1  204 NO CONTENT