デバイス制御

概要

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

  • 「デバイス制御API」リソースは、さまざまな基準によるオペレーションのクエリが可能となるよう、オペレーションコレクションにURIおよびURIテンプレートを返します。
  • 「オペレーションコレクション」リソースはオペレーションを読み出し、新規オペレーションの作成を可能にします。
  • 「オペレーション」リソースは、クエリおよび修正が可能な個々のオペレーションを表わします。

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

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

デバイス制御API

DeviceControlAPI [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})。

デバイス制御APIリソースをGETする

応答本体: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}"
}

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

OperationCollection [application/vnd.com.nsn.cumulocity.operationCollection+json]

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

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

  • 組み込みオペレーションオブジェクトは、「agentId」パラメータを使用して問い合わせを受けた場合に限り、「deviceExternalIDs」を格納します。
  • 組み込みオペレーションオブジェクトは「deviceName」が入力されますが、「オペレーションコレクションの取得」をリソースにリクエストする場合に限られます。
  • オペレーションは作成された順番で返されます(FIFO キュー)。

POST - オペレーションを作成する

リクエスト本体:オペレーション

応答本体:オペレーション?

要求されるロール: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する

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する

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に設定可能。
failureReason String 0..1 失敗理由。 いいえ
* Object 1..n デバイス上で実施予定のオペレーションを表わす付加的プロパティ。 POST:オプション、PUT:オプション

注意: PUT のステータスが"failed" の場合のみ failureReason がオプションとなる.

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

PUT - オペレーションを更新する

リクエスト本体:オペレーション

応答本体: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する

応答本体:オペレーション

要求されるロール: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"
    }
  }
}

通知

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

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

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

/devicecontrol/notifications

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

/<<agentId>>

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

/5

要求されるロール:ROLE_DEVICE_CONTROL_READ

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

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

/cep/realtime

サブスクリプションには、そのデバイスのマネージドオブジェクトIDを含める必要があります。または、 "*" を指定することで、すべてのデバイスに対する通知を受け取れます。

/operations/<<deviceId>>

応答は、オペレーションのオブジェクトにどのアクション(CREATE, UPDATE, DELETE)が行われたかを示す "realtimeAction" を追加したオブジェクトになります。削除時は、"data" 部分は削除されたオペレーションの 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

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

BulkOperationCollection [application/vnd.com.nsn.cumulocity.bulkOperationCollection+json]

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

POST - 一括オペレーションを作成する

リクエスト本体:一括オペレーション

応答本体:一括オペレーション

要求されるロール: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 all bulk operations.

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通りのモードで実行することができます。

  • groupIdが渡される場合、標準の状態で動作します。つまり、グループからデバイスを取得し、それらのデバイスに対するオペレーションのスケジュールを立てます。
  • failedParentIdが渡される場合、そのIDによってすでに処理済みの一括オペレーションを取得し、直前のオペレーションに失敗したデバイス上でのオペレーションのスケジュールを立てます。

ヒント:

  • groupIdとfailedParentIdの双方を渡すことは禁止です。
  • 一括オペレーションは静的種別と「動的」種別、どちらのデバイスグループでも機能します。

一括オペレーション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 グループ内の各デバイスについて実行されるオペレーション。 グループ内の各デバイスについて実行されるオペレーション。
status String 1 一括オペレーションの状態。可能な値:ACTIVE、COMPLETED、DELETED No
progress BulkOperationProgressRepresentation 1 処理されたオペレーションの件数に関する情報を格納します。 いいえ

PUT - 一括オペレーションを更新する

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

リクエスト本体:一括オペレーション

応答本体: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する

応答本体:一括オペレーション

要求されるロール: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する

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

応答例:

HTTP/1.1  204 NO CONTENT