VTScada RESTInterface Module
This service provides a REST interface to query VTScada tag values, alarm data or historical data where information is available and dependent upon user privileges and realm restrictions.
The interface can be accessed using GET or POST , either through an HTTP request or a client ODBC connection. The interface currently only supports the function RegisterCustomFunction. This module is used to retrieve specific values from a REST interface and register them to a custom function endpoint in your application.
The developer of the custom function is responsible for:
- Correctly handling the data passed to the callback module .
- Logging the actions caused by the customized REST script.
- Ensuring the custom REST APIs perform authentication and security checks when needed.
- Managing resource consumption of custom REST APIs.
For more information, refer to the "Security Guidelines Manual" included in the Documents folder at the root of your VTScada installation.
Example of a custom RESTInterface module
Function Registration occurs within the definition of the custom function, in the below case, one that retrieves tags under a given context:
{============================= RESTReturnTagList ==============================}
{ This service provides an external (accessible by REST) or internal interface }
{ to retrieve the tags under the given context tag. }
{==============================================================================}
[
DoAction Module { Retrieves tags under the given context tag. };
]
Init [
If \RESTServicesInterface.Ready Main;
[
\RESTServicesInterface.RegisterCustomFunction("ReturnTagList", Self());
]
]
Main [
]
Note the "Self()" entered as the CallbackObj parameter, this is what tells the interface to execute the DoAction callback.
Once registered, the custom function can be invoked within an HTTP Request:
http://serverName/realmName/REST/ReturnTagList?RootTag=RealmA&TagType=IO
Note the "realmName" in the HTTP request. The querying user will require permissions to access the security realm containing the desired tag data (see Security Realms), along with the Remote Data Access privilege (see System Privilege Reference for Programmers).
The RestResponseInfo Struct is stored within PtrResults:
PROTECTED RESTResponseInfo STRUCT [
results { Result from the REST functions };
returnCode { Return code. Zero for success };
errorMessage { Textual error message };
nextPageToken { A base64 encoded JSON token for pagination.
Invalid indicates no more pages. };
paginationStats { Statistics of the pagination progress };
];
An HTTP Request will return the results as a JSON object keyed by the same variables as the RestResponseInfo Struct: results, returnCode, errorMessage, nextPageToken, and paginationStats.
{
"results": [
"RealmA\\IOA",
"RealmA\\IOB"
],
"returnCode": 0,
"errorMessage": null,
"nextPageToken": null,
"paginationStats": null
}
In the case of a connection error, HTTP Error codes will be consistent with established HTML error conventions, see 'VTScada Thin Client Server Error Messages' for more information.
