In this video we're going to be discussing stream updates. Stream updates is a similar concept to
WebSockets in that it allows you to retrieve only new values from attributes and points as
events are added and the streams are updated. Stream updates relies on HTTP request to send
new values only when queried and only provides values since the last time the stream was queried.
This prevents you from having to pull more info than is needed and you won't need to maintain a
number of WebSocket connections to the PI Web API. Let's see what this looks like in action.
For stream updates we register a particular stream to receive updates from; this is done
by using the stream controller / the web ID of the stream followed by slash updates. I've
already selected the dummy tag cdt158 web ID for this example. Let's execute this request.
The response of the initial request is a status of whether or not updates were able to be subscribed
to on that stream. We see a 200 HTTP status which is good. We also see a field in the response
called status which says the registration succeeded as well. If you or another user
have already signed up for stream updates on this particular stream then the status will be already
registered. So let's make this request a second time just so we can see what this looks like.
We still have a 200 HTTP response code but as we mentioned, the status and the response body
has changed to already registered. Let's take a look at some of the other components of the
response we get when we're registering. We have a latest marker property being returned
to us. This marker keeps track of the last time we query the stream for updates. We
can hand this marker to the PI Web API when asking for updates and it will know where
in the stream was the last time we got updates. Let's use that marker to retrieve some updates.
The URL for this will be formatted as the base URL slash streams slash updates
slash the marker that was retrieved from the message in which we registered for updates.
We'll also need to change this from a post to a get request.
In this response we see there's been no events that have been added and as a result we see a
status of no change. We also see we have a latest marker property. This marker is different from
the one we used to make the request. We can compare this to the marker it's use as it's
shown later in the request as well. For this request I have ensured we've waited a little
bit of time so that the stream has had time to update. In the response we see an events
object with the typical event information: value, timestamp, questionable, substituted,
as well as what type of change was made. In this case all of the events were added though we could
have edited and deleted as possible actions if the changes were made to values in this stream.
If we scroll down we also see we have a latest marker property. This marker is different from
the one we use to make the request. We can compare it to the requesting marker or requested marker
also shown in the response. This new marker can be used to retrieve information from the
most recent query for updates moving forward. In other words if we use the latest marker to
query the stream we won't see updates from this response but rather updates that have occurred
since this response. Let's demonstrate this. We see that the timestamps are more recent than the
previous query using the other marker. One more detail I'd like to point out is that markers that
have existed for more than five minutes will expire and have their events cleaned up. For
this example I've registered for stream updates and used a marker that should now be expired.
When we hit execute we see we have a 404 response. Because the marker
is expired we no longer find data for that stream update.
We covered a lot of material in this video so let's summarize but first I'd like to go over some
of the benefits stream updates has to offer over channels. Stream updates has the benefit in that
it's fully based on the HTTP protocol which means it's compliant with claims based authentication
whereas channels are not. Additionally WebSockets aren't consistently supported in all production
environments. The stream updates model also allows for the client to request updates when it's ready
rather than requiring consistent poll to the channel or implementing a callback. Last but
certainly not least, stream updates have more desirable behavior in the event of a network
interruption between the client and the PI Web API. In stream updates and network interruption
may cause an individual HTTP GET requests to fail but the server will not lose updates or signup
contacts. This means that when subsequent HTTP GET calls are made successfully no data updates
are lost. If a channel fails the client needs to re-establish the connection and resend all web
IDs that need to be signed up. Data updates for those streams may be lost while this is occurring.
In this video we've registered for stream updates using a post to the updates endpoint
on the streams controller. We demonstrated the use of markers for retrieving new updates
and we noted the timeout period on markers is a default of 5 minutes. If you find that the cache
timeout is too short we would recommend using a GetRecorded call with start and end times.