FIWARE-NGSI v2 (release 2.1) 仕様

• はじめに
• 仕様
  • イントロダクション
  • 用語
    • コンテキスト・データのモデリングと交換 (Context data modelling and exchange)
      • コンテキストのエンティティ (Context Entities)
      • コンテキストの属性 (Context Attributes)
      • コンテキストのメタデータ (Context Metadata)
  • MIME タイプ (MIME Types)
  • JSON エンティティ表現 (JSON Entity Representation)
  • JSON 属性表現 (JSON Attribute Representation)
  • 簡略化されたエンティティ表現 (Simplified Entity Representation)
  • 部分表現 (Partial Representations)
  • 特殊な属性型 (Special Attribute Types)
  • 組み込み属性 (Builtin Attributes)
  • 特殊なメタデータ型 (Special Metadata Types)
  • 組み込みメタデータ (Builtin Metadata)
  • フィールド構文の制限事項 (Field syntax restrictions)
  • 属性名の制限 (Attribute names restrictions)
  • メタデータ名の制限 (Metadata names restrictions)
  • 結果の順序付け (Ordering Results)
  • エラー・レスポンス (Error Responses)
  • エンティティの地理空間プロパティ (Geospatial properties of entities)
    • シンプル・ロケーション・フォーマット (Simple Location Format)
    • GeoJSON
  • シンプル・クエリ言語 (Simple Query Language)
  • 地理的クエリ (Geographical Queries)
    • クエリの解決 (Query Resolution)
  • 属性とメタデータのフィルタリング (Filtering out attributes and metadata)
  • 通知メッセージ (Notification Messages)
  • カスタム通知 (Custom Notifications)
• API ルート (API Routes)
  • API エントリ・ポイント (API Entry Point)
    • API リソースを取得 [GET /v2]
  • エンティティの操作 (Entities Operations)
    • エンティティのリスト (Entities List)
      • エンティティをリスト [GET /v2/entities]
      • エンティティを作成 [POST /v2/entities]
    • id によるエンティティの操作 (Entity by ID)
      • エンティティを取得 [GET /v2/entities/{entityId}]
      • エンティティ属性を取得 [GET /v2/entities/{entityId}/attrs]
      • エンティティ属性の更新または追加 [POST /v2/entities/{entityId}/attrs]
      • 既存のエンティティ属性の更新 [PATCH /v2/entities/{entityId}/attrs]
      • すべてのエンティティ属性を置換 [PUT /v2/entities/{entityId}/attrs]
      • エンティティを削除する [DELETE /v2/entities/{entityId}]
    • 属性 (Attributes)
      • 属性データを取得 [GET /v2/entities/{entityId}/attrs/{attrName}]
      • 属性データを更新 [PUT /v2/entities/{entityId}/attrs/{attrName}]
      • 単一の属性を削除 [DELETE /v2/entities/{entityId}/attrs/{attrName}]
    • 属性値 (Attribute Value)
      • 属性値を取得 [GET /v2/entities/{entityId}/attrs/{attrName}/value]
      • 属性値を更新 [PUT /v2/entities/{entityId}/attrs/{attrName}/value]
    • エンティティ型 (Types)
      • 全エンティティ型のリスト [GET /v2/types]
      • 特定の型のエンティティ情報を取得 [GET /v2/types/{entityType}]
  • サブスクリプションの操作 (Subscriptions Operations)
    • サブスクリプション・ペイロード・データモデル
      • subscription
      • subscription.subject
      • subscription.subject.condition
      • subscription.notification
      • subscription.notification.http
      • subscription.notification.mqtt
      • subscription.notification.httpCustom
      • subscription.notification.mqttCustom
    • サブスクリプションのリスト
      • サブスクリプションをリスト [GET /v2/subscriptions]
      • サブスクリプションを作成 [POST /v2/subscriptions]
    • id によるサブスクリプションの操作
      • サブスクリプションを取得 [GET /v2/subscriptions/{subscriptionId}]
      • サブスクリプションを更新 [PATCH /v2/subscriptions/{subscriptionId}]
      • サブスクリプションを削除 [DELETE /v2/subscriptions/{subscriptionId}]
  • レジストレーションの操作 (Registration Operations)
    • レジストレーション・ペイロード・データモデル
      • registration
      • registration.provider
      • registration.dataProvided
      • registration.forwardingInformation
    • レジストレーションのリスト
      • レジストレーションをリスト [GET /v2/registrations]
      • レジストレーションを作成 [POST /v2/registrations]
    • id によるレジストレーションの操作
      • レジストレーションを取得 [GET /v2/registrations/{registrationId}]
      • レジストレーションを更新 [PATCH /v2/registrations/{registrationId}]
      • レジストレーションを削除 [DELETE /v2/registrations/{registrationId}]
  • バッチ操作 (Batch Operations)
    • 更新操作 (Update operation)
      • 更新 [POST /v2/op/update]
    • クエリ操作 (Query operation)
      • クエリ [POST /v2/op/query]
    • 通知操作 (Notify operation)
      • 通知 [POST /v2/op/notify]

はじめに

これは、NGSIv2 仕様 のリリース 2.1 です。2018年9月15日に リリースされた元の NGSIv2 と完全な下位互換性があります。

仕様

イントロダクション

FIWARE NGSI (Next Generation Service Interface) API は、

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

用語

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

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

コンテキストのエンティティ (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) または、部分表現 (partial representations) (以下の部分表現のセクションを参照) は、一部を残してしまう可能性があります。各オペレーションの仕様には、どの表現が入力として期待されるか、どの表現が 出力として提供 (レンダリング) されるかに関する詳細が含まれます。

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 では使用できません。

特殊なメタデータ型 (Special Metadata Types)

一般的に言えば、ユーザ定義のメタデータ型は参考になります。それらは、不透明な方法で NGSIv2 サーバによって処理されます。 それでも、以下に説明する型は、特別な意味を伝えるために使用されます:

• DateTime: ISO8601 形式で日付を識別します。このメタデータは、クエリ演算子の より大きい (greater-than), より小さい (less-than), 以上 (greater-or-equal), 以下 (less-or-equal) および 範囲 (range) で使用できます。たとえば (参照される 属性メタデータのみが表示されます):

"metadata": {
      "dateCreated": {
        "value": "2019-09-23T03:12:47.213Z",
        "type": "DateTime"
      }
}

組み込みメタデータ (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 の値は次のようになります:

• キーワード geo:distance は、"near" (georel=near) の空間関係 (spatial relationship) が使用されているときに リファレンス・ジオメトリまでの距離によって結果を並べます
• カンマで区切られた属性のリストです。組み込み属性、エンティティ 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 は、JSON (JavaScript Object Notation) に 基づく地理空間データ交換フォーマットです。GeoJSON は、より高度な柔軟性を提供し、ポイント高度またはより複雑な 地理空間形状、たとえば、 マルチ・ジオメトリ の表現を可能にします

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

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

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

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

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

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

注: この文献で、 実装のさまざまな欠点を説明しているように、サークル・ジオメトリはサポートされていません。

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

{
  "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 仕様書 にあります。さらに、 この GeoJSON チュートリアルは、 フォーマットの理解に役立ちます。

{
  "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] ]
}

attrsFormat が legacy の場合、サブスクリプション表現は NGSIv1 形式に従います。このようにして、ユーザは、NGSIv1 レガシー通知レシーバによる NGSIv2 サブスクリプションの拡張 (フィルタリングなど) の恩恵を受けることができます。

NGSIv1 は非推奨であることに注意してください。したがって、legacy 通知形式を使用することはお勧めしません。

{
    "subscriptionId": "56e2ad4e8001ff5e0a5260ec",
    "originator": "localhost",
    "contextResponses": [{
        "contextElement": {
            "type": "Car",
            "isPattern": "false",
            "id": "Car1",
            "attributes": [{
                "name": "temperature",
                "type": "centigrade",
                "value": "26.5",
                "metadatas": [{
                    "name": "TimeInstant",
                    "type": "recvTime",
                    "value": "2015-12-12 11:11:11.123"
                }]
            }]
        },
        "statusCode": {
            "code": "200",
            "reasonPhrase": "OK"
        }
    }]
}

通知には、関連するサブスクリプションの形式の値を含む Ngsiv2-AttrsFormat (attrsFormat が legacy の場合を想定) 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 の値が使用されます。

API ルート (API Routes)

API エントリ・ポイント (API Entry Point)

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

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

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

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

このリクエストは、次の要素を持つ JSON オブジェクトを返します:

• 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

エンティティの操作 (Entities Operations)

エンティティのリスト (Entities List)

エンティティをリスト [GET /v2/entities]

JSON エンティティ表現 に従って、id、型、パターン・マッチング (id または型)によって 異なる基準に一致するエンティティ・オブジェクトの配列、および/または、クエリまたは地理的クエリ (シンプル・クエリ言語 および 地理的クエリを参照) に一致する エンティティ・オブジェクトの配列を取得します。与えられたエンティティは、検索されるすべての基準に一致しなければ なりません。すなわち、基準が論理的 AND 方法で結合されます。そのパターン・マッチング・クエリ・パラメータは、それらに 対応する正確なマッチング・パラメータと互換性がない (すなわち、相互に排他的である) ことに留意してください。すなわち、 id の idPattern および type の typePattern レスポンス・ペイロードは、一致するエンティティごとに1つの オブジェクトを含む配列です。各エンティティは、JSON エンティティ表現で説明した JSON エンティティ表現形式に従います。

リクエスト・クエリ・パラメータ

このリクエストは、リクエスト・レスポンスをカスタマイズするために、次の URL パラメータを受け入れます。

パラメータ	オプション	タイプ	説明	例
id	✓	string	要素のコンマ区切りリスト。id がリスト内の要素の1つと一致するエンティティを取得します。idPattern と同時に使用できません	Boe_Idearium
type	✓	string	要素のコンマ区切りリスト。型がリスト内の要素の1つと一致するエンティティを取得します。typePattern と同時に使用できません	Room
idPattern	✓	string	正しくフォーマットされた正規表現。id が正規表現と一致するエンティティを取得します。idと互換性がありません	Bode_.*
typePattern	✓	string	正しくフォーマットされた正規表現。型が正規表現に一致するエンティティを取得します。type と互換性がありません	Room_.*
q	✓	string	temperature>40 (オプション, 文字列) - ; で区切られたステートメントのリストで構成されるクエリ式。つまり、q=statement1;statement2;statement3 です。 シンプル・クエリ言語仕様を参照してください	temperature>40
mq	✓	string	; で区切られたステートメントのリストで構成される属性メタデータのクエリ式。つまり、mq=statement1;statement2;statement3 です。シンプルクエリ言語仕様を参照してください	temperature.accuracy<0.9
georel	✓	string	一致するエンティティと参照形状 (reference shape) の間の空間的関係。地理的クエリを参照してください	near
geometry	✓	string	クエリが制限されている地理的領域。地理的クエリを参照してください	point
limit	✓	number	取得するエンティティの数を制限します	20
offset	✓	number	エンティティが取得される場所からのオフセットを確立します	20
coords	✓	string	';' で区切られた座標の緯度経度ペアのリスト。地理的クエリを参照してください	41.390205,2.154007;48.8566,2.3522
attrs	✓	string	データがレスポンスに含まれる属性名のコンマ区切りのリスト。属性は、このパラメータで指定された順序で取得されます。このパラメータが含まれていない場合、属性は任意の順序で取得されます。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	seatNumber
metadata	✓	string	レスポンスに含めるメタデータ名のリスト。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	accuracy
orderBy	✓	string	結果を順序付けするための基準。詳細については、結果の順序付けのセクションを参照してください	temperature,!speed
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
count	使用すると、エンティティの総数が Fiware-Total-Count という名前の HTTP ヘッダとしてレスポンスに返されます
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください
values	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。詳細については、簡略化されたエンティティ表現を参照してください
unique	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。繰り返しの値は省略されます。詳細については、簡略化されたエンティティ表現を参照してください
skipForwarding	使用すると、CB は CPrs への転送をスキップします。クエリは、CB のローカル・コンテキスト情報のみを使用して評価されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

レスポンス・ペイロードは、一致するエンティティごとに1つのオブジェクトを含む配列です。 各エンティティは、JSON エンティティ表現形式 (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	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	upsert

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください
upsert	使用すると、エンティティがすでに存在する場合は更新されます。upsert が使用されておらず、エンティティがすでに存在する場合、422 Unprocessable Entity エラーが返されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、作成されるエンティティを表すオブジェクトです。 オブジェクトは、JSON エンティティ表現形式 (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"
      }
    }
  }
}

レスポンス・コード

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

レスポンス・ヘッダ

レスポンスには、作成されたエンティティの URL を含む Location ヘッダが含まれます。

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

id によるエンティティの操作 (Entity by ID)

エンティティを取得 [GET /v2/entities/{entityId}]

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	取得するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
attrs	✓	string	データをレスポンスに含める必要がある属性名のコンマ区切りのリスト。属性は、このパラメータで指定された順序で取得されます。このパラメータが含まれていない場合、属性は任意の順序で取得され、エンティティのすべての属性がレスポンスに含まれます。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	seatNumber
metadata	✓	string	レスポンスに含めるメタデータ名のリスト。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	accuracy
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください
values	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。詳細については、簡略化されたエンティティ表現を参照してください
unique	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。繰り返しの値は省略されます。詳細については、簡略化されたエンティティ表現を参照してください
skipForwarding	使用すると、CB は CPrs への転送をスキップします。クエリは、CB のローカル・コンテキスト情報のみを使用して評価されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

レスポンスは、id で識別されるエンティティを表すオブジェクトです。オブジェクトは、JSON エンティティ表現形式 (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]

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	取得するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
attrs	✓	string	データをレスポンスに含める必要がある属性名のコンマ区切りのリスト。属性は、このパラメータで指定された順序で取得されます。このパラメータが含まれていない場合、属性は任意の順序で取得され、エンティティのすべての属性がレスポンスに含まれます。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	seatNumber
metadata	✓	string	レスポンスに含めるメタデータ名のリスト。詳細については、属性とメタデータのフィルタリングの セクションを参照してください	accuracy
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください
values	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。詳細については、簡略化されたエンティティ表現を参照してください
unique	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。繰り返しの値は省略されます。詳細については、簡略化されたエンティティ表現を参照してください
skipForwarding	使用すると、CB は CPrs への転送をスキップします。クエリは、CB のローカル・コンテキスト情報のみを使用して評価されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

ペイロードは、URL パラメータの id で識別されるエンティティを表すオブジェクトです。オブジェクトは JSON エンティティ表現形式 (JSON エンティティ表現のセクションと、 簡略化されたエンティティ表現および、部分表現 のセクションで説明されています) に従いますが、id フィールドと type フィールドは省略されます。

例:

{
  "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]

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	更新するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	append

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現セクションを参照してください
append	追加操作を強制します
overrideMetadata	既存のメタデータをリクエストで提供されたものに置き換えます。詳細については、メタデータ更新セマンティクスのセクションを参照してください
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、URL パラメータの id で識別されるエンティティに追加または更新する属性を持つオブジェクトです。オブジェクトは JSON エンティティ表現形式 (JSON エンティティ表現のセクションと、 簡略化されたエンティティ表現および、部分表現 のセクションで説明されています) に従いますが、idフィールドとtypeフィールドは省略されます。

例:

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

レスポンス・コード

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

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	更新するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	Example
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	keyValues

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用される場合、レスポンス・ペイロードは keyValues の簡略化されたエンティティ表現を使用します。詳細については、簡略化されたエンティティ表現のセクションを参照してください
overrideMetadata	既存のメタデータをリクエストで提供されたものに置き換えます。詳細については、メタデータ更新セマンティクスのセクションを参照してください
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、URL パラメータの id で識別されるエンティティで更新する属性を表すオブジェクトです。オブジェクトは JSON エンティティ表現形式 (JSON エンティティ表現のセクションと、 簡略化されたエンティティ表現および、部分表現 のセクションで説明されています) に従いますが、id フィールドと type フィールドは省略されます。

例:

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

レスポンス

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

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

ペイロード内の新しいエンティティ属性がエンティティに追加されます。以前にエンティティに存在していた属性が削除され、 リクエスト内の属性に置き換えられます。

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	変更するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	Example
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	keyValues

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用される場合、レスポンス・ペイロードは keyValues の簡略化されたエンティティ表現を使用します。詳細については、簡略化されたエンティティ表現のセクションを参照してください
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、URL パラメータの id で識別されるエンティティに追加または置換された新しいエンティティ属性を表すオブジェクト です。オブジェクトは JSON エンティティ表現形式 (JSON エンティティ表現のセクションと、 簡略化されたエンティティ表現および、部分表現 のセクションで説明されています) に従いますが、id フィールドと type フィールドは省略されます。

例:

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

レスポンス・コード

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

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
entityId	string	削除するエンティティの id	Room

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

属性 (Attributes)

属性データを取得 [GET /v2/entities/{entityId}/attrs/{attrName}]

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

リクエスト URL パラメータ

これらのパラメータは URL リクエストの一部です。これらは必須です。

パラメータ	タイプ	説明	例
entityId	string	取得するエンティティの id	Room
attrName	string	取得する属性の名前	temperature

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
metadata	✓	string	レスポンスに含めるメタデータ名のリスト。詳細については、属性とメタデータのフィルタリングのセクションを参照してください	accuracy
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	skipForwarding

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
skipForwarding	使用すると、CB は CPrs への転送をスキップします。クエリは、CB のローカル・コンテキスト情報のみを使用して評価されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

レスポンスは、id で識別されるエンティティに含まれる URL で指定された属性名で識別される属性を表すオブジェクトです。 オブジェクトは、JSON 属性表現 (および部分表現 のセクション) で説明されている構造に従います。

例:

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

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

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

リクエスト URL パラメータ

これらのパラメータは URL リクエストの一部です。これらは必須です。

パラメータ	タイプ	説明	例
entityId	string	更新するエンティティの id	Room
attrName	string	更新する属性の名前	Temperature

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	Example
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	overrideMetadata

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
overrideMetadata	既存のメタデータをリクエストで提供されたものに置き換えます。詳細については、メタデータ更新セマンティクスのセクションを参照してください
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

リクエスト・ペイロードは、id で識別されるエンティティに含まれる URL で指定された属性名で識別される属性を表す オブジェクトです。オブジェクトは、JSON属性表現 (および 部分表現のセクション) で説明されている構造に従います。

例:

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

レスポンス・コード

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

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

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

リクエスト URL パラメータ

これらのパラメータは URL リクエストの一部です。これらは必須です。

パラメータ	タイプ	説明	例
entityId	string	削除するエンティティの id	Room
attrName	string	削除する属性の名前	Temperature

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

属性値

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

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

リクエスト URL パラメータ

これらのパラメータは URL リクエストの一部です。これらは必須です。

パラメータ	タイプ	説明	例
entityId	string	取得するエンティティの id	Room
attrName	string	取得する属性の名前	Location

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	skipForwarding

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
skipForwarding	使用すると、CB は CPrs への転送をスキップします。クエリは、CB のローカル・コンテキスト情報のみを使用して評価されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

application/json または text/plain を含む Content-Type ヘッダ (レスポンス・ペイロードに応じて)

レスポンス・ペイロード

レスポンス・ペイロードは、オブジェクト、配列、文字列、数値、ブール値、または属性の値を持つ null にすることができます。

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

例:

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

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

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

リクエスト URL パラメータ

これらのパラメータは URL リクエストの一部です。これらは必須です。

パラメータ	タイプ	説明	例
entityId	string	更新するエンティティの id	Room
attrName	string	更新する属性の名前	Location

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	Example
type	✓	string	エンティティ型。同じエンティティ id を持つエンティティが複数ある場合のあいまいさを回避します	Room
options	✓	string	クエリのオプションのコンマ区切りリスト。次の表を参照してください	forcedUpdate

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ	text/plain
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

リクエストのペイロードは、次のように Content-Type HTTP ヘッダで指定されたペイロード MIME タイプに応じて、JSON オブジェクトまたは配列、あるいはプレーン・テキストにすることができます:

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

例:

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

レスポンス・コード

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

エンティティ型 (Types)

全エンティティ型のリスト [GET /v2/types]

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

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

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

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

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
limit	✓	number	取得するタイプの数を制限します	10
offset	✓	number	いくつかのレコードをスキップします	20
options	✓	string	オプション	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
count	使用すると、型 (types) の総数が HTTP ヘッダ Fiware-Total-Count に返されます
values	使用すると、レスポンス・ペイロードはエンティティ型のリストを含む JSON 配列です
noAttrDetail	使用される場合、リクエストは属性型の詳細を提供しません。各属性名に関連付けられている types リストは [] に設定されます。このオプションを使用すると、Orion はこれらのクエリをはるかに高速に解決します (場合によっては30秒から0.5秒節約できます)

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

このリクエストは、見つかったさまざまなエンティティ型ごとに、要素を含むオブジェクトを含む JSON 配列を返します:

• type: エンティティ型の名前。型自体
• attrs: すべての属性と、その特定の型に属する各属性の型を含むオブジェクト
• count: その特定のエンティティ型を持つエンティティの数

例:

[
  {
    "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
  }
]

特定の型のエンティティ情報を取得 [GET /v2/types/{entityType}]

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

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

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	Example
options	✓	string	オプション	noAttrDetail

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
noAttrDetail	使用される場合、リクエストは属性型の詳細を提供しません。各属性名に関連付けられている types リストは [] に設定されます。このオプションを使用すると、Orion はこれらのクエリをはるかに高速に解決します (場合によっては30秒から0.5秒節約できます)

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

このリクエストは、取得したエンティティ型の2つのフィールドを持つ JSON を返します:

• attrs: その特定の型に属するエンティティに存在する属性の各型のオブジェクトを含むオブジェクト このオブジェクトには配列 types が含まれており、指定された型のすべてのエンティティでその属性に対して見つかった さまざまな型がすべて含まれています
• count: その特定のエンティティ型を持つエンティティの数

例:

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

サブスクリプションの操作 (Subscriptions Operations)

サブスクリプション・ペイロード・データモデル

subscription

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

パラメータ	オプション	タイプ	説明
id		string	サブスクリプションの一意の識別子。作成時に自動的に作成されます
description	✓	string	クライアントがサブスクリプションを説明するために使用するフリーテキスト
subject		object	サブスクリプションのサブジェクトを説明するオブジェクト
notification		object	サブスクリプションがトリガーされたときに送信する通知を説明するオブジェクト
expires	✓	ISO8601	ISO8601 形式のサブスクリプションの有効期限。永続的なサブスクリプションでは、このフィールドを省略する必要があります
status		string	active (アクティブなサブスクリプションの場合) または inactive (非アクティブなサブスクリプションの場合)。サブスクリプションの作成時にこのフィールドが指定されていない場合、新しいサブスクリプションは active ステータスで作成され、後でクライアントが変更できます。期限切れのサブスクリプションの場合、この属性は expired に設定されます (クライアントがそれを active/inactive に更新するかどうかは関係ありません)。また、通知で問題が発生しているサブスクリプションの場合、ステータスは failed に設定されます。通知が再び機能し始めるとすぐに、ステータスは active に戻ります。さらに、oneshot 値が使用可能で、サブスクリプションの作成後にエンティティが更新されるたびに通知を1回だけ起動します。通知がトリガーされると、サブスクリプションは "status": "inactive" に移行します
throttling	✓	number	2つの連続する通知の間に経過する必要がある最小時間 (秒単位)。Orion は、スロットル・ガード期間中にこの破棄通知 (discarding notifications) を実装します。したがって、通知が時間的に近すぎると、通知が失われる可能性があります

throttling フィールドを参照すると、ローカルな方法で実装されます。マルチ CB 構成 (HA シナリオ) では、最後の通知値 (last-notification measure) が各 Orion ノードに対してローカルであることを考慮に入れてください。各ノードは、潜在的に 新しい値を取得するために定期的に DB と同期しますが (ここの詳細)、 特定のノードの値が古い場合があります。スロットルは100％正確ではありません

subscription.subject

subject には次のサブフィールドが含まれます:

パラメータ	オプション	タイプ	説明
entities	✓	string	オブジェクトのリスト。各オブジェクトは次のサブフィールドで構成されています: id または idPattern: id または、影響を受けるエンティティのパターン。両方を同時に使用することはできませんが、一方が存在している必要があります。 type または typePattern: 型 または、影響を受けるエンティティの型パターン。両方を同時に使用することはできません。省略した場合は、"any entity type" (任意のエンティティ型) を意味します
condition	✓	object	通知をトリガーする条件。省略した場合は、"属性を変更すると条件がトリガーされる" ことを意味します

subscription.subject.condition

condition には次のサブフィールドが含まれます:

パラメータ	オプション	タイプ	説明
attrs	✓	array	通知をトリガーする属性名の配列
expression	✓	object	q, mq, georel, geometry および coords で構成される式 (このフィールドについては、上記のエンティティをリストの操作を参照してください)
alterationTypes	✓	array	サブスクリプションがトリガーされる変更 (エンティティの作成、エンティティの変更など) を指定します (変更タイプに基づくサブスクリプションのセクションを参照)

condition フィールドに基づいて、通知トリガー・ルールは次のとおりです:

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

subscription.notification

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

パラメータ	オプション	タイプ	説明
attrs または exceptAttrs		array	両方を同時に使用することはできません。 attrs: 通知メッセージに含まれる属性のリスト。また、attrsFormat value が使用されたときに属性が通知に表示される順序も定義します ("通知メッセージ" のセクションを参照)。空のリストは、すべての属性が通知に含まれることを意味します。詳細については、属性とメタデータのフィルタリングのセクションを参照してください exceptAttrs: 通知メッセージから除外される属性のリスト。つまり、通知メッセージには、このフィールドにリストされているもの attrs も exceptAttrs も指定されていない場合、すべての属性が通知に含まれます
http, httpCustom, mqtt または mqttCustom	✓	object	それらの1つが存在する必要がありますが、同時に1つを超えてはなりません。x トランスポート・プロトコルを介して配信される通知のパラメータを伝達するために使用されます
attrsFormat	✓	string	エンティティが通知でどのように表されるかを指定します。受け入れられる値は、normalized (デフォルト), keyValues, values, または legacy です。 attrsFormat がそれらとは異なる値をとると、エラーが発生します。 詳細については、通知メッセージのセクションを参照してください
metadata	✓	string	通知メッセージに含まれるメタデータのリスト。詳細については、属性とメタデータの除外のセクションを参照してください
onlyChangedAttrs	✓	boolean	true の場合、通知には、attrs または exceptAttrs フィールドと組み合わせて、トリガー更新リクエストで変更された属性のみが含まれます。(フィールドが省略されている場合、デフォルトは false です))
covered	✓	boolean	true の場合、通知には、エンティティに存在しない場合でも (この場合、null 値で) attrs フィールドで定義されたすべての属性が含まれます。(デフォルト値は false です)。詳細については、対象サブスクリプションのセクションを参照してください
timesSent	取得時のみ	number	編集できません。GET 操作にのみ存在します。このサブスクリプションのために送信された通知の数
lastNotification	取得時のみ	ISO8601	編集できません。GET 操作にのみ存在します。ISO8601 形式の最終通知タイムスタンプ
lastFailure	取得時のみ	ISO8601	編集できません。GET 操作にのみ存在します。ISO8601 形式の最後の障害タイムスタンプ。サブスクリプションで通知に問題が発生したことがない場合は存在しません
lastSuccess	取得時のみ	ISO8601	編集できません。GET 操作にのみ存在します。最後に成功した通知の ISO8601 形式のタイムスタンプ。サブスクリプションに通知が成功したことがない場合は存在しません
lastFailureReason	取得時のみ	string	編集できません。GET 操作にのみ存在します。最後の失敗の原因を説明します (つまり、失敗は lastFailure 時に発生しました)。MQTT サブスクリプションには含まれていません
lastSuccessCode	取得時のみ	number	編集できません。GET 操作にのみ存在します。成功した通知が最後に送信されたときに受信エンドポイントによって返された HTTP コード (200, 400, 404, 500など) (つまり、成功は lastSuccess時間に発生しました)。MQTT サブスクリプションには含まれていません
failsCounter	取得時のみ	number	編集できません。GET 操作にのみ存在します。サブスクリプションに関連付けられた連続して失敗した通知の数。failsCounter は、通知の試行が失敗するたびに1ずつ増加し、通知の試行が成功すると0にリセットされます (この場合、failsCounter は省略されます)
maxFailsLimit	✓	number	連続した失敗の最大許容数を確立します。失敗の数が maxFailsLimit の値を超えた場合 (つまり、ある時点で failsCounter が maxFailsLimit より大きい場合)、Orion はサブスクリプションを自動的に inactive 状態に渡します。サブスクリプションを再度有効にする (状態を再び active に設定する) には、サブスクリプションの更新操作 (PATCH /v2/subscription/subId) が必要です

onlyChangedAttrs フィールドに関しては、例として、特定のサブスクリプションで attrs が [A、B、C] の場合、 デフォルトの動作 (onlyChangedAttrs が false の場合) とトリガー更新はAのみを変更します。次に、A, B, およびC に通知されます (つまり、トリガー更新は重要ではありません)。ただし、onlyChangedAttrs が true であり、 トリガー更新が変更されたAのみである場合、通知にはAのみが含まれます。

lastFailureReasonとlastSuccessCodeに関しては、どちらも通知で発生する可能性のある問題を分析するために使用できます。 詳細については、問題診断手順書 のセクションを 参照してください。

さらに、maxFailsLimit フィールドに関して、Orion がサブスクリプションを自動的に無効にすると、WARN レベルのログトレースが出力されます。この行の形式は次のとおりです:

time=... | lvl=WARN | corr=... | trans=... | from=... | srv=... | subsrv=... | comp=Orion | op=... | msg= Subscription <subId> automatically disabled due to failsCounter (N) overpasses maxFailsLimit (M)

subscription.notification.http

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

パラメータ	オプション	タイプ	説明
url		string	通知が生成されたときに呼び出されるサービスを参照する URL。NGSIv2 準拠のサーバは、http URL スキーマをサポートする必要があります。他のスキーマもサポートされる可能性があります
timeout	✓	number	サブスクリプションがレスポンスを待機する最大時間 (ミリ秒単位)。このパラメータに許可される最大値は1800000 (30分) です。timeout が0に定義されているか省略されている場合、-httpTimeout CLI パラメータとして渡された値が使用されます。詳細については、コマンドライン・オプションのセクションを参照してください

subscription.notification.mqtt

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

パラメータ	オプション	タイプ	説明
url		string	使用するMQTT ブローカーのエンドポイントを表します。URL は mqtt:// で始まる必要があり、パスを含めることはできません (ホストとポートのみが含まれます)
topic		string	使用する MQTT トピックを表します
qos	✓	number	サブスクリプションに関連付けられた通知で使用する MQTT QoS 値 (0, 1, または 2)。省略した場合、QoS 0 が使用されます
user	✓	string	ブローカーとの接続を認証するために使用されるユーザー名
passwd	✓	string	ブローカー認証のパスフレーズ。サブスクリプション情報を取得するときは常にオフになります (例: GET /v2/subscriptions)

MQTT 通知の詳細については、MQTT 通知のドキュメントを参照してください。

subscription.notification.httpCustom

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

パラメータ	オプション	タイプ	説明
url		string	上記の http と同じです
headers	✓	object	通知メッセージに含まれる HTTP ヘッダのキー・マップ
qs	✓	object	通知メッセージに含まれる URL クエリ・パラメータのキー・マップ
method	✓	string	通知を送信するときに使用するメソッド (デフォルトは POST)。有効な HTTP メソッドのみが許可されます。無効な HTTP メソッドを指定すると、400 Bad Request エラーが返されます
payload	✓	string	通知で使用されるペイロード。省略した場合、デフォルトのペイロード ("通知メッセージ" のセクションを参照) が使用されます
timeout	✓	number	サブスクリプションがレスポンスを待機する最大時間 (ミリ秒単位)。このパラメータに許可される最大値は1800000 (30分) です。timeout が0に定義されているか省略されている場合、-httpTimeout CLI パラメータとして渡された値が使用されます。詳細については、コマンドライン・オプションのセクションを参照してください

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

subscription.notification.mqttCustom

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

パラメータ	オプション	タイプ	説明
url		string	使用するMQTT ブローカーのエンドポイントを表します。URL は mqtt:// で始まる必要があり、パスを含めることはできません (ホストとポートのみが含まれます)
topic		string	使用する MQTT トピックを表します. Macro replacement is also performed for this field (i.e: a topic based on an attribute )
qos	✓	number	サブスクリプションに関連付けられた通知で使用する MQTT QoS 値 (0, 1, または 2)。省略した場合、QoS 0 が使用されます
user	✓	string	ブローカーとの接続を認証するために使用されるユーザー名
passwd	✓	string	ブローカー認証のパスフレーズ。サブスクリプション情報を取得するときは常にオフになります (例: GET /v2/subscriptions)
payload	✓	string	通知で使用されるペイロード。省略した場合、デフォルトのペイロード (通知メッセージのセクションを参照) が使用されます

mqttCustom を使用する場合は、カスタム通知のセクションで説明されている考慮事項が適用されます。 MQTT 通知の詳細については、MQTT 通知のドキュメントを参照してください。

サブスクリプション・リスト

サブスクリプションをリスト [GET /v2/subscriptions]

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

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
limit	✓	number	取得するタイプの数を制限します	10
offset	✓	number	いくつかのレコードをスキップします	20
options	✓	string	オプション	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
count	使用すると、サブスクリプションの総数が HTTP ヘッダ Fiware-Total-Count に返されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

ペイロードは、サブスクリプションごとに1つのオブジェクトを含む配列です。各サブスクリプションは、JSON サブスクリプション表現形式に従います (サブスクリプション・ペイロード・データモデル のセクションで説明されています)。

例:

[
  {
    "id": "62aa3d3ac734067e6f0d0871",
    "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": "2025-04-05T14:00:00.00Z",
    "status": "failed",
    "throttling": 5
  }
]

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

新しいサブスクリプションを作成します。

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、JSON サブスクリプション表現形式 (サブスクリプション・ペイロード・データモデル セクションで説明されています) に従うサブスクリプションを含む 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": "2025-04-05T14:00:00.00Z",
  "throttling": 5
}

レスポンス・コード

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

レスポンス・ヘッダ

• 作成が成功したとき (レスポンス・コード 201) に、サブスクリプションの作成に使用されたパスの値 (つまり、/v2/subsets/62aa3d3ac734067e6f0d0871) を含むヘッダ Location を返します

id によるサブスクリプションの操作

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

リクエストされたサブスクリプションを返します。

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
subscriptionId	string	取得するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

ペイロードは、JSON サブスクリプション表現形式 (サブスクリプション・ペイロード・データモデル のセクションで説明されています) に従うサブスクリプションを含む JSON オブジェクトです。

例:

{
  "id": "62aa3d3ac734067e6f0d0871",
  "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": "2025-04-05T14:00:00.00Z",
  "status": "active",
  "throttling": 5
}

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
subscriptionId	string	更新するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、JSON サブスクリプション表現形式 (サブスクリプション・ペイロード・データモデル セクションで説明されています) に従ってサブスクリプションの変更されるフィールドを含む JSON オブジェクトです。

例:

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

レスポンス・コード

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

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
subscriptionId	string	削除するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レジストレーションの操作 (Registration Operations)

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

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

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

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

レジストレーション・ペイロード・データモデル

registration

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

パラメータ	オプション	タイプ	説明
id		string	レジストレーションに割り当てられた一意の識別子。作成時に自動的に生成されます
description	✓	string	このレジストレーションに与えられた説明
provider		object	レジストレーションされたコンテキストソースを説明するオブジェクト
dataProvided		object	このソースによって提供されるデータを説明するオブジェクト.
status	✓	string	レジストレーションの現在のステータスを可能な値でキャプチャする列挙フィールド: [active, inactive, expired または failed]。レジストレーション作成時にこのフィールドが指定されていない場合、新しい登録は active ステータスで作成され、後でクライアントによって変更される可能性があります。期限切れの登録の場合、この属性は expired に設定されます (クライアントがそれを active/inactive に更新するかどうかは関係ありません)。また、転送操作で問題が発生したレジストレーションの場合、ステータスは failed に設定されます。転送操作が再開されるとすぐに、ステータスは active に戻ります
expires	✓	ISO8601	ISO8601 形式の登録有効期限。永続的な登録では、このフィールドを省略する必要があります
forwardingInformation		object	プロバイダに対して行われた転送操作に関連する情報。そのような実装が転送機能をサポートする場合、実装によって自動的に提供されます

registration.provider

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

パラメータ	オプション	タイプ	説明
http		object	これは、HTTP プロトコルを介して情報を配信するプロバイダのパラメータを伝達するために使用されます (現在サポートされているプロトコルのみ)。 提供するインターフェースを提供するエンドポイントとして機能する URL を含む url という名前のサブフィールドが含まれている必要があります。エンドポイントには、プロトコル固有の部分 (たとえば、/v2/entity) を含めない必要があります
supportedForwardingMode		string	これは、このコンテキスト・プロバイダによってサポートされる転送モードを伝達するために使用されます。デフォルトでは all。許可される値は次のとおりです。 none: このプロバイダはリクエストの転送をサポートしていません query: このプロバイダはクエリデータへのリクエストの転送のみをサポートしています update: このプロバイダはデータを更新するためのリクエスト転送のみをサポートします all: このプロバイダは両方のクエリと更新の転送リクエストをサポートします (デフォルト値)

registration.dataProvided

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

パラメータ	オプション	タイプ	説明
entities		array	オブジェクトのリスト。それぞれが次のサブフィールドで構成されています。 id または idPattern: id または影響を受けるエンティティのパターン。両方を同時に使用することはできませんが、どちらか一方が存在する必要があります type または typePattern: 型または影響を受けるエンティティ型のパターン。両方を同時に使用することはできません。省略した場合は、"任意のエンティティ型" を意味します
attrs		array	提供される属性のリスト (指定されていない場合は、すべての属性)
expression		object	フィルタリング式を使用して、提供されるデータの範囲を表すことができます。現在、地理的スコープのみが次のサブ用語でサポートされています georel: 地理的クエリのセクションで指定されている地理的関係のいずれか geometry: 地理的クエリのセクションで指定されているサポートされているジオメトリのいずれか coords: 地理的クエリのセクションで指定されている座標の文字列表現

registration.forwardingInformation

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

パラメータ	オプション	タイプ	説明
timesSent	検索時のみ	number	編集できません。GET 操作にのみ存在します。このレジストレーションのために送信されたリクエスト転送の数
lastForwarding	検索時のみ	ISO8601	編集できません。GET 操作にのみ存在します。ISO8601 形式の最終転送タイムスタンプ
lastFailure	検索時のみ	ISO8601	編集できません。GET 操作にのみ存在します。ISO8601 形式の最後の障害タイムスタンプ。レジストレーションで転送に問題が発生したことがない場合は存在しません
lastSuccess	検索時のみ	ISO8601	編集できません。GET 操作にのみ存在します。最後に成功したリクエスト転送の ISO8601 形式のタイムスタンプ。レジストレーションの通知が成功したことがない場合は存在しません

レジストレーション・リスト

レジストレーションをリスト [GET /v2/registrations]

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

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
limit	✓	number	取得するタイプの数を制限します	10
offset	✓	number	いくつかのレコードをスキップします	20
options	✓	string	オプション	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
count	使用すると、レジストレーションの総数が HTTP ヘッダ Fiware-Total-Count に返されます

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

レジストレーション・ペイロード・データモデル に続く各レジストレーションのオブジェクトによって表されるすべてのレジストレーションを含む JSON 配列

例:

[
  {
    "id": "62aa3d3ac734067e6f0d0871",
    "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]

新しいコンテキスト・プロバイダのレジストレーションを作成します。これは通常、特定のデータのプロバイダとしてコンテキスト・ ソースをバインドするために使用されます。

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、JSON レジストレーション表現形式に従うレジストレーションを含む JSON オブジェクトです (レジストレーション・ペイロード・データモデル セクションで説明されています)。

例:

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

レスポンス・コード

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

レスポンス・ヘッダ

リクエストは、オペレーションが成功すると (リターン・コード 201)、レジストレーションのパス (つまり、/v2/registrations/62aa3d3ac734067e6f0d0871) を含むヘッダ Location を返します。

id によるレジストレーションの操作

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

リクエストされたレジストレーションを返します。

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
registrationId	string	取得するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

レスポンス・ヘッダ

成功したオペレーションでは、application/json 値を持つ Content-Type ヘッダが返されます。

レスポンス・ペイロード

ペイロードは、JSON レジストレーション表現形式に従うレジストレーションを含む JSON オブジェクトです (レジストレーション・ペイロード・データモデル セクションで説明されています)。

例:

{
      "id": "62aa3d3ac734067e6f0d0871",
      "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}]

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
registrationId	string	更新するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、JSON レジストレーション表現形式 (レジストレーション・ペイロード・データモデル セクションで説明されています) に従ってレジストレーションの変更されるフィールドを含む JSON オブジェクトです。

例:

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

レスポンス・コード

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

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

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

リクエスト URL パラメータ

このパラメータは URL リクエストの一部です。これは必須です。

パラメータ	タイプ	説明	例
registrationId	string	削除するサブスクリプションの id	62aa3d3ac734067e6f0d0871

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

レスポンス・コード

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

バッチ操作 (Batch Operations)

更新操作 (Update operation)

更新 [POST /v2/op/update]

このオペレーションにより、単一のバッチ・オペレーション (Batch Operations) で複数のエンティティを作成、更新、 および/または、削除することができます。

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
options	✓	string	オプション	keyValues

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現セクションを参照してください
overrideMetadata	既存のメタデータをリクエストで提供されたものに置き換えます。詳細については、メタデータ更新セマンティクスのセクションを参照してください
forcedUpdate	更新操作では、属性が効果的に更新された場合にのみ更新されるデフォルトの動作の代わりに、実際の属性の更新があるかどうかに関係なく、一致するサブスクリプションをトリガーする必要があります。同じ効果については、 entityChange の変更タイプも確認してください
flowControl	高負荷シナリオでの飽和を回避するために、フロー制御メカニズムを有効にします。これについては、ドキュメントのこのセクションで説明されています

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

ペイロードは、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 にマッピングします

例:

{
  "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
      }
    }
  ]
}

レスポンス・コード

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

クエリ操作 (Query operation)

クエリ [POST /v2/op/query]

このオペレーションは、リクエスト・ペイロードで提供されるフィルタに基づいて、既存のエンティティ間でクエリを実行します。

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
limit	✓	number	取得するエンティティの数を制限します	10
offset	✓	number	いくつかのレコードをスキップします	20
orderBy	✓	string	結果を順序付けするための基準。詳細については、結果の順序付けのセクションを参照してください	temperature,!speed
options	✓	string	オプション	count

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
count	使用すると、エンティティの総数が Fiware-Total-Count という名前の HTTP ヘッダとして応答に返されます
keyValues	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください
values	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。詳細については、簡略化されたエンティティ表現を参照してください
unique	使用すると、レスポンス・ペイロードは簡略化されたエンティティ表現の values を使用します。繰り返しの値は省略されます。詳細については、簡略化されたエンティティ表現を参照してください
skipForwarding	When used, CB skips forwarding to CPrs. The query is evaluated using exclusively CB local context information.

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

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

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

例:

{

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

_**レスポンス・コード**_

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

_**レスポンス・ヘッダ**_

成功したオペレーションでは、`application/json` 値を持つ `Content-Type` ヘッダが返されます。

_**レスポンス・ペイロード**_

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

例:

```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"
      }
    }
  }
]

通知操作 (Notify operation)

通知 [POST /v2/op/notify]

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

リクエスト・クエリ・パラメータ

パラメータ	オプション	タイプ	説明	例
options	✓	string	オプション	keyValues

この特定のリクエストに対して options パラメータが持つことができる値は次のとおりです:

オプション	説明
keyValues	使用すると、リクエスト・ペイロードは簡略化されたエンティティ表現の keyValues を使用します。詳細については、簡略化されたエンティティ表現を参照してください

リクエスト・ヘッダ

ヘッダ	オプション	説明	例
Content-Type		MIME タイプ。application/json である必要があります	application/json
Fiware-Service	✓	テナントまたはサービス。詳細については、サブ・セクションのマルチテナンシを参照してください	acme
Fiware-ServicePath	✓	サービス・パスまたはサブ・サービス。詳細については、サブセクションのサービス・パスを参照してください	/project

リクエスト・ペイロード

通知メッセージ のセクションで説明されているように、リクエスト・ペイロードは NGSIv2 通知ペイロードである必要があります。

例:

{
  "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"
    }
  }]
}

レスポンス・コード

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