FORMAT: 1A
HOST: http://orion.lab.fiware.org
TITLE: FIWARE-NGSI v2 Specification (jp)
DATE: 15 Sep 2018
VERSION: 2.0
PREVIOUS_VERSION: RC-2018_07
APIARY_PROJECT: orioncontextbroker
SPEC_URL: https://telefonicaid.github.io/fiware-orion/api/v2/
GITHUB_SOURCE: http://github.com/telefonicaid/fiware-orion.git

# FIWARE-NGSI v2 仕様

この仕様は、FIWARE-NGSI version 2 API を定義します。FIWARE-NGSI v2 は、
アップデート (update), クエリ (queries), レジストレーション (registrations),
サブスクリプション (subscriptions) など、コンテキスト情報のライフサイクル
全体を管理することを目的としています。

# はじめに

## 編集者

José Manuel Cantera Fonseca (FIWARE Foundation e.V., formerly with Telefónica I+D), 
Fermín Galán Márquez (Telefónica España, formerly with Telefónica I+D),
Tobias Jacobs (NEC).
  
## 謝辞

編集者は積極的に次の人々に感謝の意を表します
この仕様に寄与しました : 
Juan José Hierro (FIWARE Foundation e.V., formerly with Telefónica I+D), 
Marcos Reyes (Telefónica España, formerly with Telefónica I+D), 
Ken Zangelin (APInf, formerly with Telefónica I+D),
Iván Arias León (Telefónica I+D), Carlos Romero Brox (Telefónica I+D),
Antonio José López Navarro (Telefónica I+D),  Marc Capdevielle (Orange), Gilles Privat (Orange), 
Sergio García Gómez (Telefónica I+D), Martin Bauer (NEC).
  
## ステータス

この仕様は、NGSIv2 API 仕様 (v2.0) の最終的かつ安定版です。

#変更履歴

RC-2018.07 以降の変更点 :

* なし

RC-2018.04以降の変更点 :

* セクション "システム/組み込み属性" を "組み込み属性" に改名
* セクション "システム/組み込みメタデータ" を "組み込みメタデータ" に改名
* 新しい組み込み属性の追加 : `dateExpires`
* "エラー レスポンス"セクションの説明を改善
* `POST /v2/entities` オペレーションの新しいオプションを追加しました : `upsert`
* "レジストレーション " におけるコンプライアンスの推進について明確化
* `POST /v2/op/update` オペレーションの `actionType` 値は現在、キャメル・ケース (camelCase) です
* `POST /v2/op/query` オペレーションにおいて、`attributes` フィールド` を `attrs` に変更
* `POST /v2/op/query` オペレーションに新しいフィールドを追加 : `expression` (古い `scope` フィールドは削除されました)
* 新しいオペレーション `POST /v2/op/notify` を追加

RC-2017.11 以降の変更点 : 

* `orderBy` は、`id` と `type` を順序フィールド (ordering fields) として含むことができます
* `GET /v2` レスポンスに `registrations_url` を含めます
* レジストレーション管理オペレーションを追加
   * `GET /v2/registrations`
   * `POST /v2/registrations`
   * `GET /v2/registrations/{id}`
   * `PATCH /v2/registrations/{id}`
   * `DELETE /v2/registrations/{id}`

RC-2016.10 以降の変更点 :

* 新しい "System/組み込みメタデータ" セクション (部分的に元の "通知の特別なメタデータ" セクションを使用)
* 新しい "属性とメタデータのフィルタリング" セクション
* セクション "仮想属性"を "システム/組み込み属性" に改名
* 新しいシステム/組み込みメタデータ : `dateCreated` および `dateModified`
* "属性名の制限" セクション に `*` を追加
* サブスクリプション情報に `lastFailure` および `lastSuccess` を追加
* サブスクリプション `status` フィールドに `failed` 値を追加
* さまざまなアクション・タイプの明確な説明とともに、
  `POST /v2/op/update` オペレーションの `actionType` として `REPLACE` を追加
* `POST /v2/op/query` オペレーションに `metadata` フィールドを追加
* 以下のオペレーションに `metadata` URI パラメータを追加 :
   * `GET /v2/entities`
   * `GET /v2/entities/{entityId}`
   * `GET /v2/entities/{entityId}/attrs`
   * `GET /v2/entities/{entityId}/attrs/{attrName}`

RC-2016.05 以降の変更点 : 

* schema.org に則ったエンティティ、属性、メタデータの既定のタイピング
* `typePattern` (`idPattern` に似ています)
* シンプル・クエリ言語 : メタデータ・フィルタ (`mq`)
* シンプル・クエリ言語 : サブキー・フィルタリング (属性とメタデータの両方の値、つまり `q` と `mq`)
* 通知メタデータのフィルタリング
* 通知のシステム/組み込みメタデータ : `previousValue` および `actionType`

## 著作権

Copyright (c) 2011-2018 Telecom Italia, Telefónica I+D and NEC.

## ライセンス

この仕様は、[FIWARE Open Specification License (implicit patent license)](https://forge.fiware.org/plugins/mediawiki/wiki/fiware/index.php/Implicit_Patents_License) 下でライセンスされています。

## コンフォーマンス

この仕様では、"完全な" コンプライアンス・レベルについて説明します。

## コンベンション

NGSI version 2 では、使用されるプロパティおよび関連する成果物の名前付けに
キャメル・ケース (camelCase) 構文が使用されています。API によって、HATEOAS
パターンの一部として URI を参照し、それらを適切にマークする場合、
サフィックス `_url` が追加されます。

## リファレンス実装

* NGISv2 Context Brokers
  * [Orion Context Broker](http://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker) - [Implementation Notes](https://fiware-orion.letsfiware.jp/user/ngsiv2_implementation_notes/index.html)

# 仕様

## はじめに

FIWARE NGSI (Next Generation Service Interface) API は、 

* *コンテキスト・エンティティ*の概念を使用した単純な情報モデルに基づく、
  コンテキスト情報の **データ・モデル**
* クエリ、サブスクリプション、および更新オペレーションによって情報を交換する
  **コンテキスト・データ・インターフェイス**
* コンテキスト情報を取得する方法に関する情報を交換するための
  **コンテキスト・アベイラビリティ・インタフェース**
  (2つのインタフェースを分離するかどうかは、現在検討中です)

## 用語

### コンテキスト・データのモデリングと交換 (Context data modelling and exchange)

NGSI データモデルの主な要素は、下図のように、コンテキストのエンティティ、属性
およびメタデータです。

![NGSI data model](https://raw.githubusercontent.com/telefonicaid/fiware-orion/master/doc/apiary/v2/Ngsi-data-model.png)

#### コンテキストのエンティティ (Context Entities)

コンテキストのエンティティ、または単にエンティティは、FIWARE NGSI 情報モデルの
中心です。エンティティはモノ、すなわち、任意の物理的または論理的オブジェクトです。
たとえば、センサ、人、部屋、発券システムの問題などです。
各エンティティには **entity id** があります。

さらに、FIWARE NGSI の型システム (type system) により、
エンティティは、**エンティティ型 (entity type)** を持つことができます。
エンティティ型はセマンティック型です。
エンティティによって表されるモノの種類を記述することを意図しています。
たとえば、id *sensor-365* のコンテキストのエンティティは、*temperatureSensor* 型
を持つことができます。

各エンティティは、その id と型の組み合わせによって一意に識別されます。

#### コンテキストの属性 (Context Attributes)

コンテキストの属性は、コンテキストのエンティティのプロパティです。
たとえば、現在の車の速度は、エンティティ *car-104* の
属性 *current_speed* のようにモデル化できます。

NGSI データモデルでは、属性は、*属性名 (attribute name)*, *属性型 (attribute type)*,
*属性値 (attribute value)* および *メタデータ (metadata)* を持っています。
* 属性名は、その属性値がエンティティのどのような種類のプロパティを表すかを
  記述します。例 : *current_speed*。
* 属性型は、属性値の NGSI 値型 (NGSI value type) を表します。
FIWARE NGSI には属性値用の独自の型システムがあるため、
NGSI 値型は JSON 型 (JSON types) と同じではありません。
* 属性値には次のものが含まれます :
  * 実際のデータ
  * オプション **metadata** は、精度、プロバイダ、タイムスタンプなどの
    属性値のプロパティを記述します
  
#### コンテキストのメタデータ (Context Metadata)

コンテキストのメタデータは、いくつかの場所で FIWARE NGSI で使用され、
そのうちの1つは、上述のように属性値のオプション部分です。属性と同様に、
各メタデータには次のものがあります :
 * **メタデータ名 (metadata name)** メタデータの発生場所におけるメタデータの
   役割を記述します。たとえば、メタデータ名 *accuracy* は、そのメタデータ値が
   与えられた属性値がどの程度正確であるかを記述していることを示します。
 * **メタデータ型 (metadata type)**, メタデータ値の NGSI 値型を記述します。
 * **メタデータ値 (metadata value)** 実際のメタデータを含んでいます。

NGSI では、メタデータにネストされたメタデータが含まれることは
予期されていないことに注意してください。

##  MIME 型 (MIME Types)

この仕様の API レスポンス・ペイロードは `application/json` と (属性値型
オペレーションのために) `text/plain` MIME 型に基づいています。 
HTTP リクエストを発行するクライアントは、それ以外の受け入れ型で、
`406 Not Acceptable` エラーが発生します。

##  JSON エンティティ表現 (JSON Entity Representation)

エンティティは、次の構文を持つ JSON オブジェクトで表されます :

* エンティティ id は、オブジェクトの `id` プロパティによって指定され、
  その値はエンティティ id を含む文字列です。

* エンティティ型は、オブジェクトの `type` プロパティによって指定され、
  その値はエンティティの型名を含む文字列です。

* エンティティ属性は、追加のプロパティによって指定されます。名前は
  属性の `name` であり、その表現は下の "JSON 属性表現" のセクションで
  説明します。 明らかに、`id` および `type` は属性名として使用できません。

この構文の例を以下に示します :

```
{
  "id": "entityID",
  "type": "entityType",
  "attr_1": <val_1>,
  "attr_2": <val_2>,
  ...
  "attr_N": <val_N>
}
```

エンティティの正規化された表現には、常に `id`、`type`、および属性を表す
プロパティが含まれます。しかし、簡略化 (simplified) または、
部分表現 (simplified) (以下の "部分表現" のセクションを参照) は、
一部を残してしまう可能性があります。
各オペレーションの仕様には、どの表現が入力として期待されるか、どの表現が
出力として提供 (レンダリング) されるかに関する詳細が含まれます。

##  JSON 属性表現 (JSON Attribute Representation)

属性は、次の構文を持つ JSON オブジェクトで表されます :

* 属性値は `value` プロパティによって指定され、その値は任意の JSON データ型
  になります。

* 属性 NGSI 型は、`type` プロパティによって指定され、その値は、NGSI 型を
  含む文字列です。

* 属性メタデータは `metadata` プロパティによって指定されます。 その値は、
  定義されたメタデータ要素ごとのプロパティを含む別の JSON オブジェクトです
  (プロパティの名前はメタデータ要素の `name` です)。 各メタデータ要素は、
  次のプロパティを保持する JSON オブジェクトで表されます :

  * `value`: その値には、JSON データ型に対応するメタデータ値が含まれています。

  * `type`: その値には、メタデータの NGSI 型の文字列表現が含まれます。

この構文の例を以下に示します :

```
{
  "value": <...>,
  "type": <...>,
  "metadata": <...>
}
```

## 簡略化されたエンティティ表現 (Simplified Entity Representation)

実装によってサポートされなければならない 2つの表現モードがあります。
これらの表現モードは、エンティティの簡略化された表現を生成することを可能にします。

* *keyValues* モード。このモードでは、型とメタデータに関する情報を除外して、
  エンティティの属性を値のみで表します。
  以下の例を参照してください。

```
{
  "id": "R12345",
  "type": "Room",
  "temperature": 22
}
```

* *values* モード。このモードでは、エンティティを属性値の配列として表します
  id と型に関する情報は除外されています。
  以下の例を参照してください。
  配列内の属性の順序は、`attrs` URI パラメータによって指定されます。
  (たとえば、`attrs=branch,colour,engine`)。
  `attrs` が使用されない場合、順序は任意です。

```
[ 'Ford', 'black', 78.3 ]
```

*  *unique* モード。このモードは、値が繰り返されない点を除いて、*values* モード
   と同じです。

## 部分表現 (Partial Representations)

一部のオペレーションでは、エンティティの部分表現を使用します :

* `id` と` type` は、不変のプロパティであるため、更新オペレーションでは
  使用できません。

* エンティティ `type` が許されるリクエストでは、それを省略することができます。
  エンティティ作成オペレーションで省略された場合、デフォルトの文字列値
  `Thing` が型に使用されます。

* 場合によっては、エンティティのすべての属性が表示されるわけではありません。
  たとえば、エンティティ属性のサブセットを選択するクエリ。

* 属性/メタデータ `value` は、属性/メタデータが `null` 値を持つことを
  意味するリクエストでは省略することができます。レスポンスでは、値は常に
  存在します。

* 属性/メタデータ `type` はリクエストで省略することができます。
  属性/メタデータの作成または更新オペレーションで省略された場合、
  その値に応じて、型に対してデフォルトが使用されます。
  * 値が文字列の場合、`Text` 型が使用されます。
  * 値が数値の場合、`Number` 型が使用されます。
  * 値がブーリンの場合は、`Boolean` が使用されます。
  * 値がオブジェクトまたは配列の場合、`StructuredValue` が使用されます。
  * 値が null の場合、`None` が使用されます。

* 属性 `metadata` はリクエストでは省略することができます。つまり、
  属性に関連付けられたメタデータ要素がありません。レスポンスでは、
  属性にメタデータがない場合、このプロパティは `{}` に設定されます。


## 特殊な属性型 (Special Attribute Types)

一般に、ユーザ定義の属性型は有益です。それらは不透明な方法で NGSIv2
サーバによって処理されます。それにもかかわらず、以下に説明する型は、
特別な意味を伝えるために使用されます :

* `DateTime`: 日付を ISO8601 形式で識別します。これらの属性は、
  より大きい、未満、以上、以下 および範囲のクエリ演算子で
  使用できます。たとえば、参照されたエンティティ属性のみが表示されます。

```
{
  "timestamp": {
    "value": "2017-06-17T07:21:24.238Z",
    "type: "DateTime"
  }
}
```

* `geo:point`, `geo:line`, `geo:box`, `geo:polygon`, `geo:json`。
  これらはエンティティの場所に関連する特別なセマンティクスを持っています。
  "エンティティの地理空間プロパティ" を参照してください。

## 組み込み属性 (Builtin Attributes)

NGSIv2 クライアントによって直接変更できないエンティティのプロパティが
ありますが、追加情報を提供するために NGSIv2 サーバによってレンダリングする
ことができます。 表現の観点から見ると、それらは名前、値、型とともに
通常の属性と同じです。

組み込み属性はデフォルトでレンダリングされません。特定の属性をレンダリング
するには、URLs (または、POST /v2/op/query オペレーションのペイロード・フィールド)
または、サブスクリプション (`notification` 内の `attrs` サブフィールド) の
`attrs` パラメータにその名前を追加してください。

組み込み属性のリストは次のとおりです :

* `dateCreated` (型 : `DateTime`) : エンティティ作成日。ISO 8601 文字列です。

* `dateModified` (型 : `DateTime`) :エンティティ変更日。ISO 8601 文字列です。

* `dateExpires` (型 : `DateTime`) : エンティティの有効期限。ISO 8601 文字列です。
  サーバがエンティティの有効期限を制御する方法は、実装の固有側面です。

通常の属性と同様に、`q` フィルタと `orderBy` で使うことができます。
ただし、リソース URLs では使用できません。

## 組み込みメタデータ (Builtin Metadata)

いくつかの属性プロパティは、NGSIv2 クライアントによって直接、変更可能では
ありませんが、NGSIv2 サーバによってレンダリングされて追加情報を提供する
ことができます。表現の観点から見ると、それらは名前、値、型ともに
通常のメタデータと似ています。

組み込みメタデータは、デフォルトではレンダリングされません。特定のメタデータを
レンダリングするには、その名前を `metadata` URL パラメータ
(または、POST /v2/op/query オペレーションのペイロード・フィールド)
または、サブスクリプション (`notification` の `metadata` サブフィールド) に
追加してください。

組み込みメタデータのリストは次のとおりです :

* `dateCreated` (型 : `DateTime`) : 属性作成日。ISO 8601 文字列です。

* `dateModified` (型 : `DateTime`) : 属性変更日。ISO 8601 文字列です。

* `previousValue` (型 : any) : 通知でのみ。このメタデータの値は、関連する
  属性の通知をトリガーするリクエストに対する以前の値です。このメタデータの型は、
  関連付けられた属性の以前の型でなければなりません。`previousValue` の型/値が、
  関連する属性と同じ型/値である場合、その属性は実際に値を変更していません。

* `actionType` (型 : `Text`) : 通知のみ。添付されている属性が、通知を
  トリガーしたリクエストに含まれていた場合に含まれます。 その値は、リクエスト・
  オペレーションのタイプによって異なります。更新の場合は `update`、
  作成の場合は `append`、削除の場合は `delete`です。その型は常に `Text`です。

通常のメタデータと同様、`mq` フィルタでも使用できます。ただし、リソース URLs 
では使用できません。

## フィールド構文の制限事項 (Field syntax restrictions)

NGSIv2 API の識別子として使用されるフィールドは、許可される構文に関する特別な
規則に従います。 これらの規則は :

*エンティティ id (Entity id)
*エンティティ型 (Entity type)
*属性名 (Attribute name)
*属性型 (Attribute type)
*メタデータ名 (Metadata name)
*メタデータ型 (Metadata type)

ルールは次のとおりです :

* 使用できる文字は、制御文字, 空白, `&`, `?`, `/`, `#` の文字を除き、
  プレーンな ASCII セットの文字です。
* 最大フィールド長は 256文字です。
* 最小フィールド長は 1文字です。

上記の規則に加えて、NGSIv2 サーバ実装が与えられれば、それらのフィールド
または他のフィールドに構文上の制約を追加して、たとえばクロス・スクリプト・
インジェクション攻撃を回避することができます。

クライアントがシンタックスの観点から無効なフィールドを使用しようとすると、
クライアントは原因を説明する、"Bad Request" エラー・レスポンスを得ます。

## 属性名の制限 (Attribute names restrictions)

次の文字列を属性名として使用しないでください :

* `id`, エンティティ id を表すために使用されるフィールドと競合するためです。 

* `type`, エンティティ型を表すために使用されるフィールドと競合するためです。

* `geo:distance`, `orderBy` で中心点に接近するために使用される文字列と衝突するためです。

* 組み込み属性名 ("組み込み属性" の特定のセクションを参照)

* `*`, "すべてのカスタム/ユーザ属性" ("属性とメタデータのフィルタリング" を参照)
  という特別な意味を持っています。

## メタデータ名の制限 (Metadata names restrictions)

次の文字列をメタデータ名として使用しないでください :

* 組み込みメタデータ名 ("組み込みメタデータ" の特定のセクションを参照)

* `*`, "すべてのカスタム/ユーザ・メタデータ" ("属性とメタデータのフィルタリング"
  を参照) という特別な意味を持っています。

## 結果の順序付け (Ordering Results)

エンティティのリストを検索するオペレーションは、`orderBy` URI パラメータが、
結果を順序付けする際の基準として使用される属性またはプロパティを
指定することを可能にする。`orderBy` の値は次のようになります :

* "near" (`georel=near`) の空間関係が使用されているときにリファレンス・
  ジオメトリまでの距離によって結果を並べるキーワード `geo : distance`。

* カンマで区切られた属性のリストです。組み込み属性、エンティティ ID の `id`、
  エンティティ型の `type` などがあります。たとえば、`temperature,!humidity`。
  結果は最初のフィールドで並べられます。続いて、結果は2番目のフィールドなど
  の順序で並べられます。フィールド名の前の "!" は、順序が逆になっていること
  を示します。

## エラー・レスポンス (Error Responses)

エラー・ペイロードが存在する場合は、次のフィールドを含む JSON オブジェクトです :

+ `error` (必須, 文字列) : エラーのテキスト記述。
+ `description` (オプション, 文字列) : エラーに関する追加情報。

すべての NGSIv2 サーバの実装では、この節で説明する以下の HTTP ステータス・
コードと `error` テキストを使用する必要があります。 しかしながら、`description`
フィールドのために使用される特定のテキストは実装の固有側面です。

NGSIv2 の `error` レポートは次のとおりです :

+ 着信 JSON ペイロードがパースできない場合、`ParseError` (`400`) が返されます。
+ URL パラメータまたはペイロードのいずれかでリクエスト自体によってのみ発生する
  エラー (つまり、NGSIv2 サーバのステータスに依存しないエラー) は、
  `BadRequest`(`400`) となります。
  + 例外 : 受信した JSON ペイロード・エラー。これには別の `error` メッセージが
    あります (前の箇条書きを参照)。
+ 空間インデックスの制限を超過しようとすると、`NoResourceAvailable` (`413`) に
  なります。詳細は、"エンティティの地理空間プロパティ"を参照してください。
+ リクエストに起因する曖昧さは、いくつかのリソースを参照する可能性があります。
  その ID だけを提供するエンティティを更新しようとすると、その ID を持つ複数の
  エンティティが存在すると、`TooManyResults` (`409`) になります。
+ リクエストによって識別されるリソースが見つからない場合、`NotFound` (`404`)が
  返されます。
+ リクエストと状態の組み合わせに起因するものの、排他的ではないリクエスト
  (たとえば、既存の属性に対して `options=append` を指定した POST) は、
  `Unprocessable` (`422`) になります。
  + 例外 : 前の箇条書きで説明した 404, 409 または 413 のエラーにつながる
    リクエストと状態の条件。
+ HTTP 層のエラーは次のように使用されます : 
  + HTTP 405 Method Not Allowed は、`MethodNotAlowed` (`405`) に対応しています。
  + HTTP 411 Length Required は `ContentLengthRequired` (`411`) に対応します。
  + HTTP 413 Request Entity Too Large は、`RequestEntityTooLarge` (`413`) に対応します。
  + HTTP 415 Unsupported Media Type は `UnsupportedMediaType` (`415`) に対応します。

## エンティティの地理空間プロパティ (Geospatial properties of entities)

コンテキストのエンティティの地理空間的特性は、通常のコンテキスト属性を用いて
表すことができます。
地理空間的プロパティの提供は、地理的クエリの解決を可能にします。

準拠した実装では、2つの異なる構文をサポートする必要があります :

* *Simple Location Format*。これは、開発者とユーザが既存のエンティティに
  素早く簡単に追加できる、非常に軽量な形式です。

* *GeoJSON*。[GeoJSON](https://tools.ietf.org/html/draft-butler-geojson-06) は、
  JSON (JavaScript Object Notation) に基づく地理空間データ交換フォーマットです。
  GeoJSON は、より高度な柔軟性を提供し、ポイント高度またはより複雑な地理空間形状、
  たとえば、[マルチ・ジオメトリ](http://www.macwright.org/2015/03/23/geojson-second-bite.html#multi-geometries)の表現を可能にします。

クライアント・アプリケーションは、適切な NGSI 属性型を提供することによって、
どのエンティティ属性がジオスペース属性を伝えるかを定義します。通常、これは
`location` という名前のエンティティ属性ですが、エンティティが複数の地理空間
属性を含むユースケースを妨げるものはありません。たとえば、異なる粒度レベルで
指定された場所、または異なる精度で異なる場所の方法によって提供された場所。
それにもかかわらず、空間特性には、バックエンド・データベースによって課せられた
リソースの制約下にある特別なインデックスが必要であることに注目してください。
したがって、実装では、空間インデックスの制限を超えるとエラーが発生する可能性が
あります。これらの状況に推奨される HTTP ステータス・コードは、``413``,
*Request entity too large* で、レスポンス・ペイロードで報告されたエラーは、
``NoResourcesAvailable`` でなければなりません。

### シンプル・ロケーション・フォーマット (Simple Location Format)

シンプル・ロケーション・フォーマットは、基本的なジオメトリ
( *point*, *line*, *box*, *polygon* ) をサポートし、地理的位置をエンコードする
際の典型的な使用例をカバーしています。
[GeoRSS Simple](http://www.georss.org/simple.html) に触発されています。

シンプル・ロケーション・フォーマットは、地球表面上の複雑な位置を表すことを
意図していないことに注目してください。たとえば、高度座標を取得する必要の
あるアプリケーションでは、GeoJSON をそのエンティティの地理空間プロパティの
表現形式として使用する必要があります。

シンプル・ロケーション・フォーマットでエンコードされたロケーションを表す
コンテキスト属性は、次の構文に準拠している必要があります :

* 属性型は、(`geo:point`, `geo:line`, `geo:box`, `geo:polygon`)の
  いずれかの値でなければなりません。
* 属性値は座標のリストでなければなりません。既定では、座標は、[WGS84 Lat Long](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84),
  [EPSG::4326](http://www.opengis.net/def/crs/EPSG/0/4326) 座標リファレンス・システム (CRS)を
  使用して定義され、緯度と経度の単位は小数です。このような座標リストは、
  `type` 属性で指定されたジオメトリをエンコードすることを可能にし、
  以下で定義される特定の規則に従ってエンコードされます :

  * `geo:point` 型 : 属性値には有効な緯度経度のペアをカンマで区切った
    文字列を含める必要があります。
  * `geo:line` 型 : 属性値に有効な緯度経度ペアの文字列配列を含める
    必要があります。少なくとも2つのペアが必要です。
  * `geo:polygon` 型 : 属性値に有効な緯度経度ペアの文字列配列を
    含める必要があります。
    少なくとも4つのペアが存在しなければならず、最後のペアは最初のものと
    同一であるため、ポリゴンには最低 3つの実際のポイントがあります。
    ポリゴンを構成する線分が定義された領域の外縁に残るように、
    座標ペアを適切に順序付けする必要があります。
    たとえば、次のパス ```[0,0], [0,2], [2,0], [2, 2]``` は無効な
    ポリゴン定義の例です。入力データによって前者の条件が満たされて
    いない場合、実装でエラーが発生するはずです。 
  * `geo:box` 型 : バウンディング・ボックスは矩形領域であり、地図の範囲や
    関心のある大まかな領域を定義するためによく使用されます。ボックスは、
    緯度経度ペアの2つの長さの文字列配列によって表現されます。
    最初のペアは下のコーナー、2番目のペアは上のコーナーです。

注 : [文献](https://github.com/geojson/geojson-spec/wiki/Proposal---Circles-and-Ellipses-Geoms#discussion-notes)で、実装のさまざまな欠点を説明しているように、
サークル・ジオメトリはサポートされていません。

以下の例は、参照される構文を示しています :

```
{
  "location": {
    "value": "41.3763726, 2.186447514",
    "type": "geo:point"
  }
}
```

```
{
  "location": {
    "value": [
      "40.63913831188419, -8.653321266174316",
      "40.63881265804603, -8.653149604797363"
    ],
    "type": "geo:box"
  }
}
```

###  GeoJSON

GeoJSON を使用してエンコードされた位置を表すコンテキスト属性は、
次の構文に準拠している必要があります :

* 属性の NGSI 型は `geo:json` でなければなりません。
* 属性値は有効な GeoJSON オブジェクトである必要があります。
  GeoJSON の座標で経度が緯度の前に来ることに注目してください。

以下の例は、GeoJSON の使い方を示しています。
その他の GeoJSON の例は、[GeoJSON IETF 仕様書](https://tools.ietf.org/html/draft-butler-geojson-06#page-14)にあります。
さらに、[この GeoJSON チュートリアル](http://www.macwright.org/2015/03/23/geojson-second-bite.html)は、フォーマットの理解に役立ちます。

```
{
  "location": {
    "value": {
      "type": "Point",
      "coordinates": [2.186447514, 41.3763726]
    },
    "type": "geo:json"
  }
}
```

## シンプル・クエリ言語 (Simple Query Language)

シンプル・クエリ言語は、一連の条件に一致するエンティティを取得する
ための簡単な構文を提供します。クエリは、';' キャラクタで区切られた
ステートメントのリストで構成されます。各ステートメントは一致条件を表します。
クエリは、一致するすべての条件 (AND 論理演算子) に一致するすべての
エンティティを返します。

ステートメントには、2種類あります : *単項ステートメント* と *バイナリ・ステートメント*

バイナリ・ステートメントは、属性パス (たとえば、`temperature` や `brand.name`)、
演算子と値 (値の形式は演算子に依存します)、たとえば :

```
temperature==50
temperature<=20
```

属性パスの構文は、`.` 文字で区切られたトークンのリストで構成されます。
このトークンのリストは、次の規則に従って JSON プロパティ名を指定します。

* 最初のトークンは、エンティティの NGSI 属性 (*ターゲット NGSI 属性*) の名前です。
* 属性値によるフィルタリング (つまり、式が `q` クエリで使用されている) の場合、
  残りのトークン (存在する場合) は、JSON オブジェクトでなければならない、
  *ターゲット NGSI 属性*のサブ・プロパティへのパスを表します。
  そのようなサブプロパティは、*ターゲット・プロパティ*として定義されます。
* メタデータによるフィルタリング (つまり、式が `mq` クエリで使用されている) の場合、
  2番目のトークンはターゲットNGSI属性, *ターゲット・メタデータ*に
  関連付けられたメタデータ名を表し、残りのトークン (存在する場合) は
  JSON オブジェクトでなければならない *ターゲット・メタデータ値*の
  サブ・プロパティへのパスを表します。
  そのようなサブ・プロパティは、*ターゲット・プロパティ*として定義されます。

*ターゲット・プロパティ値*は、上記のトークンのリストによって指定される、
JSON プロパティの値、つまり、*ターゲット・プロパティ*の値として定義されます。

トークンが 1つだけ提供されている場合 (メタデータによるフィルタリングの場合は2つ)、
*ターゲット・プロパティ* は *ターゲット NGSI 属性* (またはメタデータで
フィルタリングする場合の *ターゲット・メタデータ*)と *ターゲット・プロパティ値*
は、*ターゲット NGSI 属性*値 (または、メタデータによるフィルタリングの場合の
*ターゲット・メタデータ*値) になります。この場合、*ターゲット NGSI 属性*
(または、メタデータによるフィルタリングの場合の*ターゲット・メタデータ*)
の値は JSON オブジェクトであってはなりません。

トークンの一部に `.` が含まれている場合、セパレータとして一重引用符 (`'`) を
使用できます。たとえば、次の属性パス `'a.b'.w.'x.y'` は3つのトークンで構成
されます : 最初のトークンは `ab`、2番目のトークンは `w`、3番目のトークンは `xy ` です。

演算子のリスト、および、使用する値の形式は次のとおりです :

+ **等号**: `==`. この演算子は、次の型の右辺を受け入れます :
    + 単一要素、たとえば `temperature == 40` です。エンティティがマッチするためには、
      *ターゲット・プロパティ* (temperature) が含まれていなければならず、
      *ターゲット・プロパティ値*は、クエリ値 (40) でなければなりません。
      または、*ターゲット・プロパティ値*が配列の場合はその値を含んでいなければ
      なりません。
    + カンマで区切られた値のリストです。たとえば、`color==black,red`。
      エンティティがマッチするためには、*ターゲット・プロパティ* が含まれて
      いなければならず、*ターゲット・プロパティ値*が、リスト内の値のうちの
      **いずれか**でなければなりません (OR 句) 。または、*ターゲット・プロパティ値*が
      配列の場合は、リスト内の値の**いずれか**を含んでいなければなりません。
      たとえば、`color` という名前の属性を持つエンティティは、その値が
      ` black`であるとマッチしますが、`color` という名前の属性を持つ
      エンティティは、その値が `white` であるとはマッチしません。
    + 範囲 (range)。最小値と最大値として指定され、`..` で区切られています。
      たとえば、`temperature==10..20` です。エンティティがマッチするためには、
      *ターゲット・プロパティ* (temperature) が含まれていなければならず、
      *ターゲット・プロパティ値*は、範囲の上限と下限の間 (どちらも含まれています)
      にある必要があります。範囲は、ISO8601 形式の日付、数字または文字列を表す
      *ターゲット・プロパティ*でのみ使用できます。
+ **不等号**: `!=`. この演算子は、次の型の右辺を受け入れます :
    + 単一の要素、たとえば `temperature!=41` です。エンティティが一致するには、
      *ターゲット・プロパティ* (temperature) が含まれていなければならず、
      *ターゲット・プロパティー値*は、クエリ値 (41) で**あってはなりません**。
    + カンマで区切られた値のリスト、たとえば `color!=black,red`。
      エンティティがマッチするには、*ターゲット・プロパティ* が含まれていなければならず、
      *ターゲット・プロパティ値*が、リスト内のいずれかの値で*あっては
      なりません* (AND 句)。または、*ターゲット・プロパティ値*が配列の場合、
      リスト内の値の**いずれか**を含んでいてはなりません。
      例えば。属性 `color` が `black` に設定されたエンティティはマッチせず、
      属性 `color` が `white` に設定されたエンティティはマッチします。
    + 範囲 (range)、最小値と最大値として指定され、`..` で区切られています。
      たとえば `temperature!=10..20`。エンティティがマッチするためには、
      *ターゲット・プロパティ* (temperature) が含まれていなければならず、
      *ターゲット・プロパティ値*は上限と下限の間 (どちらも含まれています) に
      ある**必要はありません**。範囲は、ISO8601 形式の日付、数字または文字列
      の日付を表す要素 *ターゲット・プロパティ*でのみ使用できます。
+ **より大きい**: `>`。右側は単一の要素でなければなりません。
    たとえば `temperature>42` です。エンティティがマッチするためには、
    *ターゲット・プロパティ* (temperature) が含まれていなければならず、
    *ターゲット・プロパティ値*がクエリ値 (42) より厳密に大きくなければなりません。
    このオペレーションは、date 型、number 型または string 型の
    *ターゲット・プロパティ*に対してのみ有効です (他の型の *ターゲット・プロパティ*で
    使用されると、予測できない結果になる可能性があります)。
+ **未満**: `<`。右側は単一の要素でなければなりません。
    たとえば、`temperature<43` です。エンティティがマッチするためには、
    *ターゲット・プロパティ* (temperature) が含まれていなければならず、
    *ターゲット・プロパティ値*は 値 (43) より厳密に小さくなければなりません。
    このオペレーションは、date 型、number 型または string 型の
    *ターゲット・プロパティ*に対してのみ有効です (他の型の *ターゲット・プロパティ*で
    使用されると、予測できない結果になる可能性があります)。
+ **以上**: `>=`。右側は単一の要素でなければなりません。
    たとえば、`temperature>=44` です。エンティティがマッチするためには、
    *ターゲット・プロパティ* (temperature)が含まれていなければならず、
    *ターゲット・プロパティ値*は 値 (44) 以上でなければなりません。
    このオペレーションは、date 型、number 型または string 型の
    *ターゲット・プロパティ*に対してのみ有効です (他の型の *ターゲット・プロパティ*で
    使用されると、予測できない結果になる可能性があります)。
+ **以下**: `<=`。右側は単一の要素でなければなりません。
    たとえば、`temperature<=45` です。エンティティがマッチするためには、
    *ターゲット・プロパティ* (temperature)が含まれていなければならず、
    *ターゲットプロパティ値*は、値 (45) 以下でなければなりません。
    このオペレーションは、date 型、number 型または string 型の
    *ターゲット・プロパティ*に対してのみ有効です (他の型の *ターゲット・プロパティ*で
    使用されると、予測できない結果になる可能性があります)。
+ **マッチ・パターン**: `~=`。値は正規表現として表現された、与えられたパターンと
    一致します。`color~=ow`。エンティティがマッチするためには、*targetプロパティ* 
    (color) が含まれていなければならず、*ターゲット・プロパティの値*が、
    右側の文字列と一致する必要があります。この例では `ow` (`brown` と `yellow` は
    マッチし、`black` と `white` はマッチしません) です。
    このオペレーションは、string 型の *ターゲット・プロパティ*に対してのみ有効です。

シンボル` : `は`==`の代わりに使用できます。

等号または不等号の場合、一致する文字列に `,` が含まれている場合は、カンマの特殊な
意味を無効にするために一重引用符 (`'`) を使用できます。たとえば、`color=='light,green','deep,blue'`。
最初の例は、正確な値  'light,green' または 'deep,blue' と color を一致させます。
また、`q=title=='20'` は文字列 "20" にマッチしますが、数値 20 ではマッチしません。

単項否定ステートメントは単項演算子 `!` を使用しますが、肯定単項ステートメントは
演算子をまったく使用しません。単項ステートメントは、*ターゲット・プロパティ*の
存在をチェックするために使用されます。
たとえば、`temperature` は、'temperature' という属性を持つエンティティにマッチします
(値に関係なく)。`!temperature` は、 'temperature' という属性を持たないエンティティ
と一致します。

## 地理的クエリ (Geographical Queries)

地理的クエリは、以下のパラメータを使用して指定されます。

``georel`` は、一致するエンティティとリファレンス・シェイプ (`geometry`) の間の
空間的関係 (述語) を指定することを意図しています。';' で区切られたトークンリストで
構成されています。最初のトークンはリレーションシップ名であり、残りのトークン (あれば) は
リレーションシップに関する詳細情報を提供する修飾語です。次の値が認識されます :

+ `georel=near`。``near`` リレーションシップは、一致するエンティティが、リファレンス・
  ジオメトリにある閾値距離に配置しなければならないことを意味します。これは次の修飾子を
  サポートしています :
  + `maxDistance`。一致するエンティティを配置する必要がある最大距離をメートルで表します。
  + `minDistance`。一致するエンティティを配置する必要がある最小距離をメートルで表します。
+ `georel=coveredBy`。一致するエンティティは、リファレンス・ジオメトリ内に完全に存在する
  エンティティであることを示します。
  このタイプのクエリを解決するときは、シェイプの境界線をシェイプの一部とみなす必要があります。 
+ `georel=intersects`。一致するエンティティはリファレンス・ジオメトリと交差する
  エンティティであることを示します。
+ `georel=equals`。一致するエンティティとリファレンス・ジオメトリの位置に関連付けられた
  ジオメトリは、まったく同じでなければなりません。
+ `georel=disjoint`。一致するエンティティは、リファレンス・参照ジオメトリと**交差しない**
  エンティティであることを示します。

`geometry` はクエリを解決する際に使われるリファレンス・シェイプを定義することを可能にします。
次のジオメトリ (シンプル・ロケーション・フォーマットを参照) をサポートする必要があります。

+ `geometry=point` は、地球表面上の点を定義します。
+ `geometry=line` は、折れ線を定義します。
+ `geometry=polygon` はポリゴンを定義します。
+ `geometry=box` は、バウンディング・ボックス (bounding box) を定義します。

**coords**は、指定されたジオメトリとシンプル・ロケーション・フォーマットで規定されている
規則に従って、セミコロンで区切られた地理座標のペアのリストを含む文字列でなければなりません :

* `geometry=point`。`coords` は、WGS-84 地理座標のペアを含んでいます。
* `geometry=line`。`coords` は、WGS-84 地理座標のペアのリストを含んでいます。
* `geometry=polygon`。`coords` は、少なくとも 4組の WGS-84 地理座標で構成されています。
* `geometry=box`。`coords` は、2組の WGS-84 地理座標で構成されています。

例 :

`georel=near;maxDistance:1000&geometry=point&coords=-40.4,-3.5`.
マッチング・エンティティは、基準点から 1,000メートル以内に配置する必要があります。

`georel=near;minDistance:5000&geometry=point&coords=-40.4,-3.5`.
マッチング・エンティティは、基準点から (少なくとも) 5,000メートル離れていなければなりません。

`georel=coveredBy&geometry=polygon&coords=25.774,-80.190;18.466,-66.118;32.321,-64.757;25.774,-80.190`
マッチング・エンティティは、参照されたポリゴン内にあるものです。

### クエリの解決 (Query Resolution)

実装が地理的なクエリを解決できない場合、レスポンスの HTTP ステータス・コードは
```422```, *Unprocessable Entity* でなければなりません。エラー・ペイロードに
存在するエラー名は、``NotSupportedQuery`` でなければなりません。

地理的クエリを解決する際には、シンプル・クエリ言語を介して、API 実装は、
マッチング目的で使用される地理的位置を含むエンティティ属性を決定する
責任があります。この目的のために、以下の規則を遵守しなければなりません。

* エンティティに、GeoJSON または、シンプル・ロケーション・フォーマットとして
  エンコードされた場所に対応する属性がない場合、そのようなエンティティは地理空間
  プロパティを宣言せず、地理的なクエリに一致しません。

* エンティティがロケーションに対応する1つの属性のみを公開する場合、
  そのような属性は地理的クエリを解決する際に使用されます。

* エンティティが複数のロケーションを公開している場合、ブーリン値が ``true`` の
  ``defaultLocation`` という名前のメタデータ・プロパティを含む属性は、
  地理的クエリを解決するためのリファレンス・ロケーションとして扱われます。

* 複数の属性が公開されているが、いずれもデフォルトのロケーションとしてラベル付け
  されていない場合、クエリはあいまいであると宣言され、``409`` コードの
  HTTP エラー・レスポンスが送られなければなりません。

* *default location* とラベル付けされた複数の属性公開ロケーションがある場合、
  クエリはあいまいであると宣言され、``409`` コードの  HTTP エラー・レスポンスが
  送られなければなりません。

## 属性とメタデータのフィルタリング (Filtering out attributes and metadata)

`attrs` URL パラメータ または、POST /v2/op/query のフィールド は、検索オペレーションで
レスポンスに含める必要のある属性のリストを指定するために使用できます。同様に、
`metadata` URL パラメータ または POST /v2/op/query のフィールドを使用して、
レスポンスに含める必要のあるメタデータのリストを指定することができます。

デフォルトでは、`attrs` が省略された場合、または `metadata` が省略された場合、
組み込み属性 (メタデータ) を除くすべての属性 (すべてのメタデータ) が含まれます。
組み込みの属性 (メタデータ) を含めるためには、それらを明示的に `attrs` (`metadata`)
に含める必要があります。

たとえば、属性 A と B のみを含めるには :

`attrs=A,B`

*only* 組み込み属性 (メタデータ) を含めると、ユーザ定義の属性 (メタデータ) は
使用できなくなります。組み込み属性 (メタデータ) *と* ユーザー定義属性(メタデータ)を
同時に組み込む場合、

* ユーザ定義属性 (メタデータ) を明示的に含める必要があります。例えば、
  ユーザ定義属性 A と B を組み込み属性 `dateModified` とともに含めるには、
  `attrs=dateModified,A,B` を使用します。
* 特別な値 `*` は、すべてのユーザ定義属性と組み込み属性 `dateModified` とともに
  含めるために、たとえば、"すべてのユーザ定義属性 (メタデータ)" を意味する
  エイリアスとして `attrs=dateModified,*` を使用できます。

`attrs` と `metadata` フィールドは `notification` のサブ・フィールドして、
サブスクリプションでも使用でき、サブスクリプションに関連する通知にどの
属性メタデータを含めるかを指定するのと同じ意味を持ちます。

## 通知メッセージ (Notification Messages)

通知には2つのフィールドがあります :

* `subscriptionId` は通知を発信した関連するサブスクリプションを表します。
* `data` はエンティティと関連するすべての属性を含む通知データそのものを
  持つ配列です。配列内の各要素は異なるエンティティに対応します。
  デフォルトでは、エンティティは `normalized` モードで表されます。
  しかし、`attrsFormat` 修飾子を使用すると、簡略化された表現モードを
  リクエストすることができます。

`attrsFormat` が `normalized` の場合、または `attrsFormat` が省略されている場合、
デフォルトのエンティティ表現が使用されます :

```
{
  "subscriptionId": "12345",
  "data": [
    {
      "id": "Room1",
      "type": "Room",
      "temperature": {
        "value": 23,
        "type": "Number",
        "metadata": {}
      },
      "humidity": {
        "value": 70,
        "type": "percentage",
        "metadata": {}
      }
    },
    {
      "id": "Room2",
      "type": "Room",
      "temperature": {
        "value": 24,
        "type": "Number",
        "metadata": {}
      }
    }
  ]
}
```

`attrsFormat` が `keyValues` の場合、keyValues の部分エンティティ表現モードが
使用されます :

```
{
  "subscriptionId": "12345",
  "data": [
    {
      "id": "Room1",
      "type": "Room",
      "temperature": 23,
      "humidity": 70
    },
    {
      "id": "Room2",
      "type": "Room",
      "temperature": 24
    }
  ]
}
```

`attrsFormat` が `values` の場合、values の部分エンティティ表現モードが
使用されます：

```
{
  "subscriptionId": "12345",
  "data": [ [23, 70], [24] ]
}
```

通知は、通知の受信者が通知ペイロードを処理する必要なくフォーマットを認識できるように、
関連するサブスクリプションのフォーマットの値を持つ `Ngsiv2-AttrsFormat` HTTP ヘッダを
含む必要があります。

## カスタム通知 (Custom Notifications)

NGSIv2 クライアントは、単純なテンプレート・メカニズムを使用して、HTTP 通知
メッセージをカスタマイズできます。サブスクリプションの `notification.httpCustom`
プロパティは、以下のフィールドをテンプレート化するよう指定します :

* `url`
* `headers` (ヘッダ名と値の両方をテンプレート化できます)
* `qs` (パラメータ名と値の両方をテンプレート化できます)
* `payload`

5番目のフィールド `method` では、NGSIv2 クライアントが通知の配信に使用する
HTTP メソッドを選択できますが、GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE,
 CONNECTなどの有効な HTTP 動詞しか使用できないことに注意してください。


テンプレートのマクロ置換は、構文 `${..}` に基づいています。特に :

* `${id}` は、エンティティの `id` に置き換えられます。
* `${type}` は、エンティティの `type` に置き換えられます。
* 他の `${token}` は、名前が `token` の属性の値に置き換えられます。属性が通知に
  含まれていない場合は空文字列に置き換えられます。値が数値、bool または null の場合、
  その文字列表現が使用されます。値が JSON 配列またはオブジェクトの場合、
  JSON 表現は文字列として使用されます。

例 :

与えられたサブスクリプションの次の `notification.httpCustom` オブジェクトを
考えてみましょう。

```
"httpCustom": {
  "url": "http://foo.com/entity/${id}",
  "headers": {
    "Content-Type": "text/plain"
  },
  "method": "PUT",
  "qs": {
    "type": "${type}"
  },
  "payload": "The temperature is ${temperature} degrees"
}
```

次に、このサブスクリプションに関連付けられた通知がトリガーされ、
id "DC_S1-D41" および 型 "Room" で、値が 23.4 の "temperature" という
属性を含むエンティティの通知データであると仮定します。テンプレートを
適用した結果の通知は次のようになります :

```
PUT http://foo.com/entity/DC_S1-D41?type=Room
Content-Type: text/plain
Content-Length: 31
The temperature is 23.4 degrees
```

いくつかの考慮事項 : 

* NGSIv2 クライアントは、置換後に通知が正しい HTTP メッセージであることを
  確認する責任があります。たとえば Content-Type ヘッダが application/xml の場合、
  ペイロードは 整形式 XML 文書に対応する必要があります。具体的には、テンプレート
  適用後の結果の URL の形式が誤っている場合、通知は送信されません。
* 通知するデータに複数のエンティティが含まれている場合は、エンティティごとに
  個別の通知 (HTTP メッセージ) が送信されます。デフォルトの動作とは異なり、
  すべてのエンティティが同じ HTTP メッセージで送信されます。

通知にカスタム・ペイロードが使用されている場合 (フィールド `payload` は
対応するサブスクリプションにあります)、通知の `Ngsiv2-AttrsFormat` ヘッダに
`custom` の値が使用されます。

## Group API Entry Point

### API リソースを取得 [GET /v2]

このリソースには、属性はありません。代わりに、JSON 本体のリンクの形で
初期 API アフォーダンス (initial API affordance) を提供します。

該当する場合は、"url" リンク値、[Link](https://tools.ietf.org/html/rfc5988)
または Location ヘッダに従うことをお勧めします。独自の URL を構築する代わりに、
クライアントと実装の詳細を切り離してください。


+ Response 200 (application/json)

    + Attributes (object)
        + entities_url: /v2/entities (required, string) - エンティティ・リソースを指す URL
        + types_url: /v2/types (required, string) - 型リソースを指す URL
        + subscriptions_url: /v2/subscriptions (required, string) - サブスクリプション・
          リソースを指す URL
        + registrations_url: /v2/registrations (required, string) - レジストレーション・
          リソースを指す URL

# Group Entities

### エンティティをリスト [GET /v2/entities{?limit,offset,options,type,id,idPattern,typePattern,q,mq,georel,geometry,coords,attrs,metadata,orderBy}]

id、型、パターン・マッチング (id または型)、またはクエリまたは地理的クエリ
([シンプル・クエリ・ランゲージ](#simple_query_language) および [地理的クエリ](#geographical_queries))で、
一致するエンティティのリストを取得します。与えられたエンティティは、検索される
すべての基準に一致しなければなりません。すなわち、基準が論理的 AND 方法で結合されます。
そのパターン・マッチング・クエリ・パラメータは、それらに対応する正確なマッチング・
パラメータと互換性がない (すなわち、相互に排他的である) ことに留意してください。
すなわち、`id` の `idPattern` および `type` の `typePattern` 

レスポンス・ペイロードは、一致するエンティティごとに1つのオブジェクトを含む配列です。
各エンティティは、"JSON エンティティの表現" で説明した JSON エンティティの表現形式に従います。

レスポンス・コード :

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものと、エラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + id: Boe_Idearium (optional, string) - カンマで区切られた要素のリスト。
      ID がリスト内のいずれかの要素とマッチするエンティティを取得します。
      `idPattern` と互換性がありません。
    
    + type: Room (optional, string) -  カンマで区切られた要素のリスト。
      リスト内の要素の1つに型がマッチするエンティティを取得します。
      `typePattern` と互換性がありません。

    + idPattern: Bode_.* (optional, string) - 正式な正規表現です。
      ID が正規表現とマッチするエンティティを取得します。
      `id` と互換性がありません。

    + typePattern: Room_.* (optional, string) - 正式な正規表現です。
      型が正規表現とマッチするエンティティを取得します。
      `type`と互換性がありません。
    
    + q: temperature>40 (optional, string) - クエリ式です。`;` で
      区切られたステートメントのリストで構成されます。
      つまり、q=statement1;statement2;statement3 です。
      [シンプル・クエリ・ランゲージ](#simple_query_language)を
      参照してください。

    + mq: temperature.accuracy<0.9 (optional, string) - 属性メタデータ
      のクエリ式です。`;` で区切られたステートメントのリストで構成されます。
      つまり、mq=statement1;statement2;statement3 です。
      [シンプル・クエリ・ランゲージ](#simple_query_language)を
      参照してください。
    
    + georel: near (optional, string) - マッチングするエンティティと
      リファレンス・シェイプとの空間的関係。
      [地理的クエリ](#geographical_queries)を参照してください。

    + geometry: point (optional, string) - クエリが制限される地理的領域。
      [地理的クエリ](#geographical_queries)を参照してください。
    
    + coords: 41.390205,2.154007;48.8566,2.3522 (optional, string) - ';' で
      区切られた座標の緯度経度のペアのリスト。
      [地理的クエリ](#geographical_queries)を参照してください。
    
    + limit: 20 (optional, number) - 取得するエンティティの数を制限します。
    
    + offset: 20 (optional, number) - エンティティの取得元からのオフセットを
      設定します。
    
    + attrs: seatNumber (optional, string) - データをレスポンスに含める
      属性名のカンマ区切りのリスト。属性は、このパラメータで指定された
      順序で取得されます。このパラメータが含まれていない場合、属性は任意の
      順序で取得されます。詳細については、"属性とメタデータのフィルタリング"
      を参照してください。

    + metadata: accuracy (optional, string) - レスポンスに含めるメタデータ名のリスト。
      詳細については、"属性とメタデータのフィルタリング" を参照してください。

    + orderBy: temperature,!speed (optional, string) - 結果の順序付けの基準。
      詳細については、"結果の順序付け" を参照してください。
    
    + options (optional, string) - オプション辞書
      + Members
          + count - 使用された場合、エンティティの総数は `Fiware-Total-Count`
            という名前の HTTP ヘッダとして返されます。
          + keyValues - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + values - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + unique - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。反復値は除外されます。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Response 200 (application/json)

        [
         {
           "type": "Room",
           "id": "DC_S1-D41",
           "temperature": {
             "value": 35.6,
             "type": "Number",
             "metadata": {}
           }
         },
         {
           "type": "Room",
           "id": "Boe-Idearium",
           "temperature": {
             "value": 22.5,
             "type": "Number",
             "metadata": {}
           }
         },
         {
           "type": "Car",
           "id": "P-9873-K",
           "speed": {
             "value": 100,
             "type": "number",
             "metadata": {
               "accuracy": {
                 "value": 2,
                 "type": "Number"
               },
               "timestamp": {
                 "value": "2015-06-04T07:20:27.378Z",
                 "type": "DateTime"
               }
             }
           }
         }
        ]

### エンティティを作成  [POST /v2/entities{?options}]

ペイロードは、作成されるエンティティを表すオブジェクトです。オブジェクトは、
"JSON エンティティ表現" のセクションで説明している、JSON エンティティ表現形式
に従います。

レスポンス : 

* 成功したオペレーションでは、201 Created (upsert オプションが使用されない場合)
  または、204 no Content (upsert オプションが使用される場合) を使用します。
  レスポンスには、作成されたエンティティの URL を含む `Location` ヘッダが含まれます。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Request (application/json)

        {
          "type": "Room",
          "id": "Bcn-Welt",
          "temperature": {
            "value": 21.7
          },
          "humidity": {
            "value": 60
          },
          "location": {
            "value": "41.3763726, 2.1864475",
            "type": "geo:point",
            "metadata": {
              "crs": {
                "value": "WGS84"
              }
            }
          }
        }

+ Parameters
    + options (optional, string) - オプション辞書
      + Members
          + keyValues - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + upsert - 使用されると、エンティティはすでに存在する場合に更新されます。
            upsert が使用されておらず、エンティティがすでに存在する場合、
            `422 Unprocessable Entity` エラーが返されます。

+ Response 201

    + Headers

            Location: /v2/entities/Bcn-Welt?type=Room

+ Response 204

    + Headers

            Location: /v2/entities/Bcn-Welt?type=Room

## ID によるエンティティ  [/v2/entities/{entityId}{?type,attrs,options}]

### エンティティを取得 [GET /v2/entities/{entityId}{?type,attrs,metadata,options}]

レスポンスは、ID で識別されるエンティティを表すオブジェクトです。オブジェクトは、
JSON エンティティ表現形式 ("JSON エンティティ表現"のセクションを参照) に従います。

このオペレーションは、1つのエンティティ要素のみを返す必要がありますが、同じ ID を
持つエンティティが複数存在する可能性があります。このような場合、HTTP ステータス・
コードが 409 Conflict に設定されたエラー・メッセージが返されます。

レスポンス :

* 成功したオペレーションでは、200 OK を使用します
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId (required, string) - 取得するエンティティの ID
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrs: temperature,humidity (optional, string) - データをレスポンスに含める
      必要がある属性名のカンマ区切りのリスト。属性は、このパラメータで指定された
      順序で取得されます。詳細については、"属性とメタデータのフィルタリング" を
      参照してください。このパラメータが含まれていない場合、属性は任意の順序で
      取得され、エンティティのすべての属性がレスポンスに含まれます。
    + options (optional, string) - レスポンスに含めるメタデータ名のリスト。
      詳細については、"属性とメタデータのフィルタリング" を参照してください。
    + options (optional, string) - オプション辞書
      + Members
          + keyValues - 使用されると、レスポンス・ペイロードは、単純された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + values - 使用されると、レスポンス・ペイロードは、単純された
            エンティティ表現 `values` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + unique - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。反復値は除外されます。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Response 200 (application/json)

        {
          "type": "Room",
          "id": "Bcn_Welt",
          "temperature": {
            "value": 21.7,
            "type": "Number"
          },
          "humidity": {
            "value": 60,
            "type": "Number"
          },
          "location": {
            "value": "41.3763726, 2.1864475",
            "type": "geo:point",
            "metadata": {
              "crs": {
                "value": "WGS84",
                "type": "Text"
              }
            }
          }
        }

### エンティティ属性を取得 [GET /v2/entities/{entityId}/attrs{?type,attrs,metadata,options}]

このリクエストは、エンティティ全体を取得するのと同様ですが、
これは `id` と `type` フィールドを省略しています。

エンティティ全体を取得する一般的なリクエストと同様に、このオペレーション
ではエンティティ要素を 1つだけ返す必要があります。同じ ID を持つ複数の
エンティティ (たとえば ID は同じで型が異なるエンティティ) が見つかると、
HTTP ステータス・コードが 409 Conflict に設定されたエラー・メッセージが返されます。

レスポンス : 

* 成功したオペレーションでは、200 OK を使用します
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId (required, string) - 取得するエンティティの ID。
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrs: temperature,humidity (optional, string) - レスポンスにデータを
      含める属性名のカンマ区切りのリスト。属性は、このパラメータで指定された
      順序で取得されます。このパラメータが含まれていない場合、属性は任意の順序で
      取得され、エンティティのすべての属性がレスポンスに含まれます。
      詳細については、"属性とメタデータのフィルタリング" を参照してください。
    + metadata: accuracy (optional, string) - レスポンスに含めるメタデータ名の
      リスト。詳細については、"属性とメタデータのフィルタリング" を参照してください。
    + options (optional, string) - オプション辞書
      + Members
          + keyValues - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + values - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + unique - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。反復値は除外されます。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Response 200 (application/json)

        {
          "temperature": {
            "value": 21.7,
            "type": "Number"
          },
          "humidity": {
            "value": 60,
            "type": "Number"
          },
          "location": {
            "value": "41.3763726, 2.1864475",
            "type": "geo:point",
            "metadata": {
              "crs": {
                "value": "WGS84",
                "type": "Text"
              }
            }
          }
        }

### エンティティ属性の更新または追加 [POST /v2/entities/{entityId}/attrs{?type,options}]

リクエスト・ペイロードは、追加または更新する属性を表すオブジェクトです。
オブジェクトは、`id` と `type ` が許可されていないことを除いて、JSON エンティティの
表現形式 ("JSON エンティティ表現" のセクションを参照) に従います。

エンティティ属性は、`append` オペレーションのオプションが使用されているか
どうかに応じて、ペイロード内の属性で更新されます。

* `append` が使用されていない場合、エンティティ属性は更新され (以前に存在する場合)、
  ペイロードに追加されます (存在しない場合)。
* `append` が使用されている場合 (つまり、厳密なアペンド・セマンティクス)、
  ペイロード内の、エンティティ内に以前に存在しなかったすべての属性が追加されます。
  それに加えて、ペイロード内の属性の一部がすでにエンティティに存在する場合、
  エラーが返されます。

レスポンス :

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId (required, string) - 更新されるエンティティ ID。
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + options (optional, string) - オペレーションのオプション
        + Members
            + append - 追加オペレーションを強制します
            + keyValues - 使用されると、リクエスト・ペイロードは、単純化された
              エンティティ表現 `keyValues` を使用します。
              詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Request (application/json)

    + Body

            {
              "ambientNoise": {
                "value": 31.5
              }
            }

+ Response 204

### 既存のエンティティ属性の更新 [PATCH /v2/entities/{entityId}/attrs{?type,options}]

リクエスト・ペイロードは、更新する属性を表すオブジェクトです。オブジェクトは、
`id` および `type` が許可されていないことを除いて、JSON エンティティの表現形式
("JSON エンティティの表現" のセクションを参照) に従います。

エンティティ属性は、ペイロード内の属性で更新されます。それに加えて、ペイロード内の
1つ以上の属性がエンティティに存在しない場合、エラーが返されます。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters 
    + entityId (required, string) - 更新されるエンティティの ID。
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + options (optional, string) - オペレーションのオプション
        + Members
            + keyValues - 使用されると、リクエスト・ペイロードは、単純化された
              エンティティ表現 `keyValues` を使用します。
              詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Request (application/json)

        {
          "temperature": {
            "value": 25.5
          },
          "seatNumber": {
            "value": 6
          }
        }

+ Response 204

### すべてのエンティティ属性を置換 [PUT /v2/entities/{entityId}/attrs{?type,options}]

リクエスト・ペイロードは、新しいエンティティ属性を表すオブジェクトです。
オブジェクトは、上記の "JSON エンティティ表現" で説明した JSON エンティティ表現形式に
従いますが、`id` および `type` は許されません。

エンティティ内に以前に存在していた属性は削除され、リクエスト内の属性に
置き換えられます。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters 
    + entityId (required, string) - 問題のエンティティの ID です。
    + type (optional, string) - 同じエンティティIDを持つ複数のエンティティがある場合の
    あいまいさを避けるためのエンティティ型。
    + options (optional, string) - オペレーションのオプション
        + Members
            + keyValues - 使用されると、リクエスト・ペイロードは、
              単純化されたエンティティ表現 `keyValues` を使用します。
              詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Request (application/json)

        {
          "temperature": {
            "value": 25.5
          },
          "seatNumber": {
            "value": 6
          }
        }

+ Response 204

### エンティティを削除する [DELETE /v2/entities/{entityId}{?type}]

エンティティを削除します。

レスポンス :

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters 
    + entityId (required, string) - 削除するエンティティの ID
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。

+ Response 204


# Group Attributes

## エンティティ ID による属性 [/v2/entities/{entityId}/attrs/{attrName}{?type}]

### 属性データを取得 [GET /v2/entities/{entityId}/attrs/{attrName}{?type,metadata}]

属性 (Attributes) の属性データを含む JSON オブジェクトを返します。このオブジェクトは、
JSON 表現に従います ("JSON 属性表現" のセクションを参照)。

レスポンス : 

* 正常なオペレーションには、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId: Bcn_Welt (required, string) - エンティティの ID
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrName: temperature (required, string) - 取得する属性の名前。
    + attrName: temperature (required, string) - レスポンスに含めるメタデータ名の
      リスト。詳細については、"属性とメタデータのフィルタリング" を参照してください。

+ Response 200 (application/json)

        {
          "value": 21.7,
          "type": "Number",
          "metadata": {}
        }

### 属性データを更新 [PUT /v2/entities/{entityId}/attrs/{attrName}{?type}]

リクエスト・ペイロードは、新しい属性データを表すオブジェクトです。
以前の属性データは、リクエスト内の属性データに置き換えられます。
このオブジェクトは、JSON 表現に従います ("JSON属性表現" のセクションを参照)。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId: Bcn_Welt (required, string) - 更新するエンティティの ID
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrName: temperature (required, string) - 属性名。

+ Request (application/json)

        {
          "value": 25.0,
          "metadata": {
            "unitCode": {
              "value": "CEL"
            }
          }
        }

+ Response 200


### 単一の属性を削除 [DELETE /v2/entities/{entityId}/attrs/{attrName}{?type}]

エンティティ属性を削除します。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId: Bcn_Welt (required, string) - エンティティの ID。
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrName: temperature (required, string) - 属性名。

+ Response 204

# Group Attribute Value

## エンティティ ID 別 [/v2/entities/{entityId}/attrs/{attrName}/value?{type}]

### 属性値を取得 [GET /v2/entities/{entityId}/attrs/{attrName}/value{?type}]

このオペレーションは属性の値  (Attribute Value) を持つ `value` プロパティを返します。

* 属性値が JSON 配列、またはオブジェクトの場合 : 
  * `Accept` ヘッダを `application/json` または `text/plain` に展開できる場合は、
    その値を application/json または text/plain のレスポンス・タイプの JSON として
    返します。`Accept: */*` の場合は、`Accept` ヘッダの最初のものか、
    `application/json` のどちらかです。
  * その他のエラーは HTTP エラー
    "406 Not Acceptable: accepted MIME types: application/json, text/plain" を
    返します。
* 属性値が文字列、数値、ヌルまたはブール値の場合 :
  * `Accept` ヘッダを text/plain に展開できる場合は、値をテキストとして返します。
    文字列の場合、最初と最後に引用符が使用されます。
  * その他の場合、HTTP エラー "406 Not Acceptable: accepted MIME types: text/plain" を
    返します。

レスポンス : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId: Bcn_Welt (required, string) - 問題のエンティティの ID
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrName: address (required, string) - 取得する属性の名前。

+ Response 200 (application/json)

        {
          "address": "Ronda de la Comunicacion s/n",
          "zipCode": 28050,
          "city": "Madrid",
          "country": "Spain"
        }

### 属性値を更新 [PUT /v2/entities/{entityId}/attrs/{attrName}/value{?type}]

リクエスト・ペイロードは新しい属性値です。

* リクエストのペイロード MIME 型が `application/json` の場合、属性の値は
  ペイロードにコード化された JSON オブジェクト、または配列に設定されます。
  ペイロードが有効な JSON ドキュメントでない場合はエラーが返されます。
* リクエストのペイロード MIME 型が `text/plain` の場合、ペイロードには
  以下のアルゴリズムが適用されます。
  * ペイロードが引用符 (`"`) で始まり、終了すると、その値は文字列として
    扱われます。引用符自体は文字列の一部と見なされません。
  * `true` か` false` の場合は、値がブール値とみなされます。
  * `null` の場合は、値がヌルとみなされます。
  * これらの最初の 3つのテストが失敗すると、テキストは数字として解釈されます。
  * 有効な数値でない場合、エラーが返され、属性の値は変更されません。

リクエストのペイロード MIME 型は `Content-Type` HTTP ヘッダで指定されます。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityId: Bcn_Welt (required, string) - 更新されるエンティティの ID です。
    + type (optional, string) - 同じエンティティ ID を持つ複数のエンティティが
      ある場合のあいまいさを避けるためのエンティティ型。
    + attrName: address (required, string) - 属性名。

+ Request (application/json)

        {
          "address": "Ronda de la Comunicacion s/n",
          "zipCode": 28050,
          "city": "Madrid",
          "country": "Spain"
        }

+ Response 200

# Group Types

## 全エンティティ型 [/v2/types{?limit,offset,options}]

### 全エンティティ型のリスト [GET /v2/types/{?limit,offset,options}]

`values` オプションが使用されていない場合、このオペレーションは 全ての
エンティティ型 (Entity types) を持つ JSON 配列を返します。各要素は、型に関する情報を
持つ JSON オブジェクトです。

* `type` : エンティティ型名。
* `attrs` : 属性名とその型のすべてのエンティティの集合。属性名をキーとする値を
   持つ JSON オブジェクトで表現されます。その値にはそのような属性の情報が
   含まれます。特に、属性で使用される型のリストその名前とすべてのエンティティ。
* `count` : その型に属するエンティティの数。

`values` オプションが使用されている場合、オペレーションはエンティティ型名の
リストを文字列として持つ JSON 配列を返します。

結果はアルファベット順にエンティティ `type` によって順序付けられます。

レスポンス・コード : 

* 成功したオペレーションでは、200 OK を使用します
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + limit: 10 (optional, number) - 検索する型の数を制限します。
    + offset: 20 (optional, number) - いくつかのレコードをスキップします。
    + options (optional, string) - オプション辞書。
      + Members
          + count - 使用すると、型の総数が HTTP ヘッダ `Fiware-Total-Count` に
            返されます
          + values - 使用すると、レスポンス・ペイロードは、エンティティ型の
            リストを含む JSON 配列です。

+ Response 200 (application/json)

        [
          {
            "type": "Car",
            "attrs": {
              "speed": {
                "types": [ "Number" ]
              },
              "fuel": {
                "types": [ "gasoline", "diesel" ]
              },
              "temperature": {
                "types": [ "urn:phenomenum:temperature" ]
              }
            },
            "count": 12
          },
          {
            "type": "Room",
            "attrs": {
              "pressure": {
                "types": [ "Number" ]
              },
              "humidity": {
                "types": [ "percentage" ]
              },
              "temperature": {
                "types": [ "urn:phenomenum:temperature" ]
              }
            },
            "count": 7
          }
        ]

## エンティティ型 [/v2/types/{entityType}]

### エンティティ型を取得 [GET /v2/types/{entityType}]

このオペレーションは、型 (Entity type) に関する情報を含む JSON オブジェクトを返します :

* `attrs` : 属性名とその型のすべてのエンティティの集合。属性名をキーとする値を
  持つ JSON オブジェクトで表現されます。その値にはそのような属性の情報が
  含まれます。特に、属性で使用される型のリストその名前とすべてのエンティティです。
* `count` : その型に属するエンティティの数。

レスポンス・コード : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + entityType: Room (required, string) - エンティティ型

+ Response 200 (application/json)

          {
            "attrs": {
              "pressure": {
                "types": [ "Number" ]
              },
              "humidity": {
                "types": [ "percentage" ]
              },
              "temperature": {
                "types": [ "urn:phenomenum:temperature" ]
              }
            },
            "count": 7
          }

# Group Subscriptions

サブスクリプション (Subscriptions) は、次のフィールドを持つ JSON オブジェクトで表されます :

+ `id`: サブスクリプション固有の識別子。作成時に自動的に作成されます。
+ `description` (optional): サブスクリプションを記述するためにクライアントが
  使用するフリー・テキストです。
+ `subject`: サブスクリプションのサブジェクトを記述するオブジェクト。
+ `notification`: サブスクリプションがトリガされたときに送信する通知を
  記述するオブジェクト。
+ `expires`: ISO8601 形式のサブスクリプション有効期限。恒久サブスクリプションでは、
  このフィールドを省略する必要があります。
+ `status`: `active` (アクティブなサブスクリプションの場合) または `inactive`
  (非アクティブなサブスクリプションの場合) のいずれか。このフィールドが
  サブスクリプション作成時に提供されない場合、新しいサブスクリプションは 
  `active` ステータスで作成されます。これは後でクライアントによって変更される
  可能性があります。 期限切れのサブスクリプションの場合、この属性は、クライアントが
  `active`/`inactive` に更新しても、`expired` に設定されます。また、通知に問題が
  発生したサブスクリプションの場合、ステータスは `failed` に設定されます。
  通知が再び機能し始めると、状態は `active` に戻されます。
+ `throttling`: 2つの連続した通知の間に経過しなければならない最小時間(秒)。
  オプションです。

`subject` には、以下のサブフィールドが含まれています :

+ `entities`: オブジェクトのリスト。各オブジェクトは以下のサブフィールドで
  構成されています : 
  + `id` または `idPattern`: 影響を受けるエンティティの ID またはパターン。
    両方を同時に使用することはできませんが、そのうちの1つが存在する必要があります。
  + `type` または `typePattern`: 影響を受けるエンティティの型または型パターン。
    両方を同時に使用することはできません。
    これを省略すると、"任意のエンティティ型" を意味します。
+ `condition`: 通知をトリガーする条件。このフィールドはオプションで、
  2つのプロパティを含むことができ、両方ともオプションです。
    + `attrs`: 属性名の配列
    + `expression`: `q`、`mq`、`georel`、`geometry`, `coords` で構成される式です。
      上記の "エンティティをリスト" オペレーションを参照してください。

`notification` オブジェクトには、以下のサブフィールドが含まれています :

+ `attrs` または `exceptAttrs` (どちらも同時に使用できません) :
  + `attrs`: 通知メッセージに含める属性のリスト。また、`attrsFormat` `value` が
    使われたときに、属性に通知が現れる順序を定義します ("通知メッセージ" を参照)。
    空のリストは、すべての属性が通知に含まれることを意味します。詳細については、
    "属性とメタデータのフィルタリング" を参照してください。
  + `exceptAttrs`: 通知メッセージから除外される属性のリスト。すなわち、
    通知メッセージには、このフィールドにリストされているものを除くすべての
    エンティティ属性が含まれます。
  + `attrs` も `exceptAttrs` も指定されていなければ、全ての属性が通知に含まれます。
+ `http` or `httpCustom` (それらのうちの1つが存在しなければなりませんが、
  同時に両方は存在しません) : HTTP プロトコルを通して渡される通知のための
  パラメータを伝えるために使われます。
+ `attrsFormat` (optional): エンティティが通知でどのように表現されるかを指定します。
  受け入れられる値は `normalized` (デフォルト)、`keyValues` または `values` です。
  `attrsFormat` がそれらと異なる値をとると、エラーが発生します。
  "通知メッセージ" のセクションを参照してください。
+ `metadata` (optional): 通知メッセージに含めるメタデータのリスト。詳細については、
  "属性とメタデータのフィルタリング" を参照してください。
+ `timesSent` (編集不可、GET オペレーションのみ) : このサブスクリプションのために
  送信された通知の数です。
+ `lastNotification` (編集不可、GET オペレーションのみ) : ISO8601形式の最後の
  通知タイムスタンプ。
+ `lastFailure` (編集不可、GETオペレーションのみ) : ISO8601 形式の最後の
  失敗タイムスタンプ。サブスクリプションが通知に問題がない場合は存在しません。
+ `lastSuccess` (編集不可、GETオペレーションのみ) : 最後に成功した通知のための
  ISO8601 形式のタイムスタンプ。サブスクリプションが正常に通知されなかった場合
  には存在しません。

`http` オブジェクトには、以下のサブフィールドが含まれています :

+ `url` : 通知が生成されたときに呼び出されるサービスを参照するURL。
  NGSIv2 準拠のサーバは `http` URL スキーマをサポートしなければなりません。
  他のスキーマをサポートすることもできます。

`httpCustom` オブジェクトには以下のサブフィールドが含まれています。

+ `url`: 上記の` http` と同じです。
+ `headers` (optional): 通知メッセージに含まれる HTTP ヘッダのキー・マップ。
+ `qs` (optional): 通知メッセージに含まれる URL クエリ・パラメータのキー・マップ。
+ `method` (optional): 通知を送るときに使うメソッドです。デフォルトは POST です。
  有効な HTTP メソッドのみが許可されます。無効な HTTP メソッドを指定すると、
  400 Bad Request エラーが返されます。
+ `payload` (optional): 通知に使用されるペイロード。省略した場合、デフォルトの
  ペイロード ("通知メッセージ" を参照) が使用されます。

`httpCustom` が使用されている場合は、"カスタム通知" セクションで説明している
考慮事項が適用されます。

通知ルールは次のとおりです :

* `attrs` と `expression` が使用されている場合、`attrs` リスト内の属性の1つが
  変更され、同時に `expression` が一致するたびに通知が送られます。
* `attrs` が使用され、`expression` が使用されない場合、`attrs` リスト内の
  いずれかの属性が変化するたびに通知が送られます。
* `attrs` が使用されておらず、`expression` が使われている場合、エンティティの
  属性のいずれかが変更され、同時に `expression` が一致すると通知が送られます。
* `attrs` と `expression` のどちらも使わない場合は、エンティティの属性の
  いずれかが変更されるたびに通知が送られます。

## サブスクリプション・リスト [/v2/subscriptions]

### サブスクリプションをリスト [GET /v2/subscriptions{?limit,offset,options}]

システムに存在するすべてのサブスクリプションのリストを返します :

レスポンス : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + limit: 10 (optional, number) - 取得するサブスクリプション数を制限します。
    + offset: 20 (optional, number) - スキップするサブスクリプション数です。
    + options (optional, string) - オプション辞書
      + Members
          + count - 使用すると、サブスクリプションの総数は、
            HTTP ヘッダ `Fiware-Total-Count` に返されます

+ Response 200

        [
          {
            "id": "abcdefg",
            "description": "One subscription to rule them all",
            "subject": {                    
              "entities": [
                {
                  "id": "Bcn_Welt",
                  "type": "Room"
                }
              ],
              "condition": {
                 "attrs": [ "temperature " ],
                 "expression": {
                    "q": "temperature>40"
                 }
              }
            },
            "notification": {
              "httpCustom": {
                "url": "http://localhost:1234",
                "headers": {
                  "X-MyHeader": "foo"
                },
                "qs": {
                  "authToken": "bar"
                }
              },
              "attrsFormat": "keyValues",
              "attrs": ["temperature", "humidity"],
              "timesSent": 12,
              "lastNotification": "2015-10-05T16:00:00.00Z",
              "lastFailure": "2015-10-06T16:00:00.00Z"
            },
            "expires": "2016-04-05T14:00:00.00Z",
            "status": "failed",
            "throttling": 5
          }
        ]

### サブスクリプションを作成 [POST /v2/subscriptions]

新しいサブスクリプションを作成します。
サブスクリプションは、このセクションの冒頭で説明した JSON オブジェクトで表されます。

レスポンス : 

* 成功したオペレーションでは、201 Created を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Request (application/json)

        {
          "description": "One subscription to rule them all",
          "subject": {
            "entities": [
              {
                "idPattern": ".*",
                "type": "Room"
              }
            ],
            "condition": {
              "attrs": [ "temperature" ],
              "expression": {
                "q": "temperature>40"
              }
            }
          },
          "notification": {
            "http": {
              "url": "http://localhost:1234"
            },
            "attrs": ["temperature", "humidity"]
          },            
          "expires": "2016-04-05T14:00:00.00Z",
          "throttling": 5
        }

+ Response 201

    + Headers

            Location: /v2/subscriptions/abcde98765


## ID によるサブスクリプション [/v2/subscriptions/{subscriptionId}]

### サブスクリプションを取得 [GET /v2/subscriptions/{subscriptionId}]

レスポンスは、このセクションの冒頭で説明した JSON オブジェクトによって
表されるサブスクリプションです。

レスポンス : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + subscriptionId: abcdef (required, string) - サブスクリプションID。

+ Response 200 (application/json)

        {
          "id": "abcdef",
          "description": "One subscription to rule them all",
          "subject": {
            "entities": [
              {
                "idPattern": ".*",
                "type": "Room"
              }
            ],
            "condition": {
              "attrs": [ "temperature " ],
              "expression": {
                "q": "temperature>40"
              }
            }
          },
          "notification": {
            "http": {
              "url": "http://localhost:1234"
            },
            "attrs": ["temperature", "humidity"],
            "timesSent": 12,
            "lastNotification": "2015-10-05T16:00:00.00Z"
            "lastSuccess": "2015-10-05T16:00:00.00Z"
          },
          "expires": "2016-04-05T14:00:00.00Z",
          "status": "active",
          "throttling": 5
        }

### サブスクリプションを更新 [PATCH /v2/subscriptions/{subscriptionId}]

サブスクリプションでは、リクエストに含まれるフィールドのみが更新されます。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + subscriptionId: abcdef (required, string) - サブスクリプション ID。

+ Request (application/json)

        {
          "expires": "2016-04-05T14:00:00.00Z"
        }

+ Response 204


### サブスクリプションを削除 [DELETE /v2/subscriptions/{subscriptionId}]

サブスクリプションをキャンセルします。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + subscriptionId: abcdef (required, string) - サブスクリプション ID。

+ Response 204

# Group Registrations

コンテキストのレジストレーション (Registrations) は、特定の地理的領域に位置するものを含む
コンテキスト情報空間の特定のサブセット (エンティティ、属性) のプロバイダの役割を
果たすことができるように、外部コンテキスト情報ソースをバインドすることを可能にします。

NGSIv2 サーバ実装は、コンテキスト情報源へのクエリおよび/または更新転送を
実装することができます。特に、以下の転送メカニズムの一部を実装することができます。
完全なリストではありません。

* レガシー転送 (NGSIv1 オペレーションに基づく)
* NGSI コンテキスト・ソースの転送仕様

詳細を知るには、対応する仕様を確認してください。

コンテキストのレジストレーションは、次のフィールドを持つ JSON オブジェクトで
表されます。

+ `id` : レジストレーションに割り当てられた一意の識別子。作成時に自動的に生成されます。
+ `description` : このレジストレーションに与えられた説明です。オプション。
+ `provider` : レジストレーションされたコンテキスト・ソースを記述するオブジェクト。必須。
+ `dataProvided` : このソースによって提供されるデータを記述するオブジェクトです。必須。
+ `status`: このレジストレーションの現在の状態を捕捉する列挙されたフィールド :
`active` (アクティブなレジストレーションの場合) または、
`inactive` (非アクティブなレジストレーションの場合) のどちらか。
  このフィールドがレジストレーションの作成時に提供されない場合、後でクライアントに
  よって変更される可能性のある `active` 状態で新規のレジストレーションが作成されます。
  有効期限が切れたレジストレーションの場合、この属性は、クライアントが
  `active`/`inactive` に更新しても、`expired` に設定されます。
  また、転送オペレーションで問題が発生したレジストレーションの場合、ステータスは、
  `failed` に設定されます。転送オペレーションが再び開始されるとすぐに、ステータスは、
  `active` に戻されます。
+ `expires` : レジストレーションの有効期限を ISO8601 形式で指定します。
  恒久的なレジストレーションは、このフィールドを省略しなければなりません。
+ `forwardingInformation`: プロバイダに対して行われた転送オペレーションに関連する
  情報です。その実装が転送機能をサポートしている場合は、実装によって自動的に提供されます。

`provider` フィールドには以下のサブフィールドが含まれています :
+ `http` : HTTP プロトコルを通じて情報を提供するプロバイダのためのパラメータを
  伝えるために使われます。
現在サポートされているプロトコルのみです。
これには、提供インタフェースを提供するエンドポイントとして機能する URL を持つ
`url` という名前のサブフィールドが含まれている必要があります。
エンドポイントは、プロトコル固有の部分 (たとえば、`/v2/entities`) を
含んでいなければなりません。
+ `supportedForwardingMode` : このコンテキスト・プロバイダによって
サポートされている転送モードを伝えるのに使用されます。デフォルトでは `all` です。
指定できる値は次のとおりです :
    + `none` : このプロバイダは、リクエスト転送をサポートしていません。
    + `query` : このプロバイダは、クエリデータへのリクエスト転送のみを
      サポートしています。
    + `update` : このプロバイダは、データを更新するためのリクエスト転送のみを
      サポートしています。
    + `all` : このプロバイダは、クエリと更新転送の両方のリクエストを
      サポートします。(デフォルト値)

`dataProvided` フィールドには、以下のサブフィールドが含まれています :

+ `entities`: オブジェクトのリスト。各オブジェクトは以下のサブフィールドで
  構成されています : 
    + `id` または `idPattern`: 影響を受けるエンティティの ID、またはパターンです。
      両方を同時に使用することはできませんが、そのうちの1つが存在する必要があります。
    + `type` または `typePattern`: 影響を受けるエンティティの型またはパターンです。
      両方を同時に使用することはできません。
      これを省略すると、"任意のエンティティ型" を意味します。
+ `attrs`: 提供される属性のリストです。指定されていない場合はすべての属性です。
+ `expression`: フィルタ式によって、提供されたデータの範囲が何であるかを
  表現することができます。
現在のところ、地理的範囲のみが、次のサブタームでサポートされています :
    + `georel` : この仕様のジオクエリ・セクションで指定されている、
      地理的関係のいずれかです。
    + `geometry` : この仕様のジオクエリ・セクションで指定されている、
      サポートされている任意のジオメトリです。
    + `coords` : この仕様のジオクエリ・セクションで指定されている、
      座標の文字列表現です。

`forwardingInformation` フィールドには、以下のサブフィールドが含まれています :

+  `timesSent` (編集不可、GET オペレーションのみ) : このレジストレーションに
   より送信されたリクエスト転送の数です。
+  `lastForwarding` (編集不可、GET オペレーションのみ) : ISO8601 形式の
   最後の転送タイムスタンプです。
+  `lastFailure` (編集不可、GET オペレーションのみ) : ISO8601 形式の
   最後の失敗タイムスタンプです。レジストレーションが転送に問題がない場合は
   存在しません。
+  `lastSuccess` (編集不可、GET オペレーションのみ) : 最後に成功した
   リクエスト転送の ISO8601 形式のタイムスタンプです。レジストレーションが
   成功したことがない場合は存在しません。

## レジストレーション・リスト  [/v2/registrations]

### レジストレーションをリスト [GET /v2/registrations{?limit,offset,options}]

システムに存在するすべてのコンテキスト・プロバイダのレジストレーションを
リストします。

+ Parameters
    + limit: 10 (optional, number) - 取得するレジストレーションの数を制限します。
    + offset: 20 (optional, number) - レジストレーションの数をスキップします。
    + options (optional, string) - オプション辞書
      + Members
          + count - 使用された場合、レジストレーションの総数は、
            HTTP ヘッダ `Fiware-Total-Count` に返されます。

レスポンス :

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Response 200

        [
          {
            "id": "abcdefg",
            "description": "Example Context Source",
            "dataProvided": {
              "entities": [
                {
                  "id": "Bcn_Welt",
                  "type": "Room"
                }
              ],
              "attrs": [
                "temperature"
              ]
            },
            "provider": {
              "http": {
                "url": "http://contextsource.example.org"
              },
              "supportedForwardingMode": "all"
            },
            "expires": "2017-10-31T12:00:00",
            "status": "active",
            "forwardingInformation": {
              "timesSent": 12,
              "lastForwarding": "2017-10-06T16:00:00.00Z",
              "lastSuccess": "2017-10-06T16:00:00.00Z",
              "lastFailure": "2017-10-05T16:00:00.00Z"
            }
          }
        ]

### レジストレーションの作成 [POST /v2/registrations]

新しいコンテキスト・プロバイダのレジストレーションを作成します。これは通常、
特定のデータのプロバイダとしてコンテキスト・ソースをバインドするために
使用されます。このセクションの冒頭で説明したように、レジストレーションは
JSON オブジェクトで表されます。

レスポンス : 

* 成功したオペレーションでは、201 Created を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Request (application/json)

        {
          "description": "Relative Humidity Context Source",
          "dataProvided": {
            "entities": [
              {
                "id": "room2",
                "type": "Room"
              }
            ],
            "attrs": [
              "relativeHumidity"
            ]
          },
          "provider": {
            "http":{ 
              "url": "http://localhost:1234"
            }
          }
        }

+ Response 201

    + Headers

            Location: /v2/registrations/abcde98765

## ID によるレジストレーション [/v2/registrations/{registrationId}]

### レジストレーションを取得 [GET /v2/registrations/{registrationId}]

レスポンスは、このセクションの冒頭で説明した JSON オブジェクトに
よって表されるレジストレーションです。

レスポンス : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + registrationId: abcdef (required, string) - レジストレーション ID です。

+ Response 200 (application/json)

      {
            "id": "abcdefg",
            "description": "Example Context Source",
            "dataProvided": {
              "entities": [
                {
                  "id": "Bcn_Welt",
                  "type": "Room"
                }
              ],
              "attrs": [
                "temperature"
              ]
            },
            "provider": {
              "http": {
                "url": "http://contextsource.example.org"
              },
              "supportedForwardingMode": "all"
            },
            "expires": "2017-10-31T12:00:00",
            "status": "failed",
            "forwardingInformation": {
              "timesSent": 12,
              "lastForwarding": "2017-10-06T16:00:00.00Z",
              "lastFailure": "2017-10-06T16:00:00.00Z",
              "lastSuccess": "2017-10-05T18:25:00.00Z",
            }
      }

### レジストレーションを更新 [PATCH /v2/registrations/{registrationId}]

リクエストに含まれるフィールドのみがレジストレーション時に更新されます。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + registrationId: abcdef (required, string) - レジストレーション ID です。

+ Request (application/json)

        {
            "expires": "2017-10-04T00:00:00"
        }

+ Response 204


### レジストレーションを削除 [DELETE /v2/registrations/{registrationId}]

コンテキスト・プロバイダのレジストレーションを取り消します。

レスポンス : 

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + registrationId: abcdef (required, string) - レジストレーション ID です。

+ Response 204

# Group Batch Operations

### 更新 [POST /v2/op/update]

このオペレーションにより、単一のバッチ・オペレーション (Batch Operations) で
複数のエンティティを作成、更新、および/または、削除することができます。
ペイロードは、2つのプロパティを持つオブジェクトです :

+ `actionType`, 更新アクションの種類を指定するには、`append`, `appendStrict`,
  `update`, `delete`, `replace` のいずれかを指定します。
+ `entities`, エンティティの配列。各エンティティは、JSON エンティティの表現形式
  ("JSONエンティティの表現" のセクションを参照) を使用して指定します。

このオペレーションは、`entities` ベクトル内のエンティティと同じ数の
個別オペレーションに分割されているので、` actionType` がそれぞれの
エンティティに対して実行されます。`actionType` に応じて、
通常の非バッチオペレーションによるマッピングを行うことができます :

* `append`: `POST /v2/entities` (エンティティがまだ存在しない場合)、
  または `POST /v2/entities/<id>/attrs` (エンティティが既に存在する場合)
  にマップします。
* `appendStrict`: `POST /v2/entities` (エンティティがまだ存在しない場合)
  または `POST /v2/entities/<id>/attrs?options=append`
  (エンティティが既に存在する場合) にマップします。
* `update`: `PATCH /v2/entities/<id>/attrs` にマップされます。
* `delete`: エンティティに含まれているすべての属性に対して、
  `DELETE /v2/entities/<id>/attrs/<attrName>` にマッピングし、
  エンティティに属性が含まれていない場合は、
  `DELETE /v2/entities/<id>` にマッピングします。
* `replace`: `PUT /v2/entities/<id>/attrs` にマップされます。

レスポンス :

* 成功したオペレーションでは、204 No Content を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Request (application/json)

        {
          "actionType": "append",
          "entities": [
            {
              "type": "Room",
              "id": "Bcn-Welt",
              "temperature": {
                "value": 21.7
               },
              "humidity": {
                "value": 60
              }
            },
            {
              "type": "Room",
              "id": "Mad_Aud",
              "temperature": {
                "value": 22.9
              },
              "humidity": {
                "value": 85
              }
            }
          ]
        }

+ Parameters
    + options (optional, string) - オプション辞書
      + Members
          + keyValues - 使用されると、リクエスト・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Response 204


###クエリ [POST /v2/op/query{?limit,offset,options}]

レスポンス・ペイロードは、一致するエンティティごとに1つのオブジェクトを
含む配列、またはエンティティが見つからない場合は空の配列  `[]`  です。
エンティティは、JSON エンティティの表現形式 ("JSONエンティティの表現" の
セクションを参照) に従います。

ペイロードには、次の要素 (すべてオプション) が含まれている場合があります :

+ `entities`: 検索する検索対象のリストです。各要素は、次の要素を
  持つ JSON オブジェクトで表されます。
    + `id` or `idPattern`: 影響を受けるエンティティの ID、またはパターン。
      両方を同時に使用することはできませんが、そのうちの1つが存在する
      必要があります。
    + `type` or `typePattern`: 検索するエンティティの型またはパターン型です。
      両方を同時に使用することはできません。
      これを省略すると、"任意のエンティティ型" を意味します。
+ `attrs`: 提供される属性のリスト (指定されていない場合はすべての属性) です。
+ `expression`: `q`, `mq`, `georel`, `geometry`, `coords`で構成される式です。
  (上記の "エンティティのリスト" オペレーションを参照してください)。
+ `metadata`: レスポンスに含めるメタデータ名のリスト。
  詳細については、"属性とメタデータのフィルタリング" を参照してください。

レスポンス・コード : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + limit: 10 (optional, number) - 取得するエンティティの数を制限します。
    + offset: 20 (optional, number) - スキップするレコード数です。
    + orderBy: temperature,!speed (optional, string) - 結果の順序付けの基準。
      詳細については、"結果の順序付け" を参照してください。
    + options (optional, string) - オプション辞書
      + Members
          + count - エンティティの総数は、`Fiware-Total-Count` という
            名前の HTTP ヘッダとして返されます。
          + keyValues - 使用されると、リクエスト・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + values - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。
          + unique - 使用されると、レスポンス・ペイロードは、単純化された
            エンティティ表現 `values` を使用します。反復値は除外されます。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Request (application/json)

        {
          "entities": [
            {
              "idPattern": ".*",
              "type": "Room"
            },
            {
              "id": "Car",
              "type": "P-9873-K"
            }
          ],
          "attrs": [
            "temperature",
            "humidity"
          ],
          "expression": {
             "q": "temperature>20"
          },
          "metadata": [
            "accuracy",
            "timestamp"
          ]
        }

+ Response 200 (application/json)

        [
          {
            "type": "Room",
            "id": "DC_S1-D41",
            "temperature": {
              "value": 35.6,
              "type": "Number"
            }
          },
          {
            "type": "Room",
            "id": "Boe-Idearium",
            "temperature": {
              "value": 22.5,
              "type": "Number"
            }
          },
          {
            "type": "Car",
            "id": "P-9873-K",
            "temperature": {
              "value": 40,
              "type": "Number",
              "accuracy": 2,
              "timestamp": {
                "value": "2015-06-04T07:20:27.378Z",
                "type": "DateTime"
              }
            }
          }
        ]


### 通知 [POST /v2/op/notify{?options}]

このオペレーションは、通知ペイロードを消費し、その通知によって含まれる
すべてのエンティティのデータが永続化され、必要に応じて上書きされるように
することを目的としています。このオペレーションは、1つの NGSIv2 エンドポイントが
別の NGSIv2 エンドポイント (フェデレーション・シナリオ)にレジストレーション
されている場合に便利です。 リクエスト・ペイロードは、NGSIv2 通知ペイロード
でなければなりません。その動作は、`actionType` が `append` に等しい、
`POST /v2/op/update` とまったく同じでなければなりません。 

レスポンス・コード : 

* 成功したオペレーションでは、200 OK を使用します。
* エラーは、2xx 以外のものとエラー・ペイロード (オプション) を使用します。
  詳細については、"エラー・レスポンス" のサブセクションを参照してください。

+ Parameters
    + options (optional, string) - オプション辞書
      + Members
          + keyValues - 使用されると、リクエスト・ペイロードは、単純化された
            エンティティ表現 `keyValues` を使用します。
            詳細は、"簡略化されたエンティティ表現" を参照してください。

+ Request (application/json)

        {
          "subscriptionId": "5aeb0ee97d4ef10a12a0262f",
          "data": [{
            "type": "Room",
            "id": "DC_S1-D41",
            "temperature": {
              "value": 35.6,
              "type": "Number"
            }
          },
          {
            "type": "Room",
            "id": "Boe-Idearium",
            "temperature": {
              "value": 22.5,
              "type": "Number"
            }
          }]
        }

+ Response 200 (application/json)
