![\"GitHub\"](\"https://fiware.github.io/tutorials.Context-Providers/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 104: Registering Context ProvidersThis tutorial builds on the Store entity created in the previous stock management example and enables a user to \nretrieve data about a store which is not held directly within the Orion Context Broker.
\nThe docker-compose file for this tutorial can be found on GitHub:
FIWARE 104: Registering Context Providers
\n\n\"Knowledge is of two kinds. We know a subject ourselves, or we know where we can find information about it.\"
\n— Samuel Johnson (Boswell's Life of Johnson)
\n
Within the FIWARE platform, an entity represents the state of a physical or conceptural object which exists in the real world. \nFor example, a Store is a real world bricks and mortar building.
\nThe context data of that entity defines the state of that real-world object at a given moment in time.
\nIn all of the tutorials so far, we are holding all of the context data for our Store entities directly within the Orion \nContext Broker, for example stores would have attributes such as:
\nurn:ngsi-ld:Store:002As you can see, most of these attributes are completely static (such as the location) and the others are unlikely to be\nchanged on a regular basis - though a street could be renamed, or the store name could be rebranded.
\nThere is however another class of context data about the Store entity which is much more dynamic, information such as:
\nThis information is always changing, and if it were held in a database, the data would always be out-of-date. To keep the context\ndata fresh, and to be able to retrieve the current state of the system on demand, new values for these dynamic data attributes will \nneed to be retrieved whenever the entity context is requested.
\nSmart solutions are designed to react on the current state of the real-world. They are \"aware\" since they rely on dynamic data readings from \nexternal sources (such social media, IoT sensors, user inputs). The FIWARE platform makes the gathering and presentation of real-time \ncontext data transparent, since whenever an NGSI request is made to the Orion Context\nBroker it will always return the latest context by combining the data held within its database along with real-time data readings from \nany registered external context providers.
\nIn order to be able to fulfil these requests, the Orion Context Broker, must first be supplied with two types of information:
\nWithin our simple stock management system, our Store entity currently returns id, name, address and location attributes. \nWe will augment this with additional real-time context data from the following free publicly available data sources:
The relationship between our entities is defined as shown:
\n![\"\"](\"https://fiware.github.io/tutorials.Context-Providers/img/entities.png\")
This application will only make use of one FIWARE component - the Orion Context Broker. Usage of the Orion Context Broker is sufficient for an application to qualify as “Powered by FIWARE”.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep persistence of the context data it holds. \nTo request context data from external sources, we will now need to add a simple Context Provider NGSI proxy.
\nTherefore, the architecture will consist of three elements:
\nSince all interactions between the elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Context-Providers/img/architecture.png\")
The necessary configuration information for the Context Provider NGSI proxy can be seen in the services section the of the associated docker-compose.yml file:
context-provider:\n image: fiware/cp-web-app:latest\n hostname: context-provider\n container_name: context-provider\n networks:\n - default\n expose:\n - \"3000\"\n ports:\n - \"3000:3000\"\n environment:\n - \"DEBUG=proxy:*\"\n - \"PORT=3000\" \n - \"CONTEXT_BROKER=http://orion:1026/v2\" \n - \"WUNDERGROUND_KEY_ID=<ADD_YOUR_KEY_ID>\"\n - \"TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>\"\n - \"TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>\"\nThe context-provider container is driven by environment variables as shown:
The other context-provider container configuration values described in the YAML file are not used in this tutorial.
The configuration information for MongoDB and the Orion Context Broker\nhas been described in a previous tutorial
\nTo keep things simple both components will be run using Docker. Docker is a container technology which allows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker applications. A YAML file is used configure the required\nservices for the application. This means all container sevices can be brought up in a single commmand. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found here
\nWe will start up our services using a simple bash script. Windows users should download cygwin to provide a command line functionality similar to a Linux distribution on Windows.
\nA simple nodejs Express application has been bundled as part of the repository. The application offers an NGSI v1 interface for four different context providers - the Weather Underground API, the Twitter Search API and two dummy data context providers - a static data provider (which always returns the same data) and a random data context provider (which will change every time it is invoked).
\nMore information about the proxy endpoints can be found here
\nReplace the placeholders in docker-compose.yml in the root of the repository with the values you obtain for your application:
environment:\n - \"DEBUG=proxy:*\"\n - \"WUNDERGROUND_KEY_ID=<ADD_YOUR_KEY_ID>\"\n - \"TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>\"\n - \"TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>\"\nIf you do not wish to sign-up for an API key, you can use data from the random data context provider instead.
\nAll services can be initialised from the command line by running the bash script provided within the repository:
\n./services create; ./services start;\nThis command will also import seed data from the previous Stock Management example on startup.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Context Providers","slug":"context-providers"},{"content":"Architecture","slug":"architecture"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Start Up","slug":"start-up"}],"owner":"513743","collectionId":"ce8cdaaf-e082-4860-854a-2d66a3854e51","publishedId":"RW1XLMKz","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"4C4C4C","highlight":"233C68"},"publishDate":"2020-01-02T11:02:46.000Z"},"item":[{"name":"Health Checks","item":[{"name":"Static Data Context Provider (Health Check)","id":"17ee9d41-b78f-4b6c-8d49-fdf7637f95e2","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3000/health/static","description":"This example returns the health of the Static Data Context Provider endpoint.
\nA non-error response shows that an NGSI proxy is available on the network and returning values.\nEach Request will return the same data.
\n","urlObject":{"protocol":"http","path":["health","static"],"host":["localhost:3000"],"query":[],"variable":[]}},"response":[],"_postman_id":"17ee9d41-b78f-4b6c-8d49-fdf7637f95e2"},{"name":"Random Data Context Provider (Health Check)","id":"b07bf5df-c6fb-40ac-9c45-1109246bc2ea","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3000/health/random","description":"This example returns the health of the Random Data Generator Context Provider endpoint.
\nA non-error response shows that an NGSI proxy is available on the network and returning values.\nEach Request will return some random dummy data.
\n","urlObject":{"protocol":"http","path":["health","random"],"host":["localhost:3000"],"query":[],"variable":[]}},"response":[],"_postman_id":"b07bf5df-c6fb-40ac-9c45-1109246bc2ea"},{"name":"Twitter API Context Provider (Health Check)","id":"00037fd1-6505-4b56-82b6-d63861eca32a","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:3000/health/twitter","description":"This example returns the health of the Twitter API Context Provider endpoint.
\nA non-error response shows that an NGSI proxy for the Twitter API is available on the network and returning values.
\nIf the proxy is correctly configured to connect to the Twitter API, a series of Tweets will be\nreturned.
\nThe Twitter API uses OAuth2:
\nThis example returns the health of the Weather API Context Provider endpoint.
\nA non-error response shows that an NGSI proxy for the Weather API is available on the network and returning values.
\nIf the proxy is correctly configured to connect to the Weather Underground API, the current weather in Berlin will be returned.
\nMost of the Weather API features require an API key.
\nSign up for a key at https://www.wunderground.com/weather/api/
\nFor more information see: https://www.wunderground.com/weather/api/d/docs?MR=1
\nThis example returns the health of the Cat Facts API Context Provider endpoint.
\nA non-error response shows that an NGSI proxy for the Cat Facts API is available on the network and returning values.
\nIf the proxy is correctly configured to connect to the Cat Facts API, a series of facts about cats will be returned.
\n","urlObject":{"protocol":"http","path":["health","catfacts"],"host":["localhost:3000"],"query":[],"variable":[]}},"response":[],"_postman_id":"b51782ce-4ae8-467c-8f10-591743c4962e"}],"id":"6bdafbe5-78b1-4ab7-911e-ac8d360cb21a","description":"The nodejs proxy application offers a health endpoint for each of the four context providers. Making a request to the appropriate endpoint will check that the provider is running and external data can be received. The application runs on port 3000.
This example uses the NGSI v2 op/query endpoint to request a temperature reading from the Static Data Generator Context Provider.
The response will return a object of type:Number and value:42
The Orion Context Broker will make similar requests to this op/query endpoint once a context provider has been registered.
It is possible for the Orion Context Broker to make a request for multiple data values. This example uses the NGSI NGSI v2 op/query endpoint to request temperature and relativeHumidity readings from the Random Data Generator Context Provider. The requested attributes are found within the attributes array of the POST body.
The response will return a object with values for both temperature and relativeHumidity
The Orion Context Broker will make similar requests to this op/query endpoint once a context provider has been registered.
This example uses the NGSI v2 op/query endpoint to request temperature and relativeHumidity readings from the Weather API Context Provider. The requested attributes are found within the attributes array of the POST body.
The Orion Context Broker will make similar requests to this op/query endpoint once a context provider has been registered.
This example uses the NGSI v2 op/query endpoint to request tweets from the Twitter API Context Provider. The requested attributes are found within the attributes array of the POST body.
The Orion Context Broker will make similar requests to this queryContext op/query once a context provider has been registered.
This example uses the NGSI v2 op/query endpoint to request tweets from the Twitter API Context Provider. The requested attributes are found within the attributes array of the POST body.
The Orion Context Broker will make similar requests to this op/query endpoint once a context provider has been registered.
Because the 3000 port of the Context Provider has been exposed outside of the Docker container, it is possible for curl to make requests directly to the Context Provider - this simulates the requests that would have been made by the Orion Context Broker. You can also simulate making the requests as part of the docker container network by running the appropriate/curl Docker image.
Firstly obtain the name of the network used within the Docker containers by running
\ndocker network ls\nThen run the following curl command including the --network parameter:
docker run --network fiware_default --rm appropriate/curl -X GET http://context-provider:3000/random/health\nAs you can see, within the network, the host name of the Context Provider is context-provider.
This example registers the Random Data Context Provider with the Orion Context Broker.
\nThe body of the request states that: \"The URL http://context-provider:3000/proxy/v1/random/weatherConditions is capable of providing relativeHumidity and temperature data for the entity called id=urn:ngsi-ld:Store:001.\"
The values are never held within Orion, it is always requested on demand from the registered context provider. Orion merely holds the registration information about which context providers can offer context data.
\nThis request will return with a 201 - Created response code. The Location Header of the response contains a path to the registration record held in Orion.
\n\n","urlObject":{"protocol":"http","path":["v2","registrations"],"host":["localhost:1026"],"query":[{"disabled":true,"description":{"content":"Note: if you have registered with the Weather API, you can retrieve live values for
\ntemperatureandrelativeHumidityin Berlin by placing the followingurlin theprovider:\n
\n- \n
http://context-provider:3000/proxy/v1/weather/weatherConditions
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"601852dd-2a33-4bbc-a458-644a604c983f"},{"name":"Register a Context Provider - Tweets","id":"a4f4d07f-aa8f-4d54-a55d-397dd829447d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"description\": \"Get Tweets for Store 1\",\n \"dataProvided\": {\n \"entities\": [\n {\n \"id\" : \"urn:ngsi-ld:Store:001\",\n \"type\": \"Store\"\n }\n ],\n \"attrs\": [\n \"tweets\"\n ]\n },\n \"provider\": {\n \"http\": {\n \"url\": \"http://context-provider:3000/catfacts/tweets\"\n },\n \"legacyForwarding\": false\n },\n \"status\": \"active\"\n}"},"url":"http://localhost:1026/v2/registrations","description":"This example registers the Cat Facts API Context Provider with the Orion Context Broker.
\nThe body of the request states that: \"The URL http://context-provider:3000/proxy/v1/catfacts/tweets is capable of providing tweets data for the entity called id=urn:ngsi-ld:Store:001.\"
The values are never held within Orion, it is always requested on demand from the registered context provider. Orion merely holds the registration information about which context providers can offer context data.
\nThis request will return with a 201 - Created response code. The Location Header of the response contains a path to the registration record held in Orion.
\n\n","urlObject":{"protocol":"http","path":["v2","registrations"],"host":["localhost:1026"],"query":[{"disabled":true,"description":{"content":"Note: if you have registered with the Twitter API, you can retrieve live values for
\ntweetsin Berlin by placing the followingurlin theprovider:\n
\n- \n
http://context-provider:3000/proxy/v1/twitter/tweets
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"a4f4d07f-aa8f-4d54-a55d-397dd829447d"},{"name":"Read a registered content provider","id":"e730ed8e-2138-4ef8-b130-824326486760","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:1026/v2/registrations/5addeffd93e53f86d8264521","description":"This example reads the registration data with the id 5addeffd93e53f86d8264521 from the context.
Registration data can be obtained by making a GET request to the /v2/registrations/<entity> endpoint.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"e730ed8e-2138-4ef8-b130-824326486760"},{"name":"List all registered content providers","id":"7a587072-8e4d-429d-b164-72ec06b514ca","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:1026/v2/registrations","description":"This example lists all registered context providers
\nFull context data for a specified entity type can be retrieved by making a GET request to the /v2/registrations/ endpoint.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"}],"variable":[]}},"response":[],"_postman_id":"7a587072-8e4d-429d-b164-72ec06b514ca"},{"name":"Remove a registered content provider","id":"9ec487c1-2d08-415f-bc5b-c8d2655b77d8","request":{"method":"DELETE","header":[],"body":{"mode":"formdata","formdata":[]},"url":"http://localhost:1026/v2/registrations/5ad5b9435c28633f0ae90671","description":"This example removes the registration with the id 5ad5b9435c28633f0ae90671 from the context.
Registrations can be deleted by making a DELETE request to the /v2/registrations/<entity> endpoint.
Subsequent requests using the same id will result in an error response since the entity no longer exists
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"9ec487c1-2d08-415f-bc5b-c8d2655b77d8"}],"id":"5d610d41-4779-4b65-91b1-31256c4e0eae","description":"All Context Provider Registration actions take place on the v2/registrations endpoint. The standatd CRUD mappings apply:
This example reads the full context from the Store entity with the id=urn:ngsi-ld:Store:001.
The relativeHumidity attribute is returned as part of the context for the entity because a context provider has been registered to provide that data.
This example reads the value of the relativeHumidity attribute from the Store entity with the id=urn:ngsi-ld:Store:001.
Data is returned in the context because a context provider has been registered to provide that data.
\n","urlObject":{"protocol":"http","path":["v2","entities","urn:ngsi-ld:Store:001","attrs","relativeHumidity","value"],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"b65ff3ae-0e19-44c6-adb7-78c64bac5973"}],"id":"1d9c46bf-7028-4a8c-aa6a-9e36bb9f06af","description":"Once a Context Provider has been registered, the new context data will be included in the response if the context of the associated entity is requested.
\n","event":[{"listen":"prerequest","script":{"id":"c43b57f2-84cc-4d57-8c6d-5b4260399699","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cc26f7d9-301c-48e2-891f-3c336c18fe96","type":"text/javascript","exec":[""]}}],"_postman_id":"1d9c46bf-7028-4a8c-aa6a-9e36bb9f06af"}],"event":[{"listen":"prerequest","script":{"id":"343e1af9-161c-4ec3-ba3a-a63bf0296b92","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"dc4dca7c-b13f-475e-888f-046dafbba038","type":"text/javascript","exec":[""]}}],"variable":[{"key":"orion","value":"localhost:1026","type":"string"},{"key":"context-provider","value":"localhost:3000","type":"string"}]}