Managing Collector Instances
- The Create Collector Instance API
- Using the Create Collector Instance API, you can create a collector
instance.
METHOD POST URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/createnewinstance
SAMPLE URI
Payloadhttps://<NLB DNS:9090>/historian-rest-api/v1/collector/createnewinstance
{ "mode":1, "CollectorSystemName":"xyz", "InterfaceDescription":"xyz_Simulation_<IP address>_2", "DataPathDirectory":"C:\\Proficy Historian Data", "CollectorDestination":"Historian", "winUserName":"","winPassword":"", "InterfaceSubType":"", "DestinationHistorianUserName":"abc", "DestinationHistorianPassword":"password", "DestinationHistorian":"<IP address>", "General1":"", "General2":"", "General3":"123", "General4":"", "General5":"", "Type":2, "InterfaceName":"<source server>_<type of the collector>_<destination server>" }
Note:- The DestinationHistorian parameter will not have a value for offline collector configuration.
- To connect to MQTT destinations such as AWS IoT and Google Cloud Platform (GCP), you must provide an encrypted password.
SAMPLE RESPONSE { "ErrorCode": 0, "ErrorMessage": null }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{ \"mode\":1,\"CollectorSystemName\":\"xyz\", \"InterfaceDescription\":\"xyz_Simulation_<IP address>_2\",\"DataPathDirectory\":\"C:\\Proficy Historian Data\", \"CollectorDestination\":\"Historian\",\"winUserName\":\"\",\"winPassword\":\"\", \"InterfaceSubType\":\"\",\"DestinationHistorianUserName\":\"abc\", \"DestinationHistorianPassword\":\"password\", \"DestinationHistorian\":\"<IP address>\",\"General1\":\"\", \"General2\":\"\",\"General3\":\"xyz\",\"General4\":\"\",\"General5\":\"\", \"Type\":2,\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\"}” -X POST https://<NLB DNS:9090>/historian-rest-api/v1/collector/createnewinstance
Table 1. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Get Collector Instance Details API
- Using the Get Collector Instance Details API, you can view the details of a
collector instance.
METHOD GET URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/instancedetails/<interface name>
SAMPLE QUERY PARAM GET URL https://<NLB DNS:9090>/historian-rest-api/v1/collector/instancedetails/<interface name>
SAMPLE RESPONSE { "ErrorCode":0, "ErrorMessage":null, "Data": { "CloudDestination":"", "InterfaceSubType":"", "CollectorSystemName":"xyz", "Type":2, "DefaultCompression":false, "CloudInformationLogLevel":0, "InterfaceDataDir":"C:\\Proficy Historian Data", "SourceServer":"", "Username":"", "Password":"", "DestinationType":"Historian", "DestinationServer":"abc", "DebugLogLevel":0, "InterfaceInstallDrive":"C", "ConnnectionString":"xyz" } }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<NLB DNS:9090>/historian-rest-api/v1/collector/instancedetails/xyz_Simulation_<IP address>_2
Table 2. Query Parameters Parameter Description Required? Values interface name
The interface name of the collector whose details you want to view. Yes String Table 3. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Edit Collector Instance API
- Using the Edit Collector Instance API, you can modify the cloud parameters
of a collector instance. The collector instance will be restarted after you
make changes.
METHOD PUT URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/editInstance
SAMPLE URI
Payloadhttps://<NLB DNS:9090>/historian-rest-api/v1/collector/editInstance
{"InterfaceName":"<source server>_<type of the collector>_<destination server>", "messageCompression":0, "azureLogLevel":1, "debugMode":0, "CollectorDestination":"Predix", "DestinationHistorian":"abc", "mode":1, "CloudDestinationAddress":"wss://def.run.abc.ice.predix.io/v1/stream/messages", "IdentityIssuer":"https://1234.predix-uaa.run.abc.ice.predix.io/oauth/token", "ClientID":"xyz", "ClientSecret":"123", "ZoneID":"1234", "Proxy":"http://1.2.3.4:80", "ProxyUserName":"", "ProxyPassword":"", "DatapointAttribute1":"", "DatapointAttribute2":"", "DatapointAttribute3":"", "DatapointAttribute4":""}
Note:- The DestinationHistorian parameter will not have a value for offline collector configuration.
- To connect to MQTT destinations such as AWS IoT and Google Cloud Platform (GCP), you must provide an encrypted password.
SAMPLE RESPONSE { "ErrorCode": 0, "ErrorMessage": null }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\", \"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"messageCompression\":0,\"azureLogLevel\":1, \"debugMode\":0,\"CollectorDestination\":\"Predix\",\"DestinationHistorian\":\"abc\",\"mode\":1, \"CloudDestinationAddress\":\"wss://wss://def.run.abc.ice.predix.io/v1/stream/messages\", \"IdentityIssuer\":\"https://1234.predix-uaa.run.abc.ice.predix.io/oauth/token/", \"ClientID\":\"HistQA\",\"ClientSecret\":\"Gei321itc\",\"ZoneID\":\"1234\", \"Proxy\":\"http://1.2.3.4:80\",\"ProxyUserName\":\"\",\"ProxyPassword\":\"\", \"DatapointAttribute1\":\"\",\"DatapointAttribute2\":\"\",\"DatapointAttribute3\":\"\", \"DatapointAttribute4\":\"\"}” -X PUT https://<NLB DNS:9090>/historian-rest-api/v1/collector/editInstance
Table 4. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Azure Log Level API
- Using the Azure Log Level API, you can set the debug information log level
for destination - Azure IoT Hub. You can set a value ranging from 0 to
4.
METHOD PUT URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/azureloglevel
SAMPLE URI
Payloadhttps://<NLB DNS:9090>/historian-rest-api/v1/collector/azureloglevel
{"InterfaceName":""InterfaceName":"<source server>_<type of the collector>_<destination server>"", "azureLogLevel":1,}
SAMPLE RESPONSE { "ErrorCode": 0, "ErrorMessage": null }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"azureLogLevel\":1}” -X PUT https://<NLB DNS:9090>/historian-rest-api/v1/collector/azureloglevel
Table 5. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Install Component Details API
- Using the Install Component Details API, you can view the install component
details from the collector machine.
METHOD GET URI https://<NLB DNS:9090>/historian-rest-api/v1/ installcomponentdetails/collectorType/collectorSubType/machine
SAMPLE URI https://<NLB DNS:9090>/historian-rest-api/v1/installcomponentdetails/2/-/abc
SAMPLE RESPONSE { "ErrorCode":0, "ErrorMessage":null, "Data": { "InterfaceInstallDrive":"C", "InterfaceDataDir":"C:\\Proficy Historian Data", "CertPathDir":"NONE" } }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -H "Authorization: Bearer <TOKEN>” https://<NLB DNS:9090>/historian-rest-api/v1/installcomponentdetails/2/-/abc
Table 6. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Message Compression API
- Using the Message Compression API, you can enable or disable message
compression.
METHOD PUT URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/messagecompression
SAMPLE REQUEST { "InterfaceName":"<source server>_<type of the collector>_<destination server>", "messageCompression":1 }
SAMPLE RESPONSE { "ErrorCode":0, "ErrorMessage":null, }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\", \"messageCompression\":1}” -X PUT https://<NLB DNS:9090>/historian-rest-api/v1/collector/messagecompression
Table 7. Query Parameters Parameter Description Required? Values interface name
The interface name of the collector whose message compression you want to enable or disable. Yes String messagecompression
Identifies whether you want to enable or disable message compression. The valid values are 0 and 1. Yes Table 8. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL. - The Delete Instance API
- Using the Delete Instance API, you can delete a collector instance.
METHOD PUT URI https://<NLB DNS:9090>/historian-rest-api/v1/collector/deleteinstance
SAMPLE REQUEST https://<NLB DNS:9090>/historian-rest-api/v1/collector/deleteinstance Payload { "InterfaceName":"<source server>_<type of the collector>_<destination server>", "deleteTags":true }
SAMPLE RESPONSE { "ErrorCode":0, "ErrorMessage":null, }
SAMPLE cURL COMMAND curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer <TOKEN>” -d “{\"InterfaceName\":\"<source server>_<type of the collector>_<destination server>\",\"deleteTags\":true}” -X PUT https://<NLB DNS:9090>/historian-rest-api/v1/collector/deleteinstance
Table 9. Query Parameters Parameter Description Required? Values interface name
The interface name of the collector whose details you want to delete. Yes String deleteTags
Identifies whether you want to delete the tags. The valid values are true and false. Yes Boolean Table 10. Response Parameters Parameter Data Type Required? Description ErrorCode
Integer Yes For example, ErrorCode = 0 implies the operation was successful. ErrorMessage
String Yes For example, NULL.