| Tutorial Source Code |
Examples referenced:
|
| Last Update | March 2022 |
| Compiler/Runtime | See Getting Started with TypeScript. |
| Pre-requisites | Enable the session environment as outlined within the Getting Started guide. |
Overview
Whether accessing from the desktop, directly to the cloud, or through your deployed managed streaming services, the Refinitiv Data Libraries provide ease-of-use interfaces to retrieve real-time streaming content from the platform. By utilizing streaming interfaces, developers can easily define properties to request, receive, and process market data in real-time.
The following tutorial requests for a small watchlist of instruments, retrieving level 1 (MarketPrice) streaming content that captures real-time events in user-defined callbacks. The Pricing interface provides the ability to define callback methods to capture market data events including the initial refresh, status events as well as updates, such as trades and quotes, based on changes in the market. The advantage of these capabilities is for applications to immediately respond to critical changes that drive real-time decisions within their application workflow.
Executing the Application
In our example, we're requesting to stream 3 instruments. The goal of the example is to demonstrate how to define callbacks for the different types of events that occur and how to responds to those events. The output provided below dumps the entire initial image captured within the refresh callback. In addition, as market conditions change, events will be sent to an update callback that will demonstrate how to pull out individual elements from the response for display purposes. Each update displays a simple line of text detailing the instrument as well as the fields updated.
To execute the example, refer to the pre-requisites section at the top of this tutorial.
The expected output should look similar to this:
How to request for streaming data and process real-time events
The following code segment requests for a small watchlist of items from the streaming services defined within the platform. The streaming interface provides the ability to define callbacks for the different types of events.
// specify a list of items and fields for which to retrieve streaming prices
const pricingDefinition = Pricing.Definition({
universe: ['EUR=', 'CAD=', 'GBP='],
fields: ['DSPLY_NAME', 'BID', 'ASK', 'OPEN_PRC', 'PCTCHNG']
});
const stream = pricingDefinition.getStream(session);
// attach event listeners to the stream
stream.onRefresh((refresh, instrument) => console.log(`Refresh for: ${instrument}:`, refresh))
.onUpdate((update, instrument) => console.log(instrument, update))
.onStatus((status, instrument) => console.log(`Status for: ${instrument}:`, status))
.onComplete(() => console.log('Stream refresh complete'))
.onError(err => console.log(err));
// open the stream in streaming mode
await stream.open();
The above code segment was intentionally broken out into 4 distinct steps for the purpose of explanation, but also provides flexibility when using the interfaces. In general, the above code performs the following:
- Define a Pricing request
The Pricing interface provides the ability to specify a list of instruments to stream. In addition, includes a number of other options, including the ability to specify a list of fields. It's worth noting that if no fields are specified in the definition, all available fields will be returned. While not specifying the fields is a convenient way to look at all available fields, in practice, it's best to limit the fieldset based on requirements to optimize performance.
- Retrieve a stream interface
Using the pricing definition, retrieve a streaming interface providing the ability to request and manage real-time streaming data.
- Define the callbacks
Using the stream interface, define the callbacks to capture the refresh image, updates as well as status messages. The refresh represents the complete image when you make your initial request. Depending on the list of instruments requested, there may be issues such as specifying an invalid instrument. In such a case, the refresh callback will not be called, but instead, the status callback will provide details why there was no initial image available, for example, an instrument that was not found or one in which you may not have permissions to access. Finally, the update callback will be used to capture real-time changes, such as new trades and quotes.
- Open the stream
Using the stream interface, open the stream. As outlined above when defining the callbacks, you will see 2 distinct actions. Specifically, the delivery of the initial refresh or status, and real-time updates based on changes in the live market.
The following code segment demonstrates how to process update message events:
// update parameter contains the JSON message with fieldname=value pairs
.onUpdate((update, instrument) => console.log(instrument, update))
Note: The above example does not demonstrate events that are generated within the status callback. For testing purposes, you can simply include an invalid instrument within the definition to demonstrate an example status message.
Closing the stream
When you wish to stop the flow of live updates, you will need to issue a close on the stream. The following code segment will close the stream:
// close the open stream
await stream.close();
As outlined in the Streaming Cache tutorial, the Pricing interface will automatically prepare and manage an internal cache of the items defined within the interface. In addition, will include other useful features such as adding and removing items from the cache. Depending on your requirements, you may only require the need to capture real-time events as outlined within this tutorial. If there is no need to utilize the cache feature, we would suggest using the OMM stream interface.
The Pricing interface defined within the Refinitiv Data Library includes other useful features, such as the ability to retrieve real-time prices available within the RDP snapshot pricing service. This capability can be extremely useful for users that may not have access to or require the need to stream prices through real-time streaming services. Refer to the tutorial package for additional examples. In addition, we encourage the use of IntelliSense documentation within your Visual Studio editor to discover other useful capabilities.