2022年8月24日
ここまで、インタフェースに与える文字列をJSON文字列やJSONオブジェクトなどと表記してきましたが、ペイロードと言う場合があります。同じものだと理解してください。以下、データモデル以外のペイロードについて説明します。
2022年8月24日
subscriptionを設定する時の入力や参照時の出力となるペイロードです。subscriptionのペイロードには、以下のフィールドを含みます。
| key |
valueの説明 |
| id |
一意の識別子です。作成時に処理系により自動的に設定されます。作成時はペイロードは返却されませんので、レスポンスのLocationヘッダに返却されます |
| description |
subscriptionの説明です。作成時に指定します。省略可です。 |
| subject |
subjectは、notification (subscriptionの通知) がどの様な時に実行されるかを指定する部分 (オブジェクト) です。省略できません。 |
| entities |
entitiesは、どのEntitityに更新が入った際にnotificationが実行されるのかを指定する部分です。 |
| id |
subscription作成時に、ひとつのEntityを指定するためにi{d: entityId]を指定します。idか次のidPatternのどちらか一つを必ず指定します |
| idPattern |
subscription作成時に、複数のEntityを指定するために、idをパターンで指定します。"."や"*"を使います。 |
| type |
対象となるEntityのタイプを指定できますます。オプションですが、性能を考えると指定できる時には指定しましょう。次のtypePatternと併用する事は出来ません。 |
| typePattern |
対象となるEntityのタイプが複数の場合に指定できます。オプションです。"."や"*"を使います。 |
| condition |
conditionは、どの様な更新が実行された時にnotificationを実行するのかを指定する部分です。 |
| attrs |
どの属性が更新されたときに通知するかを指定します。配列の形式で記述します。オプションです。次のexpressionと同時に指定できます。 |
| expression |
更新された内容のフィルタリングを指定します。例えば、温度が40度を超えた時などの条件です。条件式にはq、mq、georel、geometry, coordsが使用できます。オプションです。 |
| notification |
bortificationは、通知する内容を指定する部分です。 |
| attrs |
通知するAttributeを配列で指定します。下にあるatrrsFormatにvalueが指定された場合は、attrsに指定した配列の記載順に値が返却されます。全てのAttributeを通知したい場合は、[]の様に空の配列を指定するか、attrsとexceptAttrsの両方を省略します。 |
| exceptAttrs |
前項と逆に、通知しないAttributeを指定します。atttrsと同時には使用できません。 |
| attrsFormat |
通知されるペイロードの形式を指定します。値としては、normalized、keyValues、valuesの三種類です。省略するとnormalizedとなります。 |
| meatadata |
通知されるペイロードに含めるmetadataを配列で指定します。 |
| timesSent |
notificationが実行された回数です。Subscription作成時にこのkeyは指定できません。 |
| lastNotification |
最後にnotificationが実行された際のタイムスタンプです。Subscription作成時にこのkeyは指定できません。 |
| lasrFailue |
最後にnotificationの実行が失敗した際のタイムスタンプです。Subscription作成時にこのkeyは指定できません。失敗が無いと、このkeyは返却されません。 |
| lastSuccess |
最後にnotificationの実行が成功した際のタイムスタンプです。Subscription作成時にこのkeyは指定できません。一度も通知が成功していないと、このkeyは返却されません。 |
| http |
notificationの実行時に、httpプロトコルで受け渡すためのパラメータです。下記のhttpCustomとどちらかを必ず指定します。 |
| url |
通知する先のurlです。 |
| httpCustom |
notificationの実行時に、httpプロトコルで受け渡すためのパラメータです。前記httpと異なり、ヘッダなども指定できます。
この指定では、以下の変数を埋め込むことが出来ます。
${id} : Notification実行時にEntityのidに置き換わります
${type} : Notification実行時にEntityのtypeに置き換わります
${<attributeName>} : Notification実行時にEntityの<attributeName>で指定しAttributeの値に置き換わります。尚、該当するAttributeがない場合は、空文字列("")になります。
尚、標準によると、複数のEntityに通知される場合、変数がそれぞれに併せて変換されず、同じ内容が通知されるという記述があります。利用前に確認が必要と思われます。また、ヘッダに"Ngsiv2-AttrsFormat: custom"が追加されるとありますが、同様に実機では未確認です。 |
| url |
通知する先のurlです。 |
| headers |
通知する際のhttpプロトコルのヘッダを指定します。省略可です。例えば、"url": "http://foo.com/v2/entities/${id}"と指定すると、通知先のurlは、http://foo.com/v2/entities/urn:ngsi-ld:Room:001に変換されて通知されます。 |
| qs |
通知する際のhttpプロトコルのオプションを指定します。省略可です。例えば、"url": "http://foo.com/v2/entities/${id}", "qs": {"type": "${type}" },と指定すると、http://foo.com/v2/entities/urn:ngsi-ld:Room:001?Type=Roomに変換されて通知されます。 |
| method |
通知する際のhttp動詞を指定します。省略するとPOSTになります。 |
| payload |
通知する際に使用するペイロードを指定します。省略すると、後述する既定のペイロードになります。例えば、"payload": "室温は ${temperature} 度です"と指定すると、通知の本文は「室温は 40 度です」となります。尚、ヘッダのContent-Lengthは指定しなくても正しい値になります(筆者注: 日本語は実機による動作は未確認です) |
| attrsFormat |
通知されるペイロードの形式を指定します。値としては、normalized、keyValues、valuesの三種類です。省略するとnormalizedとなります。 |
| meatadata |
通知されるペイロードに含めるmetadataを配列で指定します。 |
| timesSent |
notificationが実行された回数です。Subscription作成時にこのkeyは指定できません。 |
| lastNotification |
最後にnotificationが実行された際のタイムスタンプです。Subscription作成時にこのkeyは指定できません。 |
| lasrFailue |
最後にnotificationの実行が失敗した際のタイムスタンプです。Subscription作成時にこのkeyは指定できません。失敗が無いと、このkeyは返却されません。 |
| expires |
Subscriptionの有効期限です。省略すると、永久に有効という指定になります |
| status |
activeを指定すると、条件合致すれば通知が発生します。inactiveに設定すると、条件合致しても通知は発生しません。Subscription作成時に省略するとactiveになります。期限切れになるとexpireになり、通知が失敗するとfailueになります。failueになったあと、成功すればactiveに戻ります。 |
| throttling |
(optional) 続した通知の間の最小時間(秒です)。 |
以下、Subscriptionを設定する際のペイロードの例です。
|
{
"description": "室温異常通知 -- 体育館",
"subject": {
"entities": [
{
"idPattern": "urn:ngsi-ld:Room:Gymmnasium.*",
"type": "Room"
}
],
"condition": {
"attrs": [
"temperature"
],
"expression": {
"q": "temperature>40"
}
}
},
"notification": {
"http": {
"url": "http://hostpc:3000/subscriptions/temperature-change/"
},
"attrs": [
"temperature",
"humidity"
]
},
"expires": "2022-12-31T14:00:00.00Z",
"throttling": 60
} |
| 5.8.2 subscriptionの通知ペイロード |
2022年8月26日
Subscriptionで指定した条件に合致する更新が実行された時にnortificationが実行されますが、そのnortificationの通知ペイロードについて説明します。
以下は、Subscriptionでhttpを指定した時です。httpCustomの時でも、payloadを指定しない場合は以下となります。
| Key |
Valueの説明 |
| subscriptionId |
SubscriptionのIDです。Subscriptionの設定時にシステムにより自動的に生成されます。 |
| data |
通知の対象となったEntity毎の配列が格納されます。配列の各要素には、各Entityが入りますが、Subscriptionの指定に基づき、AttributeやMetadataが選択されます。また、格納される形式は、attrsFormatに従って、normalizad、keyValues、valueの形式となります。 |
| 5.8.3 Registrrationのペイロード |
2022年8月27日
registrationを設定する時の入力や参照時の出力となるペイロードです。registrationのペイロードには、以下のフィールドを含みます。
| key |
valueの説明 |
| id |
一意の識別子です。作成時に処理系により自動的に設定されます。作成時はペイロードは返却されませんので、レスポンスのLocationヘッダに返却されます |
| description |
registrationの説明です。作成時に指定します。省略可です。 |
| provider |
proveiderはContext Provider (CPr) に関する情報を記述する部分 (オブジェクト) です。省略できません。 |
| http |
registrationnの実行時に、httpプロトコルで受け渡すためのパラメータです。省略できません。 |
| url |
CPrのurlを指定します。NGSI v2に対するWebAPIのurlは"<apiRoot>/v2/<それ以下の構造>"と説明しましたが、CPrもNGSO v2をサポートしていると想定している仕様なので、CPrのurlも同じ構造となります。そのため、ここで指定する文字列は、urlの内、"<apiRoot>/v2"に相当する部分を記述します。"/<それ以下の構造>"の部分はregistration実行時に自動的に追加されます。 |
| supportedForwardingMode |
登録するCPがrサポートしているリクエストの転送モードを記述する部分です。値は以下の4種類のいずれかです。既定値はallです。
all : CPrはクエリの転送と更新転送の両方を サポートしています。
query : CPrはクエリの転送をサポートしています。
update : CPrは更新の転送をサポートしています。
none : CPrはリクエスト転送をサポートしていません。 |
| dataProvided |
CPrから提供されるデータについて記述する部分です。省略できません。 |
| entities |
どのEntityに関するデータをCPが提供するのかを指定します。つまり、ここで指定したEntityがGETされるとRegistrationが実行されます |
| id |
Registration作成時に、ひとつのEntityを指定するためにi{d: entityId]を指定します。idか次のidPatternのどちらか一つを必ず指定します |
| idPattern |
Registration作成時に、複数のEntityを指定するために、idをパターンで指定します。"."や"*"を使います。 |
| type |
対象となるEntityのタイプを指定できますます。オプションですが、性能を考えると指定できる時には指定しましょう。次のtypePatternと併用する事は出来ません。 |
| typePattern |
対象となるEntityのタイプが複数の場合に指定できます。オプションです。"."や"*"を使います。 |
| attrs |
通知するAttributeを配列で指定します。省略すると、全てのAttributeとなります。 |
| expression |
地理的範囲の情報で、提供されるデータの範囲をフィルタリングできます。指定には以下のみっつのバリエーションがあります。尚、指定の具体的な内容は後述します
georel : 「地理的関係」のいずれかで指定します。
geometry : 任意のジオメトリでしていします。
coords : 座標の文字列表現です。 |
| status |
activeを指定すると、registrationの問い合わせが発生します。inactiveに設定すると発生しません。Registration作成時に省略するとactiveになります。期限切れになるとexpireになり、通知が失敗するとfailueになります。failueになったあと、成功すればactiveに戻ります。 |
| expires |
Registrationの有効期限です。省略すると、永久に有効という指定になります |
| forwardingInformation |
Registrationの実行結果について、システムが自動的に設定します。registrationを設定する時に指定する事はできません。 |
| timesSent |
Registrationの実行回数です |
| lastForwarding |
最後にRegistrationを実行したタイムスタンプです |
| lastFailure |
最後にRegistrationが失敗したタイムスタンプです |
| lastSuccess |
最後にRegistrationが成功したタイムスタンプです |
| 5.8.4 Registrrationの要求時のペイロード |
2022年8月27日
CPrに対してのリクエスト転送の要求は、NGSI v2をサポートするサーバに対する要求と同じです。この要求は、entities/<entityId>に対するGET要求ではなく、op/queryに対するPOST要求で行われます。これは、複数のEntityに要求を可能とするためです。例えば、以下となります。
|
{
"entities": [
{
"id": "urn:ngsi-ld:Room:001-004-001",
"type": "Room"
}
],
"attrs": [
"temperature"
]
} |
これに対するCPrの応答も同様にNGSI v2のバッチ処理に対する応答でなくてはなりません。つまり、以下の様になります。
|
{
{
"id": "urn:ngsi-ld:Room:001-004-001",
"type": "Room",
"temperature": {
"value": "16",
"type": "float"
}
}
] |
| 5.8.5 Attributeの更新要求時のペイロード |
2022年9月19日
WebAPIでは、一つひとつのリクエスト内ではアトミック性が保証されますが、リクエスト間のアトミック性は保証しません。例えば、あるEntityのAttributeを読み出して、次にそのAttributeの値を変更しようとしても、そのわずかな間に他のプログラムが既に更新しているかもしれません。もし、そのまま変更した値を書き込んでしまうと、他のプログラムの更新が無かったことになってしまいます。この様な事を避けるために、一回のリクエストで更新を完結してしまう仕組みが提供されています。
具体的には、次の様なペイロードを指定して、数値属性のAttributeにPOSTすると、数値に10が加算されます。この例ではAttribute名はcountです。
|
{
"count": {
"type": "Integer",
"value": { "$inc": 10 }
}
} |
この$incを「更新演算子」と呼びます。更新演算子には、以下のものがあります。
| 更新演算子 |
Valueの説明 |
| $addToSet |
列属性のAttributeの元の列に対し、最後に追加する値を指定します。但し、同じ値が既に格納されていた場合は追加されません。無条件に追加したい場合は$pushを使用します。指定できる値はひとつだけです。例えば、値として列を指定すると、列全体がひとつの値として処理されます。 |
| $inc |
数値属性のAttributeの元の値に対し、加算する値を指定します。マイナスの値や小数も指定できます。 |
| $max |
数値属性のAttributeの元の値とこの値を比較し、大きい方の値にします。 |
| $min |
数値属性のAttributeの元の値とこの値を比較し、小さい方の値にします。 |
| $mul |
数値属性のAttributeの元の値に対し、乗算する値を指定します。マイナスの値や小数も指定できます。 |
| $pull |
列属性のAttributeの元の列に対し、取り除きたい値を指定します。元の列に複数個一致する値がある場合、それら全てが取り除かれます。指定できる値はひとつだけです。例えば、値として列を指定すると、列全体がひとつの値として処理されます。 |
| $pullAll |
列属性のAttributeの元の列に対し、取り除きたい値を列形式で指定します。元の列に複数個一致する値がある場合、それら全てが取り除かれます。$pullでは値に列を指定すると、列全体を一つの値として処理しますが、$pullAllでは列を分解し、それぞれの値に対して処理されます。 |
| $push |
列属性のAttributeの元の列に対し、最後に追加する値を指定します。指定できる値はひとつだけです。例えば、値として列を指定すると、列全体がひとつの値として格納されます |
| $set |
構造を持つAttributeの元の列に対し、追加するサブキーと値をオブジェクト形式で指定します。既にサブキーが存在する場合は値が上書きされます。尚、fiware.orgのドキュメントでは、存在しない場合に機能するとの記載もありますので、既にサブキーが存在する場合の値の書き換えに使用するのは避けた方が良いのかも知れません。 |
| $unset |
構造を持つAttributeの元の列に対し、削除するサブキーと値をオブジェクト形式で指定します。この際、値には意味はなく、何でも構いません。サブキーが存在しなかった場合は何も処理されません。 |
2022年9月19日
バッチ処理で指定するペイロードは以下の要素を含みます。
| key |
valueの説明 |
| actionType |
"append", "appendStrict", "delete", "replace", "updateのいずれかです。
"append": entitiesで指定した各entitiyを追加します。既に存在するEntityの場合はAttributeを追加します。Attributeも既にある場合は値を書き換えます。
"appendStrict": entitiesで指定した各entitiyを追加します。既に存在するEntityの場合はAttributeを追加します。但し、Attributeが既にある場合は422 Unprocessable Entityのエラーになります。
"delete": entitiesで指定した各entitiyの指定したAttributeを削除します。但し、idとtypeは削除できません。
"update": entitiesで指定した各entitiyの指定したAttributeの値を書き換えます。 |
| entities |
バッチ処理の対象となるEntityの列です。 |
| id |
更新処理の対象となるEntityのidです。 |
| type |
更新処理の対象となるEntityのtypeです。 |
| <attrobute> |
更新するAttributeのオブジェクトを指定します。 |
ペイロードの例です。この例では3件のEntityが更新対象としたkeyValues形式になっています。
|
{
"actionType": "appendStrict",
"entities": [
{
"id": "urn:ngsi-ld:Building:001",
"type": "Building",
"address": {
"type": "PostalAddress",
"value": {
"streetAddress": "本町2-33-2",
"addressLocality": "東村山市",
"addressRegion": "東京都",
"postalCode": "1890014"
}
},
"category": "public",
"location": {
"type": "Point",
"coordinates": [
139.467059,
35.759764
]
},
"name": "東村山市中央公民館",
"floorAboveGround": 4,
"floorUnderGround": 0
},
{
"id": "urn:ngsi-ld:Floor:001-001",
"type": "Floor",
"floorNumber": 1,
"refBuilding": {
"type": "Relatioship",
"value": "urn:ngsi-ld:Building:001"
}
},
{
"id": "urn:ngsi-ld:Room:001-001-001",
"type": "Room",
"name": "展示室",
"temperature": 0,
"refFloor": {
"type": "Relatioship",
"value": "urn:ngsi-ld:Floor:001-001"
}
}
]
} |
|
