Publish Events to Streaming via the REST Interface
How to use the Postman API test tool to publish input events to your streaming project via the streaming REST interface.
Prerequisites
Before you begin, make sure that your streaming server is running, and the Streaming Web Service (SWS) is running on the streaming server.
- Step 1
Streaming projects can expose REST and Web Socket interfaces, but this is not enabled by default. So your first step is to expose the REST interface for your
freezer_monitor
project.Note that this is technically not an adapter but a service provided by the streaming cluster. Therefore, you don’t add an http adapter to your project, but rather enable the project for Web Services.
In the Project Explorer view, double-click on the project configuration file
freezer_monitor.ccr
to open it in the configuration editor.Go to the Advanced tab and click on Project Deployment in the left pane of the configuration editor to display the project deployment details.
Set the Web Service Enabled property to
true
.Now close the Project Configuration editor and save the changes.
Finally:
- Re-start your project with the new configuration.
- Open the
MACHINEDATA
input stream in the Stream View. Later, after you post an event, you’ll be able to see data populate there.
Which of the following is not a tab in the Project Configurations page?
- Step 2
For this tutorial you need a way of creating the calls to send to the server. We created this tutorial using Postman, although you can use whatever REST client you like.
You can get Postman from http://www.postman.com/.
- Step 3
The
REST
andWeb Socket
interfaces for streaming projects are provided by the Streaming Web Service (SWS) - a service of the streaming cluster. At this point SWS should already be running on your streaming cluster. Let’s make sure you can connect to it.To do this, send a simple http GET request to the server.
GET http://<hostname>:9093/1/version
Here it is in Postman:
If successful, you should get a response that looks something like this:
{"version-string":"2.00.000.00/20161121.1/SP00/linux/x86_64/64-bit/OPT/Mon Nov 21 00:13:43 PST 2016"}
If you get an error indicating no response, then you aren’t able to connect to the SWS web server. Check the following:
- Double-check the IP address (or hostname) you are using in the http GET request.
- Confirm that the SWS web server is running.
- Step 4
Before you can publish messages, SWS requires that you request for a token for the specific resource you intend to access. The returned token then needs to be included in the headers of subsequent POSTs. To get an authorization token you need to send a POST request as follows:
POST http://<hostname>:9093/1/authorization
The header needs to include basic authorization credentials, where the username and password are
base64
encoded. So the header will look something like this:authorization: Basic U0RTX1VTRVI6UGFzc3dvcmQx
But Postman will construct this for you, and do the encoding. Just go to the Authorization tab, enter your credentials, and click “Update Request”.
Next, go to the Body tab, select raw, and enter the payload. For this test, you need to request a token that will allow you to publish to the
MACHINEDATA
stream of thefreezer_monitoring
project running under the default workspace. Copy this and paste it into the body:jsonCopy[ { "privilege":"write", "resourceType":"stream", "resource":"default/freezer_monitor/MACHINEDATA"} ]
It will look like this in Postman:
Send the request and if you authenticate successfully, and have permission to write to this stream, then the response will contain your authorization token. The response should look something like this:
[{"sws-token":"biVBFyKyPYgObPtmZc7y3ygn7e2hr4OoIQHjKtgQU1Hx75zunA3xDOBEQr08lCkhQFi4L7Ze9GNDb3rpNF1jEQ=="}]
Copy the token - you’ll need it in the next step. Don’t copy the full response, just the token and the surrounding quotes.
Note: The token is only valid for a set number of seconds, which is defined in streaming cluster configuration and can be changed from the HANA cockpit or using the command line tools. The default value is only 5 minutes. After this time period, a new token will need to be requested.
- Step 5
Now you’re ready to post your event to the
MACHINEDATA
input stream of thefreezer_monitor
project running in thedefault
workspace. The URL for this call looks like this:POST http://<hostname>:9093/1/workspaces/default/projects/freezer_monitor/streams/MACHINEDATA
The header needs to include your authorization token. In Postman, go to the Headers tab and click on Bulk Edit. Paste in your authorization token and then copy and add the header prefix shown below:
header prefix: authorization:SWS-Token "sws-token"=
The full header should look something like this:
authorization:SWS-Token "sws-token"="biVBFyKyPYgObPtmZc7y3ygn7e2hr4OoIQHjKtgQU1Hx75zunA3xDOBEQr08lCkhQFi4L7Ze9GNDb3rpNF1jEQ=="
Here’s how the header will look in Postman:
Since Postman does not offer a “Token” authorization type, you must change the type back to
No Auth
so your new token doesn’t get over-written back to aBasicAuth
. Go to the Authorization tab and selectNo Auth
from the dropdown menu.Then, go to the Body tab, select raw, and enter the payload below and then press Send.
jsonCopy[ {"ESP_OPS":"i", "MACHINEID":"1A", "EVENT_TIME": "2013-03-10T04:45:36.123", "EVENT_NAME":"DOOR", "EVENT_DESCRIPTION":"door open event", "EVENT_VALUE":"Door open"} ]
Here’s how the body will look in Postman:
The first part -
"ESP_OPS":"i"
- tells streaming that this is an insert event. Yourfreezer_monitor
project is only designed to process insert events. Streaming also supportsupdate
,upsert
, anddelete
events based on primary keys, but that’s beyond the scope of this tutorial.In studio, check the Stream View to see that your event arrived and was processed.
You can publish additional events if you like, simply by editing the body with different values. Note that for all the features of this demo project to work, you need to stick to these values:
MACHINEID
should be one of: 1A, 2B, 3C, 4D, 5E, 6F, 7G in order to successfully join to the HANA table containing reference data for each machineEVENT_NAME
should be one of:TEMP
,DOOR
, orPOWER
- For power events,
EVENT_VALUE
should be eitherPower on
orPower off
Also, here are some notes on the structure of the body:
The JSON message body can be sent in either of two formats:
- Map format
- Array format
Above we used the map format. Note that with the map format, you don’t have to include every field. Fields that are not included will be set to
NULL
. You can also include multiple events in a single POST like this:jsonCopy[ { "ESP_OPS":"<opcode>", "<field1>":<value1>, "<field2>":<value2>, … }, { "ESP_OPS":"<opcode>", "<field1>":<value1>, "<field2>":<value2>, … } ]
The structure of the array format is more compact (and a bit more efficient) but is less forgiving:
jsonCopy[ [ "<opcode>", <value1>, <value2>, <value3>, …], [ "<opcode>", <value1>, <value2>, <value3>, …] ]
With this method, every field must be sent a value, and the order they are typed must correspond to the schema.