In this tutorial we'll cover snapshots; their creation and parameters.
This section assumes a connection has been established; see the getting started tutorial as necessary.
Snapshot requests are used to retrieve current images of one or more topics.
A canonical snapshot requests a snapshot to a single topic. Each canonical snapshot request will receive a single response.
Here's an example of requesting the CSIQ.Q record from the activ data source using native symbology.
/* global activOneApi */
// You may have to update the userId and password fields below.
const user = "__ACTIV_SESSION_USER_ID__";
const password = "__ACTIV_SESSION_PASSWORD__";
const host = "aop-ny4-replay.activfinancial.com";
(async function() {
try {
const session = await activOneApi.connect({
host,
user,
password,
onLogMessage(logType, message) {
console.log(message);
}
});
// Initiate a snapshot request.
session.snapshot({
dataSourceId: activOneApi.DataSourceId.activ,
symbologyId: activOneApi.SymbologyId.native,
symbol: "CSIQ.Q"
},
{
onSnapshot (message) {
console.log(`Snapshot received for ${message.symbol}`);
// Iterate through the fields in the response.
for (const field of message.fieldData) {
console.log(`${activOneApi.FieldId[field.id]} = ${field.value}`);
}
},
onSnapshotFailure (message) {
console.log(`Failure: ${activOneApi.StatusCode[message.statusCode]}`);
}
});
} catch (e) {
console.error(`Failure: ${activOneApi.StatusCode[e]}`);
}
})();
A query snapshot can be used to request a snapshot of all topics that match a given query.
// With a connected session request a snapshot of all MSFT options using navigation.
session.querySnapshot({
dataSourceId: activOneApi.DataSourceId.activ,
symbol: "symbol=MSFT. navigate=option"
},
{
onSnapshot (message) {
console.log(`Snapshot received for ${message.symbol}`);
},
onSnapshotFailure (message) {
console.log(`Snapshot failure for ${message.symbol} with status ${activOneApi.StatusCode[message.statusCode]}`);
}
});The snapshot of each topic is requested from the platform independently. As such, each snapshot will be taken at a different moment in time. The time difference between snapshots depends on various factors including real-time data rates and the speed that the client application can process the results.
The results of a snapshot are notified via the callback handler provided when the snapshot was requested. The interface provides the following callbacks:
The data contained in the message can be accessed through the fieldData property. Details of how to use this can be found in the Field Data tutorial.
For a query snapshot success, or failure for a specific topic, the native symbol will be provided with the result message. For a general failure of the overall request (e.g. a request with an invalid query) the symbol will be empty.
If the snapshot method fails a StatusCode will indicate the cause of the failure.
Parameters define options that will be used when processing snapshot requests. For snapshots this allows for the definition of a field filter causing the returned snapshot to only contain the requested fields.
Parameters are relatively expensive to construct so should be reused where possible for efficiency. Rather than defining parameters for each snapshot request they are registered using the registerSnapshotParameters method. This returns a Handle that can be passed to multiple snapshot method calls. The Handle also manages the lifetime of the parameters. The handle should be deleted when it is no longer required, but must be kept open while it is in use by any open snapshot request.
Here is an example demonstrating how to request a snapshot for just the bid and ask fields for the CAJ.Q record.
/* global activOneApi */
// You may have to update the userId and password fields below.
const user = "__ACTIV_SESSION_USER_ID__";
const password = "__ACTIV_SESSION_PASSWORD__";
const host = "aop-ny4-replay.activfinancial.com";
(async function() {
try {
const session = await activOneApi.connect({
host,
user,
password,
onLogMessage(logType, message) {
console.log(message);
}
});
// Register the snapshot parameters.
const parameters = session.registerSnapshotParameters({
fieldFilter: [
activOneApi.FieldId.FID_BID,
activOneApi.FieldId.FID_ASK
]
})
// Initiate a snapshot request with the parameters and await the resolution of the resulting promise.
const snapshotResponse = await session.snapshot({
dataSourceId: activOneApi.DataSourceId.activ,
symbologyId: activOneApi.SymbologyId.native,
symbol: "CAJ.Q"
}, parameters);
console.log("Snapshot received for " + snapshotResponse.symbol);
// Iterate through the fields in the response. These will only be the bid and ask fields specified in the parameters.
for (const field of snapshotResponse.fieldData) {
console.log(`${activOneApi.FieldId[field.id]} = ${field.value}`);
}
// Delete the response and parameters once we are finished with them.
snapshotResponse.delete();
parameters.delete();
} catch (e) {
console.error(`Failure: ${activOneApi.StatusCode[e]}`);
}
})();
Not all services support snapshot field filtering, if field filtering is not supported then the full field set will be returned.
The SnapshotHandle can also be used to process results of the snapshot. The handle can be async iterated through as an async collection of SnapshotResult objects. A snapshot result contains a statusCode property that indicates if there has been an error. If the status code is StatusCode.success then the message property will also be defined and contain the successful snapshot.