Download to read offline
![16
Orion Context Broker Basic Operations
Entities
• GET /v2/entities
• Retrieve all entities
• POST /v2/entities
• Creates an entity
• GET /v2/entities/{entityID}
• Retrieves an entity
• [PUT|PATCH|POST] /v2/entities/{entityID}
• Updates an entity (different “flavors”)
• DELETE /v2/entities/{entityID}
• Deletes an entity](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-16-320.jpg)
![Quick Usage Example: Filters (1)
29
200 OK
Content-Type: application/json
...
[
{
"id": "Room2",
"pressure": 730,
"temperature": 29,
"type": "Room"
}
]
GET <cb_host>:1026/v2/entities?options=keyValues&q=temperature>27](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-29-320.jpg)
![Quick Usage Example: Filters (2)
30
200 OK
Content-Type: application/json
...
[
{
"id": "Room1",
"pressure": 720,
"temperature": 25,
"type": "Room"
}
]
GET <cb_host>:1026/v2/entities?options=keyValues&q=pressure==715..725
The full description of the Simple
Query Language for filtering can be
found in the NGSIv2 Specification
document](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-30-320.jpg)
![Quick Usage Example: Subscription
POST <cb_host>:1026/v2/subscriptions
Content-Type: application/json
…
{
"subject": {
"entities": [
{
"id": "Room1",
"type": "Room"
}
],
"condition": {
"attrs": [ "temperature" ]
}
},
"notification": {
"http": {
"url": "http://<host>:<port>/publish"
},
"attrs": [ "temperature" ]
},
"expires": "2026-04-05T14:00:00.000Z"
}
201 Created
Location: /v2/subscriptions/51c0ac9ed714fb3b37d7d5a8
...
32](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-32-320.jpg)
![POST /publish HTTP/1.1
Content-type: application/json; charset=utf-8
Ngsiv2-AttrsFormat: normalized
…
{
"subscriptionId": "574d720dbef222abb860534a",
"data": [
{
"id": "Room1",
"type": "Room",
"temperature": {
"type": "Float",
"value": 19,
"metadata": {}
}
}
]
}
Quick Usage Example: Notification
34](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-34-320.jpg)
![List existing subscriptions
35
200 OK
Content-Type: application/json
…
[{
"id": " 51c0ac9ed714fb3b37d7d5a8 ",
"expires": "2026-04-05T14:00:00.000Z",
"status": "active",
"subject": {
"entities": [{
"id": "Room1",
"type": "Room"
}],
"condition": {
"attrs": ["temperature"]
}
},
"notification": {
"timesSent": 3,
"lastNotification": "2016-05-31T11:19:32.000Z",
"lastSuccess": "2016-05-31T11:19:32.000Z",
"attrs": ["temperature"],
"attrsFormat": "normalized",
"http": {
"url": "http://localhost:1028/publish"
}
}
}]
The full description of the
subscription object (including all its
fields) can be found in the NGSIv2
Specification
GET <cb_host>:1026/v2/subscriptions](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-35-320.jpg)
![201 Created
...
Batch Operation Example: Create Several Rooms
POST <cb_host>:1026/v2/op/update
Conten-Type: application/json
...
{
"actionType": "append",
"entities": [
{
"type": "Room",
"id": "Room3",
"temperature": {
"value": 21.2,
"type": "Float"
},
"pressure": {
"value": 722,
"type": "Integer"
}
},
…
37
…
{
"type": "Room",
"id": "Room4",
"temperature": {
"value": 31.8,
"type": "Float"
},
"pressure": {
"value": 712,
"type": "Integer"
}
}
]
}](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-37-320.jpg)
![• Entities can have an attribute
that specifies its location
– value: a JSON object in
GeoJSON format
– type: geo:json
• Example: create an entity called
Madrid
…and create a couple more towns:
• Leganés
• Alcobendas
POST <cb_host>:1026/v2/entities
{
"type": "City",
"id": "Madrid",
"position": {
"type": "geo:json",
"value": {"type": "Point", "coordinates":
[ -3.691944, 40.418889] }
}
}
53
Geo-location
null is also supported as value,
meaning "no location". This may be
useful in some cases.](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-53-320.jpg)
![• For the GET /v2/entities operation
• By entity type
• By entity id list
• By entity id pattern (regex)
• By entity type pattern (regex)
• By geographical location
– Described in detail in previous slides
• Filters can be used simultaneously (i.e. like AND condition)
61
GET <cb_host>:1026/v2/entities?type=Room
GET <cb_host>:1026/v2/entities?id=Room1,Room2
GET <cb_host>:1026/v2/entities?idPattern=^Room[2-5]
GET <cb_host>:1026/v2/entities?typePattern=T[ABC]
Query filters](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-61-320.jpg)
![63
POST <cb_host>:1026/v2/subscriptions
…
{
"subject": {
"entities": [
{
"id": “Car5",
"type": "Car"
},
{
"idPattern": "^Room[2-5]",
"type": "Room"
},
{
"id": "D37",
"typePattern": "Type[ABC]"
},
],
"condition": {
"attrs": [ "temperature" ],
"expression": {
"q": "temperature>40",
"mq": "humidity.avg==80..90",
"georel": "near;maxDistance:100000",
"geometry": "point",
"coords": "40.418889,-3.691944"
}
}
},
…
}
• Filters can be also used in
subscriptions
– id
– type
– id pattern
– type pattern
– attribute values
– metadata value
– geographical location
Query filters](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-63-320.jpg)
![JEXL Support in Custom notifications
A more evolved case
speed: "10 m/s"
count: {"count":5, "sum":100}
code: null
value: 14
max: 50
speed:"${(speed|split(' ')[0])|parseInt}"
ratio: "${count.sum/count.count}"
code: "${code||'invalid}"
alert: "${(value>max)?'nok':'ok’}”
count: "${{count:count.count+1,
sum:count.sum+((speed|split(' '))[0]
|parseInt)}}"
speed: 10
ratio: 20
code: "invalid"
alert: "ok"
count: {"count":6, "sum":110}
Entity update
Subscription
Custom Notification
76](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-76-320.jpg)
![JEXL Support in Custom notifications
A more evolved case
speed:"30 m/s"
count: {"count":5, "sum":500}
code: 456
value: 75
max: 50
speed:"${(speed|split(' ')[0])|parseInt}"
ratio: "${count.sum/count.count}"
code: "${code||'invalid}"
alert: "${(value>max)?'nok':'ok’}”
count: "${{count:count.count+1,
sum:count.sum+((speed|split(' '))[0]
|parseInt)}}"
speed: 30
ratio: 100
code: 456
alert: "nok"
count: {"count":6, "sum":530}
Entity update
Subscription
Custom Notification
77](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-77-320.jpg)
![• Detailed information in the notifications
element
– timesSent: total number of notifications
attempts (both successful and failed)
– failsCounter: number of consecutive
notifications fails
• failsCounter > 0 means subscription is in
failing state
– lastSuccess: last time that notification was
successfully sent
– lastFailure: last time that notification was
tried and failed
– lastNotification: last time the notification was
sent (either success or failure)
• Corollary: lastNotification value is the same
than either lastFailure or lastSuccess
– lastFailureReason: cause of last failure (text)
– lastSuccessCode: the HTTP code (number)
returned by receiving endpoint last time a
successful notification was sent
• lastSuccessCode and
lastFailureReason fields only in HTTP
notifications (not in MQTT ones)
81
200 OK
Content-Type: application/json
…
[{
"id": " 51c0ac9ed714fb3b37d7d5a8 ",
"status": "active",
"subject": { … },
"notification": {
"timesSent": 3,
"failsCounter": 1,
"lastNotification": "2016-05-31T11:19:32.000Z",
"lastSuccess": "2016-05-31T10:07:32.000Z",
"lastFailure": "2016-05-31T11:19:32.000Z",
"lastSuccessCode": 200,
"lastFailureReason": "Timeout was reached",
…
}
}]
Notification status](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-81-320.jpg)
![• A variant of the active
status, so when the
subscription is triggered
one time (i.e. a
notification is sent) it
automatically steps to
inactive status
• An inactive subscription
can step to oneshot,
starting again the process
83
Oneshot subscription
200 OK
Content-Type: application/json
…
[{
"id": "51c0ac..",
"status": "oneshot",
…
}
}]
200 OK
Content-Type: application/json
…
[{
"id": "51c0ac..",
"status": "inactive",
…
}
}]
Subscription is
triggered
PATCH /v2/subscriptions/51c0ac..
{
"status": "oneshot"
}](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-83-320.jpg)
![• By default, subscriptions are triggered
when entities are created or changed (i.e.
update with a value different from the
previous value)
• This can be changed with alterationTypes
field (within condition) to specify a list of
the following (OR condition):
– entityUpdate: entity update (no matter if is
actually changed or not)
– entityChange: entity actual change
– entityCreate: entity is created
– entityDelete: entity is deleted
• The alteration type which triggered the
subscription can be included in notifications
by adding the special alterationType
attribute (which possible values are the
same tokens above)
85
Subscriptions based in alteration type
POST /v2/subscriptions
{
"subject": {
…
"condition": {
"alterationTypes":
["entityCreate","entityDelete"]
}
},
"notification": {
…
"attrs": [ "alterationType", "*" ]
}
}](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-85-320.jpg)
![87
Covered subscriptions
SUB 1:
"notification": {
...
"attrs": [
"temp",
"hum"
]
}
SUB 2 (covered)
"notification": {
...
"attrs": [
"temp",
"hum
],
"covered": true
}
POST /v2/entities/E/attrs/temp
{ ...
"value": 19,
"type": "Number"
}
NOTIF1:
…
{
…
"temp": {
"type": "Float",
"value": 19,
"metadata": {}
}
}
NOTIF2 (covered)
…
{
…
"temp": {
"type": "Number",
"value": 19,
"metadata": {}
},
"hum": {
"type": "None",
"value": null,
"metadata": {}
}
}](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-87-320.jpg)
![• Using mqtt instead of http in the subscription payload
• Taking advantage of MQTT features (shared subscriptions, QoS, retain, etc.)
• MQTT authentication based in user/password is supported
• Efficient connection management (removing idle connections to MQTT brokers if
they are not in use, base din -mqttMaxAge)
• Also supporting custom notifications (mqttCustom)
88
MQTT notifications
POST <cb_host>:1026/v2/subscriptions
…
{
"subject": {
"entities": [
{ "idPattern": ".*" }
],
},
"notification": {
"mqtt": {
"url": "mqtt://<mqtt_broker>:1883",
"topic": "/notif",
"qos": 1
}
}
}
Context Broker
MQTT Broker
…
MQTT broker subscribers](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-88-320.jpg)
![• Examples
– Include only attributes temp and lum
• In queries: GET /v2/entities?attrs=temp,lum
• In subscriptions: "attrs": [ "temp", "lum" ]
– Include dateCreated and not any other attribute
• In queries: GET /v2/entities?attrs=dateCreated
• In subscriptions: "attrs": [ "dateCreated" ]
– Include dateModified and all the other (regular)
attributes
• In queries: GET /v2/entities?attrs=dateModified,*
• In subscriptions: "attrs": [ "dateModified", "*" ]
– Include all attributes (same effect that not using attrs,
not very interesting)
• In queries: GET /v2/entities?attrs=*
• In subscriptions: "attrs": [ "*" ]
91
Attributes filtering and special attributes](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-91-320.jpg)
![• Examples
– Include only metadata MD1 and MD2
• In queries: GET /v2/entities?metadata=MD1,MD2
• In subscriptions: "metadata": [ "MD1", "MD2" ]
– Include previousValue and not any other metadata
• In queries: GET /v2/entities?metadata=previousValue
• In subscriptions: "attrs": [ "previousValue" ]
– Include actionType and all the other (regular) metadata
• In queries: GET /v2/entities?metadata=actionType,*
• In subscriptions: "attrs": [ "actionType", "*" ]
– Include all metadata (same effect that not using
metadata, not very interesting)
• In queries: GET /v2/entities?metadata=*
• In subscriptions: "metadata": [ "*" ]
93
Metadata filtering and special metadata](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-93-320.jpg)
![POST <cb_host>:1026/v2/registrations
…
{
"description": "Registration for Car1",
"dataProvided": {
"entities": [
{
"id": "Car1",
"type": "Car"
}
],
"attrs": [
"speed"
]
},
"provider": {
"http": {
"url": "http://contextprovider.com/Cars"
},
"legacyForwarding": true
}
}
201 Created
Location: /v2/registrations/5a82be3d093af1b94ac0f730
…
95
Registration & Context Providers
(*) With some limitations in current Orion version, see
https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#registration-implementatio
n-differences](https://image.slidesharecdn.com/orioncontextbroker-20240911-240911160958-57619aa0/85/Orion-Context-Broker-introduction-20240911-95-320.jpg)
Uploaded byFermin Galan
Orion Context Broker introduction 20240911
The document discusses the management of context information at large scale, focusing on the FIWARE Orion Context Broker and its NGSI API, which are essential for implementing smart applications across various domains like smart cities and smart homes. It outlines how context information is gathered from multiple sources, including sensors and user inputs, to support real-time data consumption and notifications. Additionally, it covers basic operations for entities and attributes, subscription mechanisms, and batch operations for efficient context management.
More Related Content
Similar to Orion Context Broker introduction 20240911
![谷歌留痕技术教程[ 𝙩𝙤𝙥 𝟮𝟯𝟯. 𝙘 𝙤𝙢 ]](https://cdn.slidesharecdn.com/ss_thumbnails/top233-260130173900-2eb784f9-thumbnail.jpg?width=640&height=640&fit=bounds)
Orion Context Broker introduction 20240911
- 1. Managing Context Informationat Large Scale: Introduction Fermín Galán Márquez - fermin.galanmarquez@telefonica.com (Reference Orion Context Broker version: 4.1.0)
- 2. • Context Managementin FIWARE • Orion Context Broker • Creating and pulling data • Pushing data and notifications • Batch operations 2 Introduction
- 3. Being “Smart” requiresfirst being “Aware” Boiler • Manufacturer • Last revision • Product id • temperature Users • Name-Surname • Birthday • Preferences • Location Flowerpot • Humidity • Watering plan Context Information Application 3 • Implementing a Smart Application requires gathering and managing context information, referring to values of attributes characterizing relevant entities • There are many application domains where management of context info is relevant: smart home, smart agrifood, smart industry, smart logistics, smart cities standard API
- 4. Being “Smart” requiresfirst being “Aware” 4 • Implementing a Smart Application requires gathering and managing context information, referring to values of attributes characterizing relevant entities • There are many application domains where management of context info is relevant: smart home, smart agrifood, smart industry, smart logistics, smart cities Ship • Company • Speed • Location • … Truck • Driver • Location • … Container • Dimension • Temperature • … Context Information Application standard API
- 5. Being “Smart” requiresfirst being “Aware” • Implementing a Smart Application requires gathering and managing context information, referring to values of attributes characterizing relevant entities • There are many application domains where management of context info is relevant: smart home, smart agrifood, smart industry, smart logistics, smart cities Bus • Location • No. passengers • Driver • Licence plate Citizen • Name-Surname • Birthday • Preferences • Location Shop • Location • Business name • Franchise • offerings Context Information Application 5 standard API
- 6. Context Information Managementin Smart Cities • Systems dealing with management of city services or third-party apps (subject to access control policies) can consume and produce context info • Overall city governance can rely on context information available (real-time and historic) to monitor KPIs and run BigData analysis 6 City Services Bus • Location • No. passengers • Driver • Licence plate Citizen • Name-Surname • Birthday • Preferences • Location Shop • Location • Business name • Franchise • offerings Context Information City Governance System City Services Third-party Apps
- 7. Different sources ofcontext need to be handle • Context information may come from many sources: – Existing systems – Users, through mobile apps – Sensor networks • Source of info for a given entity may vary over time Place = “X”, temperature = 30º What’s the current temperature in place “X”? A sensor in a pedestrian street The Public Bus Transport Management system A person from his smartphone It’s too hot! 7 standard API
- 8. Different sources ofcontext need to be handle • Context information may come from many sources: – Existing systems – Users, through mobile apps – Sensor networks • Source of info for a given entity may vary over time 8 Street = “X”, traffic = high What’s the current traffic in street “X”? Standard API A sensor in a pedestrian street The Public Bus Transport Management system Citizen’s car app or smartphone Notify me the changes of traffic in street “X”
- 9. A non-intrusive approachis required • Capable to integrate with existing or future systems without impact in their architectures, but bringing a common context information hub • Info about attributes of one entity may come from different systems, which work either as Context Producers or Context Providers Application/Service Standard API System A System B Context Producer Context Provider attribute “location” attribute “driver” 9
- 10. Context Management inFIWARE • The FIWARE Context Broker GE implements the NGSI API: a simple yet powerful standard API for managing Context information complying with the requirements of a smart enabled system • The FIWARE NGSI API is Restful: any web/backend programmer gets quickly used to it Application/Service Context Broker NGSI API Boiler • Manufacturer • Last revision • Product id • temperature Users • Name-Surname • Birthday • Preferences • Location Flowerpot • Humidity • Watering plan 10
- 11. FIWARE NGSI: “TheSNMP for IoT” • Capturing data from, or Acting upon, IoT devices becomes as easy as to read/change the value of attributes linked to context entities using a Context Broker Context Broker NGSI API NGSI API GET /v2/entities/lamp1/attrs/presenceSensor PUT /v2/entities/lamp1/attrs/status/value “light on” Setting up the value of attribute “status” to “light on” triggers execution of a function in the IoT device that switches the lamp on Issuing a get operation on the “presenceSensor” attribute enables the application to get info about presence of people near the lamp 11
- 12. Connecting to theInternet of Things • Capturing data from, or Acting upon, IoT devices becomes as easy as to read/change the value of attributes linked to context entities using a Context Broker Context Broker GET /v2/entities/lamp1/attrs/humidity PUT /v2/entities/lamp1/attrs/status/value “watering” Setting up the value of attribute “status” to “watering” triggers execution of a function in the IoT device that waters the plant Issuing a get operation on the “humidity” attribute enables the application to find out whether the plant has to be watered 12 NGSI API NGSI API
- 13. • Main functions: –Context management – Context availability management (advanced topic) (*) • HTTP and REST-based – JSON payload support • Context in NGSI is based in an entity-attribute model: Attributes • Name • Type • Value Entity • EntityId • EntityType 1 n has 13 Orion Context Broker (*) With some limitations in current Orion version, see https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#registration-implementatio n-differences
- 14.
- 15. GET <cb_host>:1026/version { "orion" :{ "version" : “4.1.0", "uptime" : "0 d, 0 h, 0 m, 5 s", "git_hash" : "...", "compile_time" : "nodate", "compiled_by" : "fermin", "compiled_in" : "centollo", "release_date" : "nodate", "machine" : "x86_64", "doc" : "https://fiware-orion.readthedocs.org/en/4.0.0/" } } 15 Orion Context Broker – check health
- 16. 16 Orion Context BrokerBasic Operations Entities • GET /v2/entities • Retrieve all entities • POST /v2/entities • Creates an entity • GET /v2/entities/{entityID} • Retrieves an entity • [PUT|PATCH|POST] /v2/entities/{entityID} • Updates an entity (different “flavors”) • DELETE /v2/entities/{entityID} • Deletes an entity
- 17. 17 Orion Context BrokerBasic Operations Attributes • GET /v2/entities/{entityID}/attrs/{attrName} • Retrieves an attribute’s data • PUT /v2/entities/{entityID}/attrs/{attrName} • Updates an attribute’s data • DELETE /v2/entities/{entityID}/attrs/{attrName} • Deletes an attribute • GET /v2/entities/{entityID}/attrs/{attrName}/value • Retrieves an attribute’s value • PUT /v2/entities/{entityID}/attrs/{attrName}/value • Updates an attribute’s value
- 18. Context Broker operations:create & pull data • Context Producers publish data/context elements by invoking the update operations on a Context Broker. • Context Consumers can retrieve data/context elements by invoking the query operations on a Context Broker Context Consumer query Context Producer update Context Broker 18
- 19. Quick Usage Example:Car Create 201 Created 19 POST <cb_host>:1026/v2/entities Content-Type: application/json ... { "id": "Car1", "type": "Car", "speed": { "type": "Float", "value": 98 } } You can add "?options=upsert" to the URL. In that case, the entity is updated if already exists.
- 20. Quick Usage Example:Car Speed Update (1) PUT <cb_host>:1026/v2/entities/Car1/attrs/speed Content-Type: application/json ... { "type": "Float", "value": 110 } 204 No Content … 20 In the case of id ambiguity, you can use "?type=Car" to specify entity type
- 21. Quick Usage Example:Car Speed Query (1) 200 OK Content-Type: application/json ... { "type": "Float", "value": 110, "metadata": {} } 21 You can get all the attributes of the entity using the entity URL: GET/v2/entities/Car1/attrs GET <cb_host>:1026/v2/entities/Car1/attrs/speed
- 22. Quick Usage Example:Car Speed Update (2) PUT <cb_host>:1026/v2/entities/Car1/attrs/speed/value Content-Type: text/plain ... 115 204 No Content … 22
- 23. Quick Usage Example:Car Speed Query (2) 23 200 OK Content-Type: text/plain ... 115.000000 GET <cb_host>:1026/v2/entities/Car1/attrs/speed/value Accept: text/plain
- 24. 201 Created ... Quick UsageExample: Room Create (1) POST <cb_host>:1026/v2/entities Content-Type: application/json ... { "id": "Room1", "type": "Room", "temperature": { "type": "Float", "value": 24 }, "pressure": { "type": "Integer", "value": 718 } } 24
- 25. 204 No Content … QuickUsage Example: Room Update (1) 25 PATCH <cb_host>:1026/v2/entities/Room1/attrs Content-Type: application/json ... { "temperature“: { "type": "Float", "value": 25 }, "pressure": { "type": "Integer", "value": 720 } }
- 26. Quick Usage Example:Room Query (1) 26 200 OK Content-Type: application/json ... { "pressure": { "type": "Integer", "value": 720, "metadata": {} }, "temperature": { "type": "Float", "value": 25, "metadata": {} } } GET <cb_host>:1026/v2/entities/Room1/attrs
- 27. Quick Usage Example:Room Query (2) 27 200 OK Content-Type: application/json ... { "pressure": 720, "temperature": 25 } GET <cb_host>:1026/v2/entities/Room1/attrs?options=keyValues
- 28. 201 Created ... Quick UsageExample: Room Create (2) POST <cb_host>:1026/v2/entities Content-Type: application/json ... { "id": "Room2", "type": "Room", "temperature": { "type": "Float", "value": 29 }, "pressure": { "type": "Integer", "value": 730 } } 28
- 29. Quick Usage Example:Filters (1) 29 200 OK Content-Type: application/json ... [ { "id": "Room2", "pressure": 730, "temperature": 29, "type": "Room" } ] GET <cb_host>:1026/v2/entities?options=keyValues&q=temperature>27
- 30. Quick Usage Example:Filters (2) 30 200 OK Content-Type: application/json ... [ { "id": "Room1", "pressure": 720, "temperature": 25, "type": "Room" } ] GET <cb_host>:1026/v2/entities?options=keyValues&q=pressure==715..725 The full description of the Simple Query Language for filtering can be found in the NGSIv2 Specification document
- 31. Context Broker operations:push data • Context Consumers can subscribe to receive context information that satisfy certain conditions using the subscribe operation. Such subscriptions may have an expiration time. • The Context Broker notifies updates on context information to subscribed Context Consumers by invoking the notify operation they export subId = subscribeContext (consumer, expr, expiration) Context Consumer notify (subId, data/context) Context Broker Application 31
- 32. Quick Usage Example:Subscription POST <cb_host>:1026/v2/subscriptions Content-Type: application/json … { "subject": { "entities": [ { "id": "Room1", "type": "Room" } ], "condition": { "attrs": [ "temperature" ] } }, "notification": { "http": { "url": "http://<host>:<port>/publish" }, "attrs": [ "temperature" ] }, "expires": "2026-04-05T14:00:00.000Z" } 201 Created Location: /v2/subscriptions/51c0ac9ed714fb3b37d7d5a8 ... 32
- 33. 25 19 Quick Usage Example:Notification 33
- 34. POST /publish HTTP/1.1 Content-type:application/json; charset=utf-8 Ngsiv2-AttrsFormat: normalized … { "subscriptionId": "574d720dbef222abb860534a", "data": [ { "id": "Room1", "type": "Room", "temperature": { "type": "Float", "value": 19, "metadata": {} } } ] } Quick Usage Example: Notification 34
- 35. List existing subscriptions 35 200OK Content-Type: application/json … [{ "id": " 51c0ac9ed714fb3b37d7d5a8 ", "expires": "2026-04-05T14:00:00.000Z", "status": "active", "subject": { "entities": [{ "id": "Room1", "type": "Room" }], "condition": { "attrs": ["temperature"] } }, "notification": { "timesSent": 3, "lastNotification": "2016-05-31T11:19:32.000Z", "lastSuccess": "2016-05-31T11:19:32.000Z", "attrs": ["temperature"], "attrsFormat": "normalized", "http": { "url": "http://localhost:1028/publish" } } }] The full description of the subscription object (including all its fields) can be found in the NGSIv2 Specification GET <cb_host>:1026/v2/subscriptions
- 36. Orion Context Brokerbatch operations 36 • Batch query and batch update • They are equivalent in functionality to previously described RESTful operations • All them use POST as verb and the /v2/op URL prefix, including operation parameters in the JSON payload • They implement extra functionality that cannot be achieved with RESTful operations, e.g. to create several entities with the same operation • They are not a substitute but a complement to RESTful operations
- 37. 201 Created ... Batch OperationExample: Create Several Rooms POST <cb_host>:1026/v2/op/update Conten-Type: application/json ... { "actionType": "append", "entities": [ { "type": "Room", "id": "Room3", "temperature": { "value": 21.2, "type": "Float" }, "pressure": { "value": 722, "type": "Integer" } }, … 37 … { "type": "Room", "id": "Room4", "temperature": { "value": 31.8, "type": "Float" }, "pressure": { "value": 712, "type": "Integer" } } ] }
- 38. How to getOrion? (Docker containers) 38 • Assuming docker is installed in your system • Documentation in https://github.com/telefonicaid/fiware-orion/tree/develop/docker • Quick guide git clone https://github.com/telefonicaid/fiware-orion.git cd fiware-orion/docker sudo docker-compose up • That’s all! – curl localhost:1026/version • Installing Orion docker in less than 1 minute – https://www.youtube.com/watch?v=6taR7e20H9U
- 39. Would you liketo play with this? 39 • Have a look to the FIWARE Reference Tutorial application – git clone https://github.com/Fiware/tutorials.TourGuide- App.git – cd tutorials.TourGuide-App/ – docker-compose up orion – curl localhost:1026/version • Self-explanatory README.md at root directory • Open a Postman session and rock and roll – Postman collection: https://github.com/Fiware/tutorials.TourGuide-App/blob /develop/contrib/CampusParty2016.postman_collection
- 40. NGSI Go The NGSIGo is a command-line interface supporting FIWARE NGSIv2 API and Orion Admin API, which simplifies syntax. It's a powerful tool and easy to use. It has different commands for Orion as shown: – NGSI commands to manage NGSI Entity, subscription, registration – Admin commands for FIWARE Orion – Print version – Copy or remove entities at once – Create template of subscription or registration – Notification receiver – Integrated access token management for Keystone (Thinking Cities platform), Keyrock and so on. • Source code: https://github.com/lets-fiware/ngsi-go • How to install: https://github.com/lets-fiware/ngsi-go#install • Full documentation: https://ngsi-go.letsfiware.jp/ *NGSI Go is a third-party open-source software made by FIWARE community. 40
- 41. Would you liketo know more? 41 • References – This presentation, available at https://github.com/telefonicaid/fiware-orion#introduct ory-presentations – NGSIv2 Specification • https://github.com/telefonicaid/fiware-orion/blob/master/doc/ma nuals/orion-api.md – Documentation at ReadTheDocs • https://fiware-orion.readthedocs.io – Orion support through StackOverflow • Ask your questions using the “fiware-orion” tag • Look for existing questions at http://stackoverflow.com/questions/tagged/fiware-orion
- 42. Managing Context Informationat Large Scale: Advanced Topics Fermín Galán Márquez - fermin.galanmarquez@telefonica.com (Reference Orion Context Broker version: 4.1.0)
- 43. 43 Orion functionality 43 43 Pagination Metadata Compound attribute/metadatavalues Type browsing Geo-location Query filters DateTime support Custom notifications Notification status Attribute/metadata filtering Special attribute/metadata Registrations & context providers Multitenancy Creating & pulling data Pushing data Subscriptions & Notifications Batch operations Transient entities Oneshot subscriptions Subscription improvements Unrestricted text attributes Flow control MQTT notifications Update operators Subscription auto-disabling Subscription based in alteration type Covered subscriptions JEXL support in custom notifications
- 44. • Pagination • Metadata •Compound attribute/metadata values • Type browsing • Geo-location • Update operators • Query filters • DateTime support • Transient entities • Unrestricted text attributes • Flow control • Custom notifications • JEXL support in custom notifications • Notification status • Oneshot subscriptions • Subscription auto-disabling • Subscriptions based in alteration type • Covered subscriptions • MQTT notifications • Subscription improvements • Attribute/metadata filtering and special attribute/metadata • Registrations & context providers • Multitenancy • Service paths • CORS • Notifying services in private networks 44 Advanced Features
- 45. • Pagination helpsclients organize query and discovery requests with a large number of responses. • Three URI parameters: – limit • Number of elements per page (default: 20, max: 1000) – offset • Number of elements to skip (default: 0) – count (option) • Returns total elements (default: not return) 45 Pagination
- 46. • Example, queryingthe first 100 entries: – GET <orion_host>:1026/v2/entities?limit=100&options=count • The first 100 elements are returned, along with the following header in the response: – Fiware-Total-Count: 322 • Now we now there are 322 entities, we can keep querying the broker for them: – GET <orion_host>:1026/v2/entities?offset=100&limit=100 – GET <orion_host>:1026/v2/entities?offset=200&limit=100 – GET <orion_host>:1026/v2/entities?offset=300&limit=100 46 Pagination
- 47. • By default,results are ordered by entity creation date • This behavior can be overridden using orderBy URI parameter – A comma-separated list of attributes (including system/builtin attributes), id (for entity ID) and type (for entity type). Results are ordered by the first field. On ties, the results are ordered by the second field and so on. A "!" before the field name means that the order is reversed. • Example: get the first 20 entities ordered by temp in ascending order, then humidity in descending order GET <orion_host>:1026/v2/entities?limit=20&offset=0&orderBy=temp,!humidity • dateCreated and dateModified can be used to ordering by entity creation and modification date, respectively 47 Pagination
- 48. • Users mayattach metadata to attributes • Reserved metadata: dateCreated, dateModified, previousValue, actionType, ignoreType • By default, metadata are not removed on updates, except if overrideMetadata option is used • Examples: 48 … "temperature": { "type": "Float", "value": 26.5, "metadata": { "accuracy": { "type": "Float", "value": 0.9 } } } … … "temperature": { "type": "Float", "value": 26.5, "metadata": { "average": { "type": "Float", "value": 22.4 } } } … Metadata
- 49. Attributes • Name • Type •Value Entity • EntityId • EntityType Metadata • Name • Type • Value 49 Complete NGSI Model 1 n has 1 n has
- 50. • Attributes andmetadata can have a structured value. Vectors and key-value maps are supported. • It maps directly to JSON's objects and arrays. 50 Compound Attribute/Metadata Values
- 51. • Example: wehave a car whose four wheels' pressure we want to represent as a compound attribute for a car entity. We would create the car entity like this: { "type": "Car", "id": "Car1", "tirePressure": { "type": "kPa", "value": { "frontRight": 120, "frontLeft": 110, "backRight": 115, "backLeft": 130 } } } 51 Compound Attribute/Metadata Values
- 52. • GET /v2/types •Retrieve a list of all entity types currently in Orion, including their corresponding attributes and entities count • GET /v2/types/{typeID} • Retrieve attributes and entities count associated to an entity type PRO TIP GET /v2/contextTypes?options=values Retrieves just a list of all entity types without any extra info 52 Type Browsing
- 53. • Entities canhave an attribute that specifies its location – value: a JSON object in GeoJSON format – type: geo:json • Example: create an entity called Madrid …and create a couple more towns: • Leganés • Alcobendas POST <cb_host>:1026/v2/entities { "type": "City", "id": "Madrid", "position": { "type": "geo:json", "value": {"type": "Point", "coordinates": [ -3.691944, 40.418889] } } } 53 Geo-location null is also supported as value, meaning "no location". This may be useful in some cases.
- 54.
- 55. Geo-location – Maxdistance 13.5 km radius 55 GET <cb_host>:1026/v2/entities? type=City& georel=near;maxDistance:13500& geometry=point& coords=40.418889,-3.691944
- 56. Geo-location – Mindistance 13.5 km radius 56 GET <cb_host>:1026/v2/entities? type=City& georel=near;minDistance:13500& geometry=point& coords=40.418889,-3.691944
- 57. • Apart fromnear, the following georel can be used – georel=coveredBy – georel=intersects – georel=equals – georel=disjoint • See NGSIv2 Specification for a detailed description 57 More geo-relationships
- 58. • Regular attributeupdate uses particular values (eg. 12, "on", etc). • This can be inefficient and cause race conditions in some cases – Eg. several context producers updating a common counter attribute 58 Update operators CP A GET /v2/entity/E/attrs/count CP B count = 10 Sum 2 Sum 3 GET /v2/entity/E/attrs/count 10 10 10 +2 = 12 10 +3 = 13 count = 12 count = 13 PUT /v2/entity/E/attrs/count (12) PUT /v2/entity/E/attrs/count (13) Final value is 13 but it should be 15! Calculation at CP: Calculation at CP:
- 59. • Update operatorscan be used in attribute updates • Eg. "increase the value of attribute by 2" • Full list of current operators: – $inc: increase by a given value – $mul: multiply by a given value – $max, $min: max/min comparing provided and existing value – $push, $addToSet: add elements to array – $pull, $pullAll: remove elements from array – $set, $unset: add/remove sub-keys in object 59 Update operators … "count": { "type": "Number", "value": { "$inc": 2 } } …
- 60. • Simpler workfor context producers and avoiding race conditions – No need of calculation in context producers 60 Update operators CP A PUT /v2/entity/E/attrs/count {$inc: 2} CP B count = 10 Sum 2 Sum 3 count = 12 count = 15 Final result is correct PUT /v2/entity/E/attrs/count {$inc: 3}
- 61. • For theGET /v2/entities operation • By entity type • By entity id list • By entity id pattern (regex) • By entity type pattern (regex) • By geographical location – Described in detail in previous slides • Filters can be used simultaneously (i.e. like AND condition) 61 GET <cb_host>:1026/v2/entities?type=Room GET <cb_host>:1026/v2/entities?id=Room1,Room2 GET <cb_host>:1026/v2/entities?idPattern=^Room[2-5] GET <cb_host>:1026/v2/entities?typePattern=T[ABC] Query filters
- 62. • By attributevalue (q) • By metadata value (mq) • See full details about q and mq query language in NGSIv2 specification 62 GET <cb_host>:1026/v2/entities?q=temperature>25 GET <cb_host>:1026/v2/entities?q=tirePressure.frontRight >130 attribute name attribute sub-key (for compound attribute values only) GET <cb_host>:1026/v2/entities?mq=temperature.avg>25 GET <cb_host>:1026/v2/entities?mq=tirePressure.accuracy.frontRight >90 metadata sub-key (for compound metadata values only) attribute name metadata name Query filters
- 63. 63 POST <cb_host>:1026/v2/subscriptions … { "subject": { "entities":[ { "id": “Car5", "type": "Car" }, { "idPattern": "^Room[2-5]", "type": "Room" }, { "id": "D37", "typePattern": "Type[ABC]" }, ], "condition": { "attrs": [ "temperature" ], "expression": { "q": "temperature>40", "mq": "humidity.avg==80..90", "georel": "near;maxDistance:100000", "geometry": "point", "coords": "40.418889,-3.691944" } } }, … } • Filters can be also used in subscriptions – id – type – id pattern – type pattern – attribute values – metadata value – geographical location Query filters
- 64. • Orion implementsdate support – Based on ISO ISO8601 format with milliseconds precision, including partial representations and timezones • See https://github.com/telefonicaid/fiware-orion/blob/master/d oc/manuals/orion-api.md#datetime-support for syntax details • null is also supported meaning "no date" – Use reserved attribute type DateTime to express a date – Date-based filters are supported 64 Datetime support
- 65. • Attribute valuearithmetic filters can be used with dates as if they were numbers • Entity dateModified and dateCreated special attributes, to get entity creation and last modification timestamps – They are shown in query responses using attrs=dateModified,dateCreated • Entity dateModified and dateCreated special metadata, to get attribute creation and last modification timestamps – They are shown in query responses using metadata=dateModified,dateCreated 65 POST /v2/entities … { "id": "John", "birthDate": { "type": "DateTime", "value": "1979-10-14T07:21:24.238Z" } } GET /v2/entities?q=birthDate<1985-01-01T00:00:00 Example: create entity John, with birthDate attribute using type DateTime Datetime support
- 66. • Orion willautomatically delete the entity, once dateExpires time is reached – In fact transient entities may remain in the database up to 60 seconds (or a bit more, if the database load is high) after expiration date • BE CAREFUL! Entities removed this way cannot be recovered • As dateModified and dateCreated (previously described), dateExpires is not retrieved by default – It is shown in query responses using attrs=dateExpires • dateExpires can be used as any othe DatetTime attribute in filter, e.g.: 66 POST /v2/entities … { "id": "Warning1", "dateExpires": { "type": "DateTime", "value": “2018-07-30T12:00:00Z" } } GET /v2/entities?q=dateExpires<2018-08-01T00:00:00 Example: create entity Warning1, to expire at noon on July 30th , 2018 Transient entities
- 67. • By default,Orion limits the set of allowed chars in order to avoid injection attacks – List of forbidden chars: https://github.com/telefonicaid/fiware-orion/blob/maste r/doc/manuals/orion-api.md#general-syntax-restrictions • You can avoid this check in attribute values using the special attribute type TextUnrestricted • Use it at your own risk! 67 Unrestricted text attributes … "description": { "type": "TextUnrestricted", "value": "Hey! I'm using <forbidden chars>" } …
- 68. • By default,Orion updates responses are decoupled from the sending of the notifications triggered by these updates • This may cause that if the client sending updates is much faster than the receiver processing notifications, saturation will happen 68 Flow control Client Receiver … client sending updates too fast at some point in time, Orion notification queue will saturate and new notifications will be discarded receiver is not so fast …
- 69. • Orion canimplement a flow control mechanism, based in the -notifFlowControl CLI option and flowControl option in update requests • Using flow control, Orion doesn’t response updates immediately. It introduces a delay based on occupation size of the notification queue (the more the occupation, the more the delay) 69 Flow control Client Receiver … … ?options=flowControl delays introduced by Orion
- 70. • More informationon flow control – Functionality description: https://fiware-orion.readthedocs.io/en/master/admin/pe rf_tuning/index.html#updates-flow-control-mechanism – Detailed example/tutorial: https://github.com/telefonicaid/fiware-orion/blob/maste r/test/flowControlTest/README.md 70 Flow control
- 71. • Apart fromthe standard formats defined in the previous slides NGSIv2 allows to re-define all the notification aspects • httpCustom is used instead of http, with the following subfields – URL query parameters – HTTP method – HTTP headers – Payload (not necessarily JSON!) • A simple macro substitution language based on ${..} syntax can be used to “fill the gaps” with entity data (id, type or attribute values) and extra information (service, servicePath or authToken) – Exception: this cannot be used in HTTP method field 71 Custom notifications
- 72. 72 … "httpCustom": { "url": "http://foo.com/entity/${id}", "headers":{ "Content-Type": "text/plain" }, "method": "PUT", "qs": { "type": "${type}" }, "payload": "The temperature is ${temp} degrees" } … PUT http://foo.com/entity/DC_S1-D41?type=Room Content-Type: text/plain Content-Length: 31 The temperature is 23.4 degrees PUT /v2/entities/DC_S1-D41/attrs/temp/value?type=Room … 23.4 Custom notification configuration update notification Custom notifications Text based payload
- 73. 73 … "httpCustom": { "url": "http://foo.com/entity/${id}", "method":"PUT", "qs": { "type": "${type}" }, "json": { "t": "${temp}", "s": "${status}" } } … PUT http://foo.com/entity/DC_S1-D41?type=Room Content-Type: application/json Content-Length: 19 { "t": 23.4, "s": "on"} PUT /v2/entities/DC_S1-D41/attrs?type=Room … { "temp": {"value": 23.4, "type": "Number"}, "status": {"value": "on", "type": "Text"} } Custom notification configuration update notification Custom notifications JSON based payload
- 74. 74 … "httpCustom": { "url": "http://foo.com/entity/${id}", "method":"PUT", "ngsi": { "id": "stamp:${id}" "A:map": { "value": "${A}", "type": "Text"} "oldId": { "value": "${id}", "type": "Text"} } } … PUT http://foo.com/entity/DC_S1-D41 Content-Type: application/json Content-Length: 140 { "id": "stamp:DC_S1-D41", "A": { "value": "foo", "type": "Text" }, "A:map": { "value": "foo", "type": "Text" }, "oldId": { "value": "DC_S1-D41", "type": "Text" } } PUT /v2/entities/DC_S1-D41/attrs?type=Room … { "A": {"value": "foo", "type": "Text"} } Custom notification configuration update notification Custom notifications NGSI patching in payload Notification uses NGSIv2 compliant format (as in regular notifications)!
- 75. 75 … "httpCustom": { "url": "http://foo.com/entity/${id}", "method":"PUT", "ngsi": { "id": "stamp:${id}" "product": { "value": "${A*B}", "type": "Text"}} } … PUT http://foo.com/entity/DC_S1-D41 Content-Type: application/json Content-Length: … { "id": "stamp:DC_S1-D41", "A": { "value": 10, "type": "Number" }, "B": { "value": 5, "type": "Number" }, "product": { "value": 50, "type": "Number" }, } PUT /v2/entities/DC_S1-D41/attrs?type=Room … { "A": {"value": 10, "type": "Number"}, “B": {"value": 5, "type": "N"}} Custom notification configuration update notification JEXL Support in Custom notifications Not only basic replacement, but also JEXL expressions Not only for NGSI patching, also supported in payload and json
- 76. JEXL Support inCustom notifications A more evolved case speed: "10 m/s" count: {"count":5, "sum":100} code: null value: 14 max: 50 speed:"${(speed|split(' ')[0])|parseInt}" ratio: "${count.sum/count.count}" code: "${code||'invalid}" alert: "${(value>max)?'nok':'ok’}” count: "${{count:count.count+1, sum:count.sum+((speed|split(' '))[0] |parseInt)}}" speed: 10 ratio: 20 code: "invalid" alert: "ok" count: {"count":6, "sum":110} Entity update Subscription Custom Notification 76
- 77. JEXL Support inCustom notifications A more evolved case speed:"30 m/s" count: {"count":5, "sum":500} code: 456 value: 75 max: 50 speed:"${(speed|split(' ')[0])|parseInt}" ratio: "${count.sum/count.count}" code: "${code||'invalid}" alert: "${(value>max)?'nok':'ok’}” count: "${{count:count.count+1, sum:count.sum+((speed|split(' '))[0] |parseInt)}}" speed: 30 ratio: 100 code: 456 alert: "nok" count: {"count":6, "sum":530} Entity update Subscription Custom Notification 77
- 78. JEXL Support inCustom notifications Available transformations • uppercase • lowercase • split • indexOf • len • trim • substring • includes • isNaN • parseInt • parseFloat • typeOf • toString • toJson • floor • ceil • round • toFixed • log • log10 • log2 • sqrt • replaceStr • replaceRegex • matchRegex • mapper • thMapper • values • keys • arrSum • arrAvg • now • toIsoString • getTime Full detail at https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#available-transformations 78
- 79. JEXL Support inCustom notifications Chained expressions and evaluation priority 79 … "httpCustom": { ... "ngsi": { "A": { "value": "${16|sqrt}", "type": "Calculated" }, "B": { "value": "${A/100}", "type": "Calculated" } } }… "httpCustom": { ... "ngsi": { "A": { "value": "${16|sqrt}", "type": "Calculated", "metadata": { "evalPriority": { "value": 1, "type": "Number" } } }, "B": { "value": "${A/100}", "type": "Calculated" } }} X • Expression result of one expression can be used in other expressions • Use evalPriority metadata to specify evaluation order
- 80. JEXL Support inCustom notifications Attribute metadata is also added to JEXL context 80 speed: 30 diff:"${(speed-metadata.speed.previousValue}" speed: 30 diff: … Entity update Subscription Custom Notification speed: 40 speed: 35 speed: 37 speed: 40 diff: 10 speed: 35 diff: -5 speed: 37 diff: 2
- 81. • Detailed informationin the notifications element – timesSent: total number of notifications attempts (both successful and failed) – failsCounter: number of consecutive notifications fails • failsCounter > 0 means subscription is in failing state – lastSuccess: last time that notification was successfully sent – lastFailure: last time that notification was tried and failed – lastNotification: last time the notification was sent (either success or failure) • Corollary: lastNotification value is the same than either lastFailure or lastSuccess – lastFailureReason: cause of last failure (text) – lastSuccessCode: the HTTP code (number) returned by receiving endpoint last time a successful notification was sent • lastSuccessCode and lastFailureReason fields only in HTTP notifications (not in MQTT ones) 81 200 OK Content-Type: application/json … [{ "id": " 51c0ac9ed714fb3b37d7d5a8 ", "status": "active", "subject": { … }, "notification": { "timesSent": 3, "failsCounter": 1, "lastNotification": "2016-05-31T11:19:32.000Z", "lastSuccess": "2016-05-31T10:07:32.000Z", "lastFailure": "2016-05-31T11:19:32.000Z", "lastSuccessCode": 200, "lastFailureReason": "Timeout was reached", … } }] Notification status
- 82. 82 Notification diagnosis workflow "status"field value? "lastSuccessCode“ field value? Subscription is inactive so notifications are not being sent. Update subscription to activate it. Notifications are being sent and the receiving endpoint confirms correct reception. Notifications are being sent but the receiving endpoint is reporting HTTP error. Check receiving endpoint (e.g. logs, etc.) Some problem is precluding notifications to be sent. In HTTP subscriptions, the "lastFailureReason" field value should provide additional information on it. inactive Subscription is expired so notifications are not being sent. Update subscription to make it permanent or extend expiration time expired active/oneshot YES 2xx 4xx, 5xx Only for HTTP notifications failsCounter > 0? NO
- 83. • A variantof the active status, so when the subscription is triggered one time (i.e. a notification is sent) it automatically steps to inactive status • An inactive subscription can step to oneshot, starting again the process 83 Oneshot subscription 200 OK Content-Type: application/json … [{ "id": "51c0ac..", "status": "oneshot", … } }] 200 OK Content-Type: application/json … [{ "id": "51c0ac..", "status": "inactive", … } }] Subscription is triggered PATCH /v2/subscriptions/51c0ac.. { "status": "oneshot" }
- 84. • A maxFailsLimitcan be specified for subscriptions so when the number of consecutive notifications overpasses that value, the subscription automatically passes to inactive state • failsCounter is reset to 0 whenever a successful notification is sent • This allow to protect Orion against failing notification endpoints what would consume notification resources (pool workers, etc.) • When a subscription is auto-disabled, a trace about it is printed in logs: 84 Subscription auto-disabling POST /v2/subscriptions { "subject": { … }, "notification": { "maxFailsLimit": 3, … } } failsCounter > maxFailsLimit => status := inactive time=... | lvl=WARN | ... | msg= Subscription 51c0ac9ed714fb3b37d7d5a8 automatically disabled due to failsCounter (4) overpasses maxFailsLimit (3)
- 85. • By default,subscriptions are triggered when entities are created or changed (i.e. update with a value different from the previous value) • This can be changed with alterationTypes field (within condition) to specify a list of the following (OR condition): – entityUpdate: entity update (no matter if is actually changed or not) – entityChange: entity actual change – entityCreate: entity is created – entityDelete: entity is deleted • The alteration type which triggered the subscription can be included in notifications by adding the special alterationType attribute (which possible values are the same tokens above) 85 Subscriptions based in alteration type POST /v2/subscriptions { "subject": { … "condition": { "alterationTypes": ["entityCreate","entityDelete"] } }, "notification": { … "attrs": [ "alterationType", "*" ] } }
- 86. • By default,attributes that doesn't exist in the entity are not notified • This can be changed with covered field (within notification) set to true to specify that non existing attributes has to be notified – As they don't exist, they use null as value • We use the term "covered" in the sense the notification "covers" completely all the attributes in the attrs field within notification • This feature can be useful for those notification endpoints that are not flexible enough for a variable set of attributes and needs always the same set of incoming attributes in every received notification 86 Covered subscriptions
- 87. 87 Covered subscriptions SUB 1: "notification":{ ... "attrs": [ "temp", "hum" ] } SUB 2 (covered) "notification": { ... "attrs": [ "temp", "hum ], "covered": true } POST /v2/entities/E/attrs/temp { ... "value": 19, "type": "Number" } NOTIF1: … { … "temp": { "type": "Float", "value": 19, "metadata": {} } } NOTIF2 (covered) … { … "temp": { "type": "Number", "value": 19, "metadata": {} }, "hum": { "type": "None", "value": null, "metadata": {} } }
- 88. • Using mqttinstead of http in the subscription payload • Taking advantage of MQTT features (shared subscriptions, QoS, retain, etc.) • MQTT authentication based in user/password is supported • Efficient connection management (removing idle connections to MQTT brokers if they are not in use, base din -mqttMaxAge) • Also supporting custom notifications (mqttCustom) 88 MQTT notifications POST <cb_host>:1026/v2/subscriptions … { "subject": { "entities": [ { "idPattern": ".*" } ], }, "notification": { "mqtt": { "url": "mqtt://<mqtt_broker>:1883", "topic": "/notif", "qos": 1 } } } Context Broker MQTT Broker … MQTT broker subscribers
- 89. • By defaultupdates not actually changing attribute value don’t trigger notification but this behavior can be overridden by the forcedUpdate URI param option, eg.: – PATCH /v2/entities/E/attrs?options=forcedUpdate – PUT /v2/entities/E/attrs/A?options=forcedUpdate – POST /v2/op/update?options=forcedUpdate • onlyChangedAttributes (within notification) can be set to true in order to notify only attributes that change (in combination with the ones specified in attrs or exceptAttrs) • notifyOnMetadataChange (within condition) can be set to false so metadata is not considered part of the value of the attribute in the context of notification (so if the value doesn't change but the metadata changes notification is not triggered) • Per-subscription notification timeout can be specified for HTTP subscriptions in timeout field (within http/httpCustom within notification) 89 Additional subscription improvements
- 90. • By defaultall attribute are included in query responses or notifications • The attrs field (as parameter in GET operations and as notification sub-field in subscriptions) can be used to specify a filtering list • The attrs field can be also used to explicitly include some special attributes (not included by default) – dateCreated, dateModified, dateExpires: described in previous slide • The “*” can be used as an alias of “all the (regular) attributes” 90 Attributes filtering and special attributes
- 91. • Examples – Includeonly attributes temp and lum • In queries: GET /v2/entities?attrs=temp,lum • In subscriptions: "attrs": [ "temp", "lum" ] – Include dateCreated and not any other attribute • In queries: GET /v2/entities?attrs=dateCreated • In subscriptions: "attrs": [ "dateCreated" ] – Include dateModified and all the other (regular) attributes • In queries: GET /v2/entities?attrs=dateModified,* • In subscriptions: "attrs": [ "dateModified", "*" ] – Include all attributes (same effect that not using attrs, not very interesting) • In queries: GET /v2/entities?attrs=* • In subscriptions: "attrs": [ "*" ] 91 Attributes filtering and special attributes
- 92. • By defaultall attribute metadata are included in query responses and notifications • The metadata field (as parameter in GET operations and as notification sub-field in subscriptions) can be used to specify a filtering list • The metadata field can be also used to explicitly include some special metadata (not included by default) – dateCreated, dateModified: described in previous slide – actionType: which value is the action type corresponding to the update triggering the notification: “update”, “append” or “delete” (*) – previousValue: which provides the value of the attribute previous to processing the update that triggers the notification • The “*” can be used as an alias of “all the (regular) metadata” 92 (*) actionType “delete” not yet supported by Orion in 4.1.0. Metadata filtering and special metadata
- 93. • Examples – Includeonly metadata MD1 and MD2 • In queries: GET /v2/entities?metadata=MD1,MD2 • In subscriptions: "metadata": [ "MD1", "MD2" ] – Include previousValue and not any other metadata • In queries: GET /v2/entities?metadata=previousValue • In subscriptions: "attrs": [ "previousValue" ] – Include actionType and all the other (regular) metadata • In queries: GET /v2/entities?metadata=actionType,* • In subscriptions: "attrs": [ "actionType", "*" ] – Include all metadata (same effect that not using metadata, not very interesting) • In queries: GET /v2/entities?metadata=* • In subscriptions: "metadata": [ "*" ] 93 Metadata filtering and special metadata
- 94. • Uncached queriesand updates 94 Application ContextBroker ContextProvider 1. register(provider= ) db 2. query 3. query 4. data 5. data Context Consumer Registration & Context Providers
- 95. POST <cb_host>:1026/v2/registrations … { "description": "Registrationfor Car1", "dataProvided": { "entities": [ { "id": "Car1", "type": "Car" } ], "attrs": [ "speed" ] }, "provider": { "http": { "url": "http://contextprovider.com/Cars" }, "legacyForwarding": true } } 201 Created Location: /v2/registrations/5a82be3d093af1b94ac0f730 … 95 Registration & Context Providers (*) With some limitations in current Orion version, see https://github.com/telefonicaid/fiware-orion/blob/master/doc/manuals/orion-api.md#registration-implementatio n-differences
- 96. 96 GET <cb_host>:1026/v2/entities/Car1/attrs ContextBroker ContextProvider db query data 200OK Content-Type: application/json ... { "type": "Float", "value": 110, "metadata": {} } Registration & Context Providers ?options=skipForwarding can be used to avoid query forwarding, in which case query is evaluated using exclusively Context Broker local context information
- 97. • Simple multitenantmodel based on logical database separation. • It eases tenant-based authorization provided by other components. • Just use an additional HTTP header called "Fiware-Service", whose value is the tenant name. Example: Fiware-Service: Tenant1 Context Broker Tenant 1 Tenant 2 … 97 Multitenancy
- 98. • A servicepath is a hierarchical scope assigned to an entity at creation time (with POST /v2/entities). 98 Service Paths
- 99. • In orderto use a service path we put in a new HTTP header called "Fiware- ServicePath". For example: Fiware-ServicePath: /Madrid/Gardens/ParqueNorte/Parterre1 • Special servicePath attribute can be used to retrieve entity service path along any other attribute – E.g. GET /v2/entities?attrs=servicePath,* • Properties: – A query on a service path will look only into the specified node – Use "ParentNode/#" to include all child nodes – Queries without Fiware-ServicePath resolve to "/#" – Entities will fall in the "/" node by default ParqueNorte Parterre2 Parterre1 ParqueOeste ParqueSur 99 Service Paths
- 100. • Properties (continued): –You can OR a query using a comma (,) operator in the header • For example, to query all street lights that are either in ParqueSur or in ParqueOeste you would use: ServicePath: Madrid/Gardens/ParqueSur, Madrid/Gardens/ParqueOeste • You can OR up to 10 different scopes. – Maximum scope levels: 10 • Scope1/Scope2/.../Scope10 – You can have the same element IDs in different scopes (be careful with this!) – You can't change scope once the element is created – One entity can belong to only one scope – It works not only with queries, but also with subscriptions/notifications – It works not only in NGSI10, but also with registrations/discoveries (NGSI9) ParqueNorte Parterre1 light1 light1 A B A or B 100 Service Paths
- 101. • Useful forprogramming clients that run entirely in browser without backend – Full support (including pre-flight requests) in NGSIv2 – Partial support (only for GET requests) in NGSIv1 • CLI parameters related with CORS – -corsOrigin – -corsMaxAge • See details – https://fiware-orion.readthedocs.io/en/master/user/cors/in dex.html Cross-Origin Resource Sharing (CORS)
- 102. 102 Context Consumer notify Context Broker PrivateNetwork Context Consumer notify Context Broker Private Network ./ngrok http 8080 http://9762d35a.ngrok.io n o ti f y ngrok.io Notifying services in private networks
- 103. • References – Thispresentation, available at https://github.com/telefonicaid/fiware-orion#introduct ory-presentations – NGSIv2 Specification • https://github.com/telefonicaid/fiware-orion/blob/master/doc/ma nuals/orion-api.md – Documentation at ReadTheDocs • https://fiware-orion.readthedocs.io – Orion support through StackOverflow • Ask your questions using the “fiware-orion” tag • Look for existing questions at http://stackoverflow.com/questions/tagged/fiware-orion 103 Would you like to know more?
- 104.
- 105. Integration with existingsystems • Context adapters will be developed to interface with existing systems (e.g., municipal services management systems in a smart city) acting as Context Providers, Context Producers, or both • Some attributes from a given entity may be linked to a Context Provider while other attributes may be linked to Context Producers queryContext (e1, attr1, attr2) Context Provider queryContext (e1, attr1) Context Consumer updateContext (e1, attr2) Application Context Broker System B System A 105
- 106. Integration with sensornetworks • The backend IoT Device Management GE enables creation and configuration of NGSI IoT Agents that connect to sensor networks • Each NGSI IoT Agent can behave as Context Consumers or Context Providers, or both FIWARE Context Broker IoT Agent-1 IoT Agent-2 IoT Agent-n IoT Agent Manager create/monitor FIWARE Backend IoT Device Management OMA NGSI API (northbound interface) (southbound interfaces) MQTT ETSI M2M IETF CoAP 106
- 107. • Federation ofinfrastructures (private/public regions) • Automated GE deployment Cloud • Complete Context Management Platform • Integration of Data and Media Content Data • Easy plug&play of devices using multiple protocols • Automated Measurements/Action Context updates IoT • Visualization of data (operation dashboards) • Publication of data sets/services Apps • Easy support of UIs with advanced web-based 3D and AR capabilities • Visual representation of context information. Web UI • Advanced networking capabilities (SDN) and Middleware • Interface to robots I2ND • Security Monitoring • Built-in Identity/Access/Privacy Management Security Context Management in FIWARE 107
- 108. Context/Data Management Platform Applications OMANGSI-9/10 Processing/Analysis Algorithms Gathered data is injected for processing/analysis Distributed Context Sources Complex Event Processing (PROTON) BigData (COSMOS) Processed data is injected for processing/analysi s Data generated either by CEP or BigData is published Gathered data injected for CEP-like processing Direct bigdata injection Programming of rules 108 FI-WARE Context/Data Management Platform
- 109. • Used by/v2/op/update (batch operation) • Conventional actionTypes – append: to append (or update if the attribute already exists) – update: to update – delete: to delete • Special actionTypes – appendStrict: strict append (returns error if some of the attributes to add already exists) – replace: delete all the entity attributes, next append the ones in the update request 109 Special update action types
Editor's Notes
- #102 Alternatives to ngrok.io: http://localtunnel.me https://forwardhq.com