Things Cloud | メジャーメント

概要

メジャーメントインターフェースは次の通り三つの部分で構成されています：

「メジャーメントAPI」リソースは、さまざまなフィルター基準に従ってメジャーメントのクエリが可能となるよう、メジャーメントコレクションにURIおよびURIテンプレートを返します。
「メジャーメントコレクション」リソースはメジャーメントを読み出し、新規メジャーメントの作成を可能にします。
「メジャーメント」リソースは、クエリおよび削除が可能な個々のメジャーメントを表わします。

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

単位のシステム

注意：すべてのGETリクエストは「X-Cumulocity-System-Of-Units」ヘッダーをサポートしており、レスポンスで使用される単位系を設定することができます。指定できる値は、「imperial」または「metric」です。「単位」特性を含む全ての測定フラグメントは、必要な単位系を使用するように変換されます。

一般的な変換:

メーター,キログラム法	ヤード,ポンド法
m (meter)	ft (foot)
km (kilometer)	mi (mile)
cm (centimeter)	in (inch)
°C (degree Celsius)	°F (degree Fahrenheit)
"K (Kelvin)	°R (degree Rankine)
g (gram)	oz (ounce)
kg (kilogram)	lb (pound)

例

メジャーメント例:

...
{
    ....
     "c8y_Temperature": {
         "T": {
             "unit": "oC",
             "value": 2.0791169082
         }
     }
}
...

リクエスト例:

GET　/measurement/measurements?valueFragmentType=c8y_Temperature&valueFragmentSeries=T&source=663951
Host: ...
Authorization: Basic ...
X-Cumulocity-System-Of-Units: imperial

応答例:

...
{
    ....
     "c8y_Temperature": {
        "T": {
            "unit": "°F",
            "value": 35.742410434759904
        }
    }
}
...

メジャーメントAPI

MeasurementAPI [application/vnd.com.nsn.cumulocity.measurementApi+json

名称	種別	発生回数	説明
self	URL	1	このリソースへのリンク
measurements	Measurement Collection	1	すべてのメジャーメントのコレクション
measurementsForDate	MeasurementCollection URI template	1	特定の期間からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{dateFrom}、{dateTo}）。
measurementsFor DateAndType	MeasurementCollection URI template	1	特定の種別を含む、特定の期間からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{type}、{dateFrom}および{dateTo}）。
measurementsFor DateAndValueFragmentType	MeasurementCollection URI template	1	値のある特定のフラグメント種別を含む、特定の期間からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{dateFrom}および{dateTo}）。
measurementsFor DateAnd ValueFragmentTypeAnd Type	MeasurementCollection URI template	1	値のある特定のフラグメント種別を含む、特定の期間およびオブジェクト種別からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{dateFrom}、{dateTo}および{type}）。
measurementsFor DateAnd ValueFragmentTypeAnd ValueFragmentSeries	MeasurementCollection URI template	1	値のある特定のフラグメント種別とフラグメントシリーズを含む、特定の期間からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{dateFrom}、{dateTo}および{type}）。
measurementsFor DateAnd ValueFragmentTypeAnd ValueFragmentSeriesAnd Type	MeasurementCollection URItemplate	1	値のある特定のフラグメント種別とフラグメントシリーズを含む、特定の期間およびオブジェクト種別からのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ： {valueFragmentType},{valueFragmentSeries}, {dateFrom}, {dateTo} and {type}).
measurementsFor Source	MeasurementCollection URI template	1	特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{source}）。
measurementsFor SourceAnd Date	MeasurementCollection URI template	1	特定の期間および特定のソースオブジェクトからのイベントすべてから成る読み取り専用コレクション（プレースホルダ：{dateFrom}、{dateTo}、{source}）。
measurementsFor SourceAnd DateAnd Type	MeasurementCollection URI template	1	特定の種別を含む、特定の期間および特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{type}、{dateFrom}、{dateTo}および{source}）。
measurementsFor SourceAnd DateAnd ValueFragmentType	MeasurementCollection URI template	1	特定のフラグメント種別を含む、特定の期間および特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{dateFrom}、{dateTo}および{source}）。
measurementsFor SourceAnd DateAnd ValueFragmentTypeAnd Type	MeasurementCollection URI template	1	特定のフラグメント種別およびオブジェクト種別を含む、特定の期間およびソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{dateFrom}、{dateTo}、{type} および{source}）。
measurementsFor SourceAnd DateAnd ValueFragmentTypeAnd ValueFragmentSeries	MeasurementCollection URItemplate	1	値のある特定のフラグメント種別およびフラグメントシリーズを含む、特定の期間およびソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション(プレースホルダ：{valueFragmentType},{valueFragmentSeries}, {dateFrom}, {dateTo} and {source}).
measurementsFor SourceAnd DateAnd ValueFragmentTypeAnd ValueFragmentSeriesAnd Type	MeasurementCollection URItemplate	1	値とタイプオブジェクトのある特定のフラグメント種別およびフラグメントシリーズを含む、特定の期間およびソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション(プレースホルダ：{valueFragmentType}, {valueFragmentSeries}, {dateFrom}, {dateTo}, {type}　および {source}).
measurementsFor SourceAnd Type	MeasurementCollection URI template	1	特定の種別を含む、特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{type}および{source}）。
measurementsFor SourceAnd ValueFragmentType	MeasurementCollection URI template	1	特定のフラグメント種別を含む、特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}および{source}）。
measurementsFor SourceAnd ValueFragmentTypeAnd Type	MeasurementCollection URI template	1	特定のフラグメント種別を含む、特定の種別およびソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}、{type}および{source}）。
measurementsFor SourceAnd ValueFragmentTypeAnd ValueFragmentSeries	MeasurementCollection URI template	1	値のある特定のフラグメント種別およびフラグメントシリーズを含む、特定のソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション(プレースホルダ：{valueFragmentType}, {valueFragmentSeries} and {source}).
measurementsFor SourceAnd ValueFragmentTypeAnd ValueFragmentSeriesAnd Type	MeasurementCollection URItemplate	1	値のある特定のフラグメント種別とフラグメントシリーズを含む、特定の種別およびソースオブジェクトからのメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType}, {valueFragmentSeries},{type} and {source}).
measurementsFor ValueFragmentType	MeasurementCollection URI template	1	値のある特定のフラグメント種別を含むメジャーメントすべてから成る読み取り専用コレクション。
measurementsFor ValueFragmentTypeAnd Type	MeasurementCollection URI template	1	特定の種別および特定のフラグメント種別を含むメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{type} および{valueFragmentType}）。
measurementsFor ValueFragmentTypeAnd ValueFragmentSeries	MeasurementCollection】 URI template	1	値のある特定の種別および特定のフラグメント種別とフラグメントシリーズを含むメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{valueFragmentType} and{valueFragmentSeries}).
measurementsFor ValueFragmentTypeAnd ValueFragmentSeriesAnd Type	MeasurementCollection】URI template	1	値のある特定の種別および特定のフラグメント種別を含むメジャーメントすべてから成る読み取り専用コレクション（プレースホルダ：{type}, {valueFragmentType}およびvalueFragmentSeries}).

queryパラメータである「fragmentType」は廃止されました。APIでは引き続き使用できますが、クライアントはパラメータを「valueFragmentType」および「valueFragmentSeries」に置き換えることを推奨します。これにより、クエリのパフォーマンスが大幅に向上します。これらのパラメータを持つ標準測定値を持つフラグメントのみを照会できることに注意してください。他の形式は照会できません。

大規模なメジャメントコレクションの場合、フィルタを使用しない最新ページのクエリは、結果を返す前に入力結果セットの先頭からサーバーがスキャンする必要があるため、時間がかかることがあります。最新の測定値を取得する必要がある場合に備えて、Things Cloudでは、デバイスによって報告されたタイムスタンプ上で時間範囲クエリとベースクエリを使用して範囲を狭めることを推奨しています。また、ソースごとにクエリを実行することで、クエリの範囲を大幅に縮小することもできます。

メジャーメントAPIリソースをGETする

応答本体： application/vnd.com.nsn.cumulocity.measurementApi+json

要求されるロール：ROLE_MEASUREMENT_READ

リクエスト例：

GET /measurement
Host: ...
Authorization: Basic ...

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurementApi+json;ver=...
Content-Length: ...
{
  "self" : "<<Measurement API URL>>",
  "measurements" : { "self" : "<<MeasurementCollection URL>>" },
  "measurementsForDate" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
  "measurementsForDateAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "measurementsForDateAndValueFragmentType" :"<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}",     
  "measurementsForDateAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForDateAndValueFragmentTypeAndValueFragmentSeries" :"<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForDateAndValueFragmentTypeAndValueFragmentSeriesAndType" :"<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForSource" : "<<MeasurementCollection URL>>?source={source}",
  "measurementsForSourceAndDate" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
  "measurementsForSourceAndDateAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
  "measurementsForSourceAndDateAndValueFragmentType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndValueFragmentSeries": "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForSourceAndDateAndValueFragmentTypeAndValueFragmentSeriesAndType": "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForSourceAndType" : "<<MeasurementCollection URL>>?source={source}&type={type}",
  "measurementsForSourceAndValueFragmentType" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}",
  "measurementsForSourceAndValueFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForSourceAndValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForSourceAndValueFragmentTypeAndValueFragmentSeriesAndType": "<<MeasurementCollection URL>>?source={source}&valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}",
  "measurementsForType" : "<<MeasurementCollection URL>>?type={type}",
  "measurementsForValueFragmentType" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}",
  "measurementsForValueFragmentTypeAndType" :"<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&type={type}",
  "measurementsForValueFragmentTypeAndValueFragmentSeries" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}",
  "measurementsForValueFragmentTypeAndValueFragmentSeriesAndType" : "<<MeasurementCollection URL>>?valueFragmentType={valueFragmentType}&valueFragmentSeries={valueFragmentSeries}&type={type}"
}

メジャーメントコレクション

MeasurementCollection [application/vnd.com.nsn.cumulocity.measurementCollection+json]

名称	種別	発生回数	説明
self	URL	1	このリソースへのリンク
measurements	Measurement	0..n	メジャーメントのリスト（下記参照）
statistics	PagingStatistics	1	ページング統計に関する情報
prev	URI	0..1	メジャーメントの潜在的な前のページへのリンク
next	URI	0..1	メジャーメントの潜在的な次のページへのリンク

メジャーメントコレクションをGETする

応答本体： MeasurementCollection

要求されるロール：ROLE_MEASUREMENT_READ

リクエスト例：電力使用量を読み出す

 GET /measurement/measurements
 Host: ...
 Authorization: Basic ...
 Accept: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
Content-Length: ...
{
  "self":"...",
  "measurements":[
    {
      "id" : "42",
      "self" : "...",
      "time" : "2011-09-06T12:03:27.845Z",
      "type" : "KamstrupA220Reading",
      "source" : { "id": "12345", "self": "..." },
      "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
        "A+:1": { "value": 123, "unit": "kWh" },
        "A-:1": { "value": 2, "unit": "kWh" }
      },
      "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
        "A+:1": { "value": 123, "unit": "kWh" },
        "A+:2": { "value": 123, "unit": "kWh" },
        "A+:3": { "value": 123, "unit": "kWh" }
      }
    },
    {
      "id" : "43",
      "self" : "...",
      "time" : "2011-09-19T12:03:27.845Z",
      "type" : "KamstrupA220Reading",
      "source" : { "id": "12345", "self": "..." },
      "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
        "A+:1": { "value": 1234, "unit": "kWh" },
        "A-:1": { "value": 2, "unit": "kWh" }
      },
      "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
        "A+:1": { "value": 1234, "unit": "kWh" },
        "A+:2": { "value": 1234, "unit": "kWh" },
        "A+:3": { "value": 1234, "unit": "kWh" }
      }
    }
  ],
  "statistics" : {
    "totalPages" : 2,
    "pageSize" : 5,
    "currentPage : 1
  }
}

メジャーメントAPIに対して範囲のクエリ、例えばdateFromおよびdateToによるクエリを実行する場合、メジャーメントは古いものから順に返されます。クエリパラメータ「revert=true」をリクエストURLに追加することにより、順序を変えることができます。多くの場合、デバイスから送信された最新のメジャーメントを取得する必要があります。例えば1年前からのdateFromや将来からのdateToを渡すといったように、日付によって結果をソートできるよう、「dateFrom」および「dateTo」のパラメータと併せて「revert」パラメータを渡すことによって可能です。

メジャーメントシリーズの全部または一部を取得(GET)する

このエンドポイントは、シリーズ(すべてまたは指定された名称にマッチするもの。シリーズとは「value」プロパティを持つメジャーメントの任意のフラグメント)と指定された期間内の値のリストを返却します。必須パラメータはdateFrom、dateToおよびsourceです。ページングは使用されません。以下の付加的パラメータを渡すことにより、取得したメジャーメントを集計することができます： aggregationType（DAILY、HOURLY、MINUTELY）。集計パラメータが指定されない場合、結果に含まれる値は5000件以下です。重要事項：集計を適正に行うため、デバイスが日付を送信する際に必ず同じタイムゾーンを使用する必要があります。

要求されるロール：ROLE_MEASUREMENT_READ

リクエスト例： retrieve all series.

 GET /measurement/measurements/series...
 Authorization: Basic ...
 Accept: application/json

応答例：

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

{
 values: {
     2014-12-04T17:33:01.538+01:00: [
         {
          min: 13.37,
          max: 13.37
         },
         {
          min: 11.37,
          max: 11.37
         }],
     2014-12-04T17:34:01.774+01:00: [
         {
          min: 10.2,
          max: 10.2
         },
         {
          min: 11.37,
          max: 11.37
         }]
 },
 series: [
         {
          unit: "m/s2",
          name: "acceleration",
          type: "c8y_AccelerationMeasurement"
         },
         {
          unit: "m/s",
          name: "velocity",
          type: "c8y_SpeedMeasurement"
         }],
 truncated: false
}

シリーズは、メジャーメントタイプ、シリーズ名を共に含む「series」パラメータを追加することでフィルタリングできます。さらに「series」パラメータを追加することで、フィルタリングされるシリーズを追加できます。例：...series=c8y_AccelerationMeasurement.acceleration&series=c8y_SpeedMeasurement.velocity... このユースケースのために、メジャーメントフラグメントでもシリーズでもドットは使用してはいけません。

要求例：特定のシリーズのみを取得

GET /measurement/measurements/series?series=c8y_AccelerationMeasurement.acceleration&dateFrom=...
Authorization: Basic ...
Accept: application/json

応答例：

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

{
 values: {
     2014-12-04T17:33:01.538+01:00: [
         {
          min: 13.37,
          max: 13.37
         }],
     2014-12-04T17:34:01.774+01:00: [
         {
          min: 10.2,
          max: 10.2
         }]
 },
 series: [
         {
          unit: "m/s2",
          name: "acceleration",
          type: "c8y_AccelerationMeasurement"
         }],
 truncated: false
}

オブジェクト内の個々の値はメジャーメントから取得される日付であり、その日付の範囲内に最小値と最大値のペアのリストが存在します。各ペアはシリーズオブジェクトにおける単一のseriesの定義に呼応します。集計を使用しない場合、すべてのペアにおいて最小値と最大値は同じです。

「Truncated」フラグは、値が5000件を超えたことにより最終結果が切り捨てられていることを示します。

POST - 新規メジャーメントの作成

リクエスト本体：メジャーメント

応答本体：メジャーメント

要求されるロール：ROLE_MEASUREMENT_ADMIN or owner of source object

リクエスト例：

POST /measurement/measurements
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
{
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345" },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

応答例：

HTTP/1.1 201 Created
Content-Length: ...
{
  "id" : "43",
  "self" : "<<URL of new measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

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

新規メジャーメントの「id」はサーバーによって生成され、応答においてPOSTオペレーションへ返されます。

注記：メジャーメントシリーズをUIグラフ上で適正に可視化するため、フラグメントおよびserieに使用されるプロパティ名は、空白や特殊文字（例：[],*.）を含んではなりません。

POST - 複数のメジャーメントの作成

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

{
"measurements": [
    {
     "c8y_SpeedMeasurement": {
         "speed": {
             "value": 25,
             "unit": "km/h" }
            },
     "time":"2013-06-22T17:03:14.000+02:00",
     "source": {
         "id":"10200" },
     "type": "c8y_SpeedMeasurement"
    },
    {
     "c8y_SpeedMeasurement": {
            "speed": {
            "value": 22,
            "unit": "km/h" }
            },
     "time":"2013-06-22T17:05:14.000+02:00",
     "source": {
         "id":"10200" },
     "type": "c8y_SpeedMeasurement"
    }
]
}

応答例:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
Content-Length: ...

{
 "measurements": [
    {
     "time": "2013-06-22T17:03:14.000+02:00",
     "id": "832254760",
     "self": "<<URL of new measurement>>"",
     "source": {"id": "10200","self": "..."},
     "type": "c8y_SpeedMeasurement",
     "c8y_SpeedMeasurement": {
         "speed": {
            "unit": "km/h",
            "value": 25
            }
        }
    },
    {
     "time": "2013-06-22T17:05:14.000+02:00",
     "id": "832254761",
     "self": "<<URL of new measurement>>",
     "source": {"id": "10200","self": "..."},
     "type": "c8y_SpeedMeasurement",
     "c8y_SpeedMeasurement": {
         "speed": {
            "unit": "km/h",
            "value": 22
            }
        }
    }
]
}

DELETE - メジャーメントコレクションをDELETEする

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

Request body: N/A

応答本体： N/A

要求されるロール：ROLE_MEASUREMENT_ADMIN

リクエスト例：

DELETE: /measurement/measurements....
Host: ...
Authorization: Basic ...

応答例：

HTTP/1.1  204 NO CONTENT

メジャーメント

メジャーメント [application/vnd.com.nsn.cumulocity.measurement+json]

名称	種別	発生回数	説明	POST
id	String	1	メジャーメントを一意に識別します	いいえ
self	URI	1	このリソースへのリンク	いいえ
time	String	1	メジャーメントの時間	必須
type	String	1	このメジャーメント種別を端的に示す種別名	必須
source	ManagedObject	1	このメジャーメントのソースであるマネージドオブジェクト。オブジェクトは「id」および「self」のプロパティを含みます	必須
*	*	0..n	メジャーメントフラグメントのリスト	オプション

各メジャーメントフラグメントは実際のメジャーメントをプロパティとして含むオブジェクトです。プロパティ名はメジャーメントの名称に相当し、プロパティ値は以下のように構造化されます。

名称	種別	発生回数	説明	POST
value	Number	1	個々のメジャーメントの値	必須
unit	String	1	メジャーメントの単位、「Wh」または「C」など	オプション

メジャーメントをGETする

応答本体：メジャーメント

要求されるロール：ROLE_MEASUREMENT_READ

リクエスト例：

GET /measurement/measurements/<<measurementId>>
Host: ...
Authorization: Basic ...

応答例：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
Content-Length: ...
{
  "id" : "43",
  "self" : "<<URL of the measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A-:1": { "value": 2, "unit": "kWh" }
  },
  "com_cumulocity_msrmts_ThreePhaseReading": {
    "A+:1": { "value": 1234, "unit": "kWh" },
    "A+:2": { "value": 1234, "unit": "kWh" },
    "A+:3": { "value": 1234, "unit": "kWh" }
  }
}

メジャーメントをDELETEする

リクエスト本体：N/A

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

要求されるロール：ROLE_MEASUREMENT_ADMIN or owner of source object

リクエスト例：メジャーメントをDELETEする

DELETE /measurement/measurements/<<measurementID>>
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx

応答例：

HTTP/1.1  204 NO CONTENT

データストリーミング

メジャーメントコレクションAPIによって、データストリームの形式で取得できます。レスポンスフォーマットは同じですが、データはサーバーによってデータベースから要素ごとに直接送信されます。データは同様に取得できます。 java jsonパーサのようなストリームJSON解析を利用することで、単一要求で大容量のデータを転送することができます。ストリーミングを利用するには、Accept ヘッダーに application/json-stream を設定します。

例：

 GET /measurement/measurements
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx
 Accept application/json-stream

他のレスポンスフォーマット

JSON以外のフォーマットでメジャーメントを取得するため、Accept ヘッダーに次を利用できます。

text/csv,
application/vnd.ms-excel.

通知

メジャーメント通知APIを使用すると、特定のデバイスに関するすべてのメジャーメントの更新を受信することができます。通知を受信するための基本プロトコルは「リアルタイム通知」セクションに記載されています。URLは以下の通りです。

/cep/realtime

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

/measurements/<<deviceId>>

応答は付加的にメジャーメントオブジェクト宛に、所定のオブジェクトにおいて結果的に発生したアクションを識別する「realtimeAction」を包含することになります（CREATE、UPDATEまたはDELETE）。削除の場合、データは、削除されるメジャーメントのIDのみ包含することになります。

応答例：

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "channel": "/measurement/12345",
    "successful": true,
    "error": "",
    "data": [{
      "realtimeAction": "CREATE",
      "data": {
        "id": "1",
        "self": "...",
        "source": {
          "12345"
        },
        "creationTime": "2011-09-06T12:03:27.927+02:00",
        "c8y_TemperatureMeasurement": {
          "T": {
            "value": 25,
            "unit": "C"
          }
        },
        "time":"2011-09-06T12:03:17.927+02:00",
        "type": "TemperatureMeasurement"
      }
    }],
    "clientId": "Un1q31d3nt1f13r"
  }
]

要求されるロール：ROLE_MEASUREMENT_READ