@mindconnect/mindconnect-nodejs
Version:
NodeJS Library for Siemens Insights Hub Connectivity - TypeScript SDK for Insights Hub and Industrial IoT - Command Line Interface - Insights Hub Development Proxy (Siemens Insights Hub was formerly known as MindSphere)
295 lines (294 loc) • 13.8 kB
TypeScript
/// <reference types="node" />
import * as ajv from "ajv";
import "url-search-params-polyfill";
import { AgentAuth } from "./agent-auth";
import { BaseEvent, DataPointValue, DataSourceConfiguration, IMindConnectConfiguration, Mapping, TimeStampedDataPoint } from "./mindconnect-models";
import { MindSphereSdk } from "./sdk";
import { fileUploadOptionalParameters } from "./sdk/common/multipart-uploader";
/**
* MindConnect Agent implements the V3 of the Mindsphere API.
*
* * The synchronous methods (IsOnBoarded, HasConfiguration, HasDataMapping...) are operating on agent state storage only.
* * The asynchronous methods (GetDataSourceConfiguration, BulkPostData...) are calling MindSphere APIs.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @export
* @class MindConnectAgent
*/
export declare class MindConnectAgent extends AgentAuth {
ClientId(): string;
/**
*
* Check in the local storage if the agent is onboarded.
*
* * This is a local agent state storage setting only. MindSphere API is not called.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {boolean}
* @memberof MindConnectAgent
*/
IsOnBoarded(): boolean;
/**
* Checks in the local storage if the agent has a data source configuration.
*
* * This is a local agent state storage setting only. MindSphere API is not called.
* * Call await GetDataSourceConfiguration() if you want to check if there is configuration in the mindsphere.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {boolean}
* @memberof MindConnectAgent
*/
HasDataSourceConfiguration(): boolean;
/**
* Checks in the local storage if the agent has configured mappings.
*
* * This is a local agent state storage setting only. MindSphere API is not called.
* * Call await GetDataMappings() to check if the agent has configured mappings in the MindSphere.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {boolean}
* @memberof MindConnectAgent
*/
HasDataMappings(): boolean;
/**
* Stores the configuration in the mindsphere.
*
* By default the eTag parameter in the provided configuration is ignored, and the agent just updates the configuration every time the put method is stored
* and automatically increases the eTag.
* This is why its a good idea to check if the configuration was stored before the data was posted. If the ignoreEtag is set to false then the agent just uses
* the eTag which was specified in the configuration. This might throw an "already stored" exception in the mindsphere.
*
* @param {DataSourceConfiguration} dataSourceConfiguration
* @param {boolean} [ignoreEtag=true]
* @returns {Promise<DataSourceConfiguration>}
* @memberof MindConnectAgent
*/
PutDataSourceConfiguration(dataSourceConfiguration: DataSourceConfiguration, ignoreEtag?: boolean): Promise<DataSourceConfiguration>;
private calculateEtag;
/**
* Acquire DataSource Configuration and store it in the Agent Storage.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {Promise<DataSourceConfiguration>}
*
* @memberOf MindConnectAgent
*/
GetDataSourceConfiguration(): Promise<DataSourceConfiguration>;
/**
* Acquire the data mappings from the MindSphere and store them in the agent state storage.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {Promise<Array<Mapping>>}
*
* @memberOf MindConnectAgent
*/
GetDataMappings(): Promise<Array<Mapping>>;
private checkConfiguration;
/**
* Store data mappings in the mindsphere and also in the local agent state storage.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @param {Mapping[]} mappings
* @returns {Promise<boolean>}
*
* @memberOf MindConnectAgent
*/
PutDataMappings(mappings: Mapping[]): Promise<boolean>;
/**
* Deletes all mappings from the agent
*
* @memberOf MindConnectAgent
*/
DeleteAllMappings(): Promise<void>;
/**
* Posts the Events to the Exchange Endpoint
*
* @see: https://developer.mindsphere.io/apis/api-advanced-eventmanagement/index.html
*
* @param {*} events
* @param {Date} [timeStamp=new Date()]
* @param {boolean} [validateModel=true]
* @returns {Promise<boolean>}
* @memberof MindConnectAgent
*/
PostEvent(event: BaseEvent | CustomEvent, timeStamp?: Date, validateModel?: boolean): Promise<boolean>;
/**
* Post Data Point Values to the Exchange Endpoint
*
* @see: https://developer.mindsphere.io/howto/howto-upload-agent-data/index.html
*
* @param {DataPointValue[]} dataPoints
* @param {Date} [timeStamp=new Date()]
* @param {boolean} [validateModel=true] you can set this to false to speed up the things if your agent is working.
* @returns {Promise<boolean>}
* @memberof MindConnectAgent
*/
PostData(dataPoints: DataPointValue[], timeStamp?: Date, validateModel?: boolean): Promise<boolean>;
/**
* Post Bulk Data Point Values to the Exchange Endpoint.
*
* @param {TimeStampedDataPoint[]} timeStampedDataPoints
* @param {boolean} [validateModel=true]
* @returns {Promise<boolean>}
*
* @memberOf MindConnectAgent
*/
BulkPostData(timeStampedDataPoints: TimeStampedDataPoint[], validateModel?: boolean): Promise<boolean>;
/**
* Upload file to MindSphere IOTFileService
*
* * This method is used to upload the files to the MindSphere.
* * It supports standard and multipart upload which can be configured with the [optional.chunk] parameter.
*
* * The method will try to abort the multipart upload if an exception occurs.
* * Multipart Upload is done in following steps:
* * start multipart upload
* * upload in parallel [optional.parallelUploadChunks] the file parts (retrying [optional.retry] times if configured)
* * uploading last chunk.
*
* @param {string} entityId - asset id or agent.ClientId() for agent
* @param {string} filepath - mindsphere file path
* @param {(string | Buffer)} file - local path or Buffer
* @param {fileUploadOptionalParameters} [optional] - optional parameters: enable chunking, define retries etc.
* @param {(number | undefined)}[optional.part] multipart/upload part
* @param {(Date | undefined)} [optional.timestamp] File timestamp in mindsphere.
* @param {(string | undefined)} [optional.description] Description in mindsphere.
* @param {(string | undefined)} [optional.type] Mime type in mindsphere.
* @param {(number | undefined)} [optional.chunkSize] chunkSize. It must be bigger than 5 MB. Default 8 MB.
* @param {(number | undefined)} [optional.retry] Number of retries
* @param {(Function | undefined)} [optional.logFunction] log functgion is called every time a retry happens.
* @param {(Function | undefined)} [optional.verboseFunction] verboseLog function.
* @param {(boolean | undefined)} [optional.chunk] Set to true to enable multipart uploads
* @param {(number | undefined)} [optional.parallelUploads] max paralell uploads for parts (default: 3)
* @param {(number | undefined)} [optional.ifMatch] The etag for the upload.
* @returns {Promise<string>} - md5 hash of the file
*
* @memberOf MindConnectAgent
*
* @example await agent.UploadFile (agent.GetClientId(), "some/mindsphere/path/file.txt", "file.txt");
* @example await agent.UploadFile (agent.GetClientId(), "some/other/path/10MB.bin", "bigFile.bin",{ chunked:true, retry:5 });
*/
UploadFile(entityId: string, filepath: string, file: string | Buffer, optional?: fileUploadOptionalParameters): Promise<string>;
/**
* Uploads the file to mindsphere
*
* @deprecated please use UploadFile method instead this method will probably be removed in version 4.0.0
*
* @param {string} file filename or buffer for upload
* @param {string} fileType mime type (e.g. image/png)
* @param {string} description description of the file
* @param {boolean} [chunk=true] if this is set to false the system will only upload smaller files
* @param {string} [entityId] entityid can be used to define the asset for upload, otherwise the agent is used.
* @param {number} [chunkSize=8 * 1024 * 1024] - at the moment 8MB as per restriction of mindgate
* @param {number} [maxSockets=3] - maxSockets for http Upload - number of parallel multipart uploads
* @returns {Promise<string>} md5 hash of the uploaded file
*
* @memberOf MindConnectAgent
*/
Upload(file: string | Buffer, fileType: string, description: string, chunk?: boolean, entityId?: string, chunkSize?: number, maxSockets?: number, filePath?: string): Promise<string>;
private SendMessage;
/**
* Generates a Data Source Configuration for specified Asset Type
*
* you still have to generate the mappings (or use ConfigureAgentForAssetId method)
*
* @example
* config = await agent.GenerateDataSourceConfiguration("castidev.Engine");
*
* @param {string} assetTypeId
* @param {("NUMERICAL" | "DESCRIPTIVE")} [mode="DESCRIPTIVE"]
* * NUMERICAL MODE will use names like CF0001 for configurationId , DS0001,DS0002,DS0003... for data source ids and DP0001, DP0002... for dataPointIds
* * DESCRIPTIVE MODE will use names like CF-assetName for configurationId , DS-aspectName... for data source ids and DP-variableName for data PointIds (default)
* @returns {Promise<DataSourceConfiguration>}
*
* @memberOf MindConnectAgent
*/
GenerateDataSourceConfiguration(assetTypeId: string, mode?: "NUMERICAL" | "DESCRIPTIVE"): Promise<DataSourceConfiguration>;
/**
* Generate automatically the mappings for the specified target assetid
*
* !Important! this only works if you have created the data source coniguration automatically
*
* @example
* config = await agent.GenerateDataSourceConfiguration("castidev.Engine");
* await agent.PutDataSourceConfiguration(config);
* const mappings = await agent.GenerateMappings(targetassetId);
* await agent.PutDataMappings (mappings);
*
* @param {string} targetAssetId
* @returns {Mapping[]}
*
* @memberOf MindConnectAgent
*/
GenerateMappings(targetAssetId: string): Mapping[];
/**
* This method can automatically create all necessary configurations and mappings for selected target asset id.
*
* * This method will automatically create all necessary configurations and mappings to start sending the data
* * to an asset with selected assetid in Mindsphere
*
* @param {string} targetAssetId
* @param {("NUMERICAL" | "DESCRIPTIVE")} mode
*
* * NUMERICAL MODE will use names like CF0001 for configurationId , DS0001,DS0002,DS0003... for data source ids and DP0001, DP0002... for dataPointIds
* * DESCRIPTIVE MODE will use names like CF-assetName for configurationId , DS-aspectName... for data source ids and DP-variableName for data PointIds (default)
* @param {boolean} [overwrite=true] ignore eTag will overwrite mappings and data source configuration
* @memberOf MindConnectAgent
*/
ConfigureAgentForAssetId(targetAssetId: string, mode?: "NUMERICAL" | "DESCRIPTIVE", overwrite?: boolean): Promise<void>;
private _sdk?;
/**
* MindSphere SDK using agent authentication
*
* ! important: not all APIs can be called with agent credentials, however MindSphere is currently working on making this possible.
*
* * Here is a list of some APIs which you can use:
*
* * AssetManagementClient (Read Methods)
* * MindConnectApiClient
*
* @returns {MindSphereSdk}
*
* @memberOf MindConnectAgent
*/
Sdk(): MindSphereSdk;
/**
* Ajv Validator (@see https://github.com/ajv-validator/ajv) for the data points. Validates if the data points array is only
* containing dataPointIds which are configured in the agent configuration.
*
* @returns {ajv.ValidateFunction}
*
* @memberOf MindConnectAgent
*/
GetValidator(): ajv.ValidateFunction;
private _eventValidator?;
/**
*
* Ajv Validator (@see https://github.com/ajv-validator/ajv) for the events. Validates the syntax of the mindsphere events.
*
* @returns {ajv.ValidateFunction}
*
* @memberOf MindConnectAgent
*/
GetEventValidator(): ajv.ValidateFunction;
/**
* Get local configuration from the agent state storage.
*
* * This is a local agent state storage setting only. MindSphere API is not called.
*
* @see https://developer.siemens.com/industrial-iot-open-source/mindconnect-nodejs/agent-development/agent-state-storage.html
*
* @returns {IMindConnectConfiguration}
*
* @memberOf MindConnectAgent
*/
GetMindConnectConfiguration(): IMindConnectConfiguration;
private uploader;
}