Orion Context Broker Basics Antriksh Mathur Orange Labs
Orion Context. Broker: Basics Antriksh Mathur Orange Labs (Reference Orion Context Broker version: 1. 15. 0) Presentation Date: 28 th November 2018
Introduction • • • Context Management in FIWARE Orion Context Broker Creating and pulling data Pushing data and notifications Batch operations 2
Being “Smart” requires first 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 Application standard API Context Information Users • Name-Surname • Birthday • Preferences • Location Boiler • Manufacturer • Last revision • Product id • temperature 3 Flowerpot • Humidity • Watering plan
Being “Smart” requires first 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 Application standard API Context Information Truck • Driver • Location • … Ship • Company • Speed • Location • … 4 Container • Dimension • Temperature • …
Being “Smart” requires first 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 Application standard API Context Information Citizen • Name-Surname • Birthday • Preferences • Location Bus • Location • No. passengers • Driver • Licence plate 5 Shop • Location • Business name • Franchise • offerings
Context Information Management in Smart Cities • • Systems dealing with management of city services or thirdparty 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 Big. Data analysis City Governance System Bus • Location • No. passengers • Driver • Licence plate Third-party Apps Context Information Citizen • Name-Surname • Birthday • Preferences • Location City Services 6 Shop • Location • Business name • Franchise • offerings City Services
Different sources of context 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 What’s the current temperature in place “X”? standard API Place = “X”, temperature = 30º It’s too hot! A sensor in a pedestrian street A person from his smartphone 7 The Public Bus Transport Management system
Different sources of context 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 What’s the current traffic in street “X”? Standard API Notify me the changes of traffic in street “X” Street = “X”, traffic = high The Public Bus Transport Management system A sensor in a pedestrian street 8 Citizen’s car app or smartphone
A non-intrusive approach is 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 attribute “location” attribute “driver” System A System B Context Producer Context Provider 9
Context Management in FIWARE • 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 NGSI API Context Broker Users • Name-Surname • Birthday • Preferences • Location Boiler • Manufacturer • Last revision • Product id • temperature 10 Flowerpot • Humidity • Watering plan
FIWARE NGSI: “The SNMP for Io. T” • Capturing data from, or Acting upon, Io. T devices becomes as easy as to read/change the value of attributes linked to context entities using a Context Broker PUT /v 2/entities/lamp 1/attrs/status/value “light on” GET /v 2/entities/lamp 1/attrs/presence. Sensor NGSI API Context Broker Issuing a get operation on the “presence. Sensor” attribute enables the application to get info about presence of people near the lamp Setting up the value of attribute “status” to “light on” triggers execution of a function in the Io. T device that switches the lamp on 11
Connecting to the Internet of Things • Capturing data from, or Acting upon, Io. T devices becomes as easy as to read/change the value of attributes linked to context entities using a Context Broker PUT /v 2/entities/lamp 1/attrs/status/value “watering” GET /v 2/entities/lamp 1/attrs/humidity NGSI API Context Broker Issuing a get operation on the “humidity” attribute enables the application to find out whether the plant has to be watered Setting up the value of attribute “status” to “watering” triggers execution of a function in the Io. T device that waters the plant 12
Orion Context Broker • 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: Entity • Entity. Id • Entity. Type Attributes has 1 n • Name • Type • Value (*) With some limitations in current Orion version, see https: //fiwareorion. readthedocs. io/en/master/user/ngsiv 2_implementa 1 ti 3 on_notes/index. html#registrations
Two “flavors” of NGSI API • • NGSIv 1 – Original NGSI RESTful binding of OMA-NGSI – Implemented in 2013 – Uses the /v 1 prefix in resource URL NGSIv 2 – • Simple things must be easy • Complex things should be possible • Agile, implementation-driven approach • Make it as developer-friendly as possible (RESTful, JSON, …) – Enhanced functionality compared with NGSIv 1 (eg. filtering) – Stable, ready for production, version already available – • A revamped, simplified binding of OMA-NGSI • Current NGSIv 2 version is Release Candidate 2018. 07 http: //telefonicaid. github. io/fiwareorion/api/v 2/stable • New features coming (http: //telefonicaid. github. io/fiware-orion/api/v 2/stable) Uses the /v 2 prefix in resource URL Introduction to NGSIv 2 – https: //docs. google. com/presentation/d/1_fv 9 d. B 5 jo. Cs. OCHlb 4 Ld 6 AQme. IYh. Dz. Hg. FHUWre. Gmv. KU/edit#slide=id. g 53 c 31 d 7074 fd 7 bc 7_0 14
NGSIv 2 status (AKA the “NGSIv 2 disclaimer”) • NGSIv 2 is in “release candidate” status – By "release candidate" we mean that the specification is quite stable – RC-2018 -07 is intended to be the last RC version, prior to the definitive final version – Thus, only minor editorial changes (typos, etc. ) are expected from now on. Changes in content and structure are not expected. 15
So… when should I use NGSIv 1 or NGSIv 2? • In general, it is always preferable to use NGSIv 2 • Even if you use NGSIv 1, you can still use NGSIv 2 advanced functionality – See “Considerations on NGSIv 1 and NGSIv 2 coexistence” section at Orion manual • For a NGSIv 1 -based version of this presentation have a look to – http: //bit. ly/fiware-orion-ngsiv 1 16
Orion Context Broker in a nutshell Orion Context Broker Context Consumers subscriptions Context Producers query 1026 update notify update 1026 notify update DB 17
Orion Context Broker – check health GET <cb_host>: 1026/version { "orion" : { "version" : "1. 15. 0", "uptime" : "0 d, 0 h, 0 m, 5 s", "git_hash" : ". . . ", "compile_time" : "nodate", "compiled_by" : "fermin", "compiled_in" : "centollo", "release_date" : "nodate", "doc" : "https: //fiware-orion. readthedocs. org/en/1. 15. 0/" } } 18
Orion Context Broker Basic Operations Entities • GET /v 2/entities • Retrieve all entities • POST /v 2/entities • Creates an entity • GET /v 2/entities/{entity. ID} • Retrieves an entity • DELETE /v 2/entities/{entity. ID} • Deletes an entity 19
Orion Context Broker Basic Operations Attributes • GET /v 2/entities/{entity. ID}/attrs/{attr. Name} • Retrieves an attribute’s data • PUT /v 2/entities/{entity. ID}/attrs/{attr. Name} • Updates an attribute’s data • DELETE /v 2/entities/{entity. ID}/attrs/{attr. Name} • Deletes an attribute • GET /v 2/entities/{entity. ID}/attrs/{attr. Name}/value • Retrieves an attribute’s value • PUT /v 2/entities/{entity. ID}/attrs/{attr. Name}/value • Updates an attribute’s value 20
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 update Context Producer query Context Broker 21 Context Consumer
Quick Usage Example: Car Create POST <cb_host>: 1026/v 2/entities Content-Type: application/json. . . You can add "? options=upsert" to the URL. In that case, the entity is updated if already exists. { "id": "Car 1", "type": "Car", "speed": { "type": "Float", "value": 98 } } 201 Created 22
Quick Usage Example: Car Speed Update (1) PUT <cb_host>: 1026/v 2/entities/Car 1/attrs/speed Content-Type: application/json. . . { "type": "Float", "value": 110 } In the case of id ambiguity, you can use "? type=Car" to specify entity type 204 No Content … 23
Quick Usage Example: Car Speed Query (1) GET <cb_host>: 1026/v 2/entities/Car 1/attrs/speed 200 OK Content-Type: application/json. . . { "type": "Float", "value": 110, "metadata": {} } You can get all the attributes of the entity using the entity URL: GET/v 2/entities/Car 1/attrs 24
Quick Usage Example: Car Speed Update (2) PUT <cb_host>: 1026/v 2/entities/Car 1/attrs/speed/value Content-Type: text/plain. . . 115 204 No Content … 25
Quick Usage Example: Car Speed Query (2) GET <cb_host>: 1026/v 2/entities/Car 1/attrs/speed/value Accept: text/plain 200 OK Content-Type: text/plain. . . 115. 000000 26
Quick Usage Example: Room Create (1) POST <cb_host>: 1026/v 2/entities Content-Type: application/json. . . { "id": "Room 1", "type": "Room", "temperature": { "type": "Float", "value": 24 }, "pressure": { "type": "Integer", "value": 718 } } 201 Created. . . 27
Quick Usage Example: Room Update (1) PATCH<cb_host>: 1026/v 2/entities/Room 1/attrs Content-Type: application/json. . . { "temperature“: "type": "value": 25 }, "pressure": { "type": "Integer", "value": 720 } { "Float", } 204 No Content … 28
Quick Usage Example: Room Query (1) GET <cb_host>: 1026/v 2/entities/Room 1/attrs 200 OK Content-Type: application/json. . . { "pressure": { "type": "Integer", "value": 720, "metadata": {} }, "temperature": { "type": "Float", "value": 25, "metadata": {} } } 29
Quick Usage Example: Room Query (2) GET <cb_host>: 1026/v 2/entities/Room 1/attrs? options=key. Values 200 OK Content-Type: application/json. . . { "pressure": 720, "temperature": 25 } 30
Quick Usage Example: Room Create (2) POST <cb_host>: 1026/v 2/entities Content-Type: application/json. . . { "id": "Room 2", "type": "Room", "temperature": { "type": "Float", "value": 29 }, "pressure": { "type": "Integer", "value": 730 } } 201 Created. . . 31
Quick Usage Example: Filters (1) GET <cb_host>: 1026/v 2/entities? options=key. Values&q=temperature>27 200 OK Content-Type: application/json. . . [ { "id": "Room 2", "pressure": 730, "temperature": 29, "type": "Room" } ] 32
Quick Usage Example: Filters (2) GET <cb_host>: 1026/v 2/entities? options=key. Values&q=pressure==715. . 725 200 OK Content-Type: application/json. . . The full description of the Simple Query Language for filtering can be found in the NGSIv 2 Specification document [ { "id": "Room 1", "pressure": 720, "temperature": 25, "type": "Room" } ] 33
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 Application sub. Id = subscribe. Context (consumer, expiration) notify (sub. Id, data/context) Context Consumer Context Broker 34
Quick Usage Example: Subscription POST <cb_host>: 1026/v 2/subscriptions Content-Type: application/json … { "subject": { "entities": [ { "id": "Room 1", "type": "Room" } ], "condition": { "attrs": [ "temperature" ] } }, "notification": { "http": { "url": "http: //<host>: <port>/publish" }, "attrs": [ "temperature" ] }, } "expires": "2026 -04 -05 T 14: 00. 00 Z" 201 Created L cation: /v 2/subscriptions/51 c 0 ac 9 ed 714 fb 3 b 37 d 7 d 5 a 8 o. . . 35
Quick Usage Example: Notification 25 19 36
Quick Usage Example: Notification POST/publish HTTP/1. 1 Content-type: application/json; charset=utf-8 Ngsiv 2 -Attrs. Format: normalized … { "subscription. Id": "574 d 720 dbef 222 abb 860534 a", "data": [ { "id": "Room 1", "type": "Room", "temperature": { "type": "Float", "value": 19, "metadata": {} } } ] } 37
List existing subscriptions GET <cb_host>: 1026/v 2/subscriptions The full description of the subscription object (including all its fields) can be found in the NGSIv 2 Specification 200 OK Content-Type: application/json … [{ "id": " 51 c 0 ac 9 ed 714 fb 3 b 37 d 7 d 5 a 8 ", "expires": "2026 -04 -05 T 14: 00. 00 Z", "status": "active", "subject": { "entities": [{ "id": "Room 1", "type": "Room" }], "condition": { "attrs": ["temperature"] } }, "notification": { "times. Sent": 3, "last. Notification": "2016 -05 -31 T 11: 19: 32. 00 Z", "last. Success": "2016 -05 -31 T 11: 19: 32. 00 Z", "attrs": ["temperature"], "attrs. Format": "normalized", "http": { "url": "http: //localhost: 1028/publish" } } }] 38
Orion Context Broker batch operations • Batch query and batch update • They are equivalent in functionality to previously described RESTful operations • All them use POST as verb and the /v 2/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 39
Batch Operation Example: Create Several Rooms … POST<cb_host>: 1026/v 2/op/update Conten-Type: application/json. . . { "type": "Room", "id": "Room 4", "temperature": { "value": 31. 8, "type": "Float" }, "pressure": { "value": 712, "type": "Integer" } { "action. Type": "append", "entities": [ { "type": "Room", "id": "Room 3", "temperature": { "value": 21. 2, "type": "Float" }, "pressure": { "value": 722, "type": "Integer" } }, … } ] } 201 Created. . . 40
Would you like to know more? • The easy way – – – • This presentation, available at https: //github. com/telefonicaid/fiwareorion#introductory-presentations Orion User Manual: google for “Orion FIWARE manual” and use the first hit Orion Catalogue page: google for “Orion FIWARE catalogue” and use the first hit References – Context. Broker Presentation : https: //edu. fiware. org/pluginfile. php/9508/mod_resource/content/1/Ori on%20 Context%20 Broker%20 Basic%20. pdf https: //www. slideshare. net/fermingalan/orion-context-broker-1150 – NGSIv 2 Specification • • http: //fiware. github. io/specifications/ngsiv 2/stable http: //fiware. github. io/specifications/ngsiv 2/latest • http: //bit. ly/ngsiv 2 -vs-ngsiv 1 • http: //www. slideshare. net/fermingalan/fiware-managing-context-information-at-largescale – NGSIv 2 for NGSIv 1 developers – This presentation – Orion Catalogue: • http: //catalogue. fiware. org/enablers/publishsubscribe-context-broker-orion-contextbroker 47 – Orion support trhough Stack. Overflow
Thank you! http: //fiware. org Follow @FIWARE on Twitter
- Slides: 42