PlayGround

//*************************************************************************************************
// Mervis Data API
// Definition of the communication contract
//
// (c) Energocentrum Plus - all rights reserved
//
// Code style guide: https://developers.google.com/protocol-buffers/docs/style
//*************************************************************************************************
 
syntax = "proto3";
 
package esg.mervis_data_api.shared;
 
option csharp_namespace = "ESG.MervisDataApi.Shared";
 
import "Protos/mda_types.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
 
service MervisDataApiService
{
    // List of all variables that comply with request parameters.
	rpc EnumerateValueDescriptions (EnumerateValueDescriptionsRequest) returns (EnumerateValueDescriptionsResponse);
 
	// Gets values identified by ID.
	rpc GetValuesById (GetValuesByIdRequest) returns (GetValuesByIdResponse);
 
	// Gets values identified by path.
	rpc GetValuesByPath (GetValuesByPathRequest) returns (GetValuesByPathResponse);
 
	// Stream request for variable values identified by IDs.
	rpc SubscribeValuesById (SubscribeValuesByIdRequest) returns (stream Value);
 
	// Stream request for variable values identified by paths.
	rpc SubscribeValuesByPath (SubscribeValuesByPathRequest) returns (stream Value);
 
	// Sets values identified by ID.
	rpc SetValuesById (SetValuesByIdRequest) returns (SetValuesByIdResponse);
 
	// Stream request for setting values identified by ID.
	rpc StreamSetValuesById (stream StreamSetValuesByIdRequest) returns (StreamSetValuesByIdResponse);
}
 
// Name/password credentials.
message UserNameCredentials
{
	string domain_id = 1;
	string user_name = 2;
	string password = 3;
}
 
// Token credentials.
message TokenCredentials
{
	string token = 1;
}
 
// Request credentials.
message Credentials
{
	oneof identity
	{
		UserNameCredentials user_name_and_password = 1;
		TokenCredentials token = 2;
	}
}
 
// Explicit definition of path to a variable.
message Path
{
	repeated string segments = 1;
}
 
// Value of a metadata item.
message MetadataValue
{
	oneof value
	{
		bool boolean			= 10;
		sfixed64 signed_int		= 11;
		fixed64 unsigned_int	= 12;
		double float64			= 14;
		string text				= 17;
	}
}
 
// Tag item used for detailed description of a variable.
message Tag
{
	string key = 1;
	string value = 2;
}
 
// Description of a variable.
message ValueDescription
{
	string id = 1;							// ID
	MdaValueType type = 2;					// Value type, can be "unspecified". It means that the value is polymorphic
	MdaAccess access = 3;					// Kinda of access to a variable
	repeated Path paths = 5;				// All available paths where the can be found
	map<int32, MetadataValue> metadata = 6;	// Metadata. Key corresponds to MdaMetadataKey but cannot be used directly https://protobuf.dev/programming-guides/proto3/#maps
	repeated Tag tags = 7;					// Variable tags
}
 
// Definition of a variable. Requesters can assign their own IDs and the server must be able to provide values based on this ID.
message OptimizedIdDefinition
{
	string native_id = 1;			// ID as given by the server
	optional int32 numerical = 2;	// Requester defined ID
}
 
// Numericals ID is used in case of requester custom ID.
message OptimizedId
{
	oneof id
	{
		string native = 1;		// ID as given by the server
		int32 numerical = 2;	// Requester defined ID
	}
}
 
// Variable value.
message Value
{
	OptimizedId id = 1;	// ID of the value
	oneof value			// Strongly typed value
	{
		bool boolean							= 10;
		sfixed64 signed_int						= 11;
		fixed64 unsigned_int					= 12;
		float float32							= 13;
		double float64							= 14;
		google.protobuf.Timestamp date_time_utc = 15;
		google.protobuf.Duration timespan		= 16;
		string text								= 17;
	}
}
 
// Request parameters for enumerating variables.
message EnumerateValueDescriptionsRequest
{
	Credentials credentials = 1;	// Credentials
	repeated Path path_filters = 2;	// List of paths where are variables located. If the list is empty the method returns all available variables.
}
 
// Response of enumerating variables.
message EnumerateValueDescriptionsResponse
{
	MdaResponseReturnResult result = 1;			// General result
	repeated ValueDescription descriptions = 2;	// Available variables
}
 
// Request parameters for reading values of variables specified by IDs.
message GetValuesByIdRequest
{
	Credentials credentials = 1;	// Credentials
	repeated string ids = 2;		// Requested IDs
}
 
// Response of reading values of variables specified by IDs.
message GetValuesByIdResponse
{
	MdaResponseReturnResult result = 1;	// General result
	repeated Value values = 2;			// Values
}
 
// Request parameters for reading values of variables specified by paths.
message GetValuesByPathRequest
{
	Credentials credentials = 1;	// Credentials
	repeated Path paths = 2;		// Paths
}
 
// Response of reading values of variables specified by paths.
message GetValuesByPathResponse
{
	MdaResponseReturnResult result = 1;	// General result
	repeated Value values = 2;			// Values
}
 
// Request parameters for stream-reading values of variables specified by IDs.
message SubscribeValuesByIdRequest
{
	Credentials credentials = 1;			// Credentials
	repeated OptimizedIdDefinition ids = 2; // IDs
}
 
// Request parameters for stream-reading values of variables specified by Paths.
message SubscribeValuesByPathRequest
{
	Credentials credentials = 1;	// Credentials
	repeated Path paths = 2;		// Paths
}
 
// Request parameters for writing values of variables specified by IDs.
message SetValuesByIdRequest
{
	Credentials credentials = 1;	// Credentials
	repeated Value values = 2;		// Values
}
 
// Response result for individual variables. Only problematic variables are reported.
message SetValueIssue
{
	string id = 1;						// Variable ID
	SetValueErrorCode error_code = 2;	// Error code
	optional string error_message = 3;	// Error message
}
 
// Response of writing values of variables specified by IDs.
message SetValuesByIdResponse
{
	MdaResponseReturnResult result = 1;	// General result
	repeated SetValueIssue issues = 2;	// Issues
}
 
// Request parameters for stream-writing values of variables specified by IDs.
message StreamSetValuesByIdRequest
{
	optional Credentials credentials = 1;						// Last credentials are taken int account
	optional OptimizedIdDefinition optimized_id_definition = 2;	// Possible definition of custom IDs
	Value value = 3;											// Value
}
 
// Response of stream-writing values of variables specified by IDs.
message StreamSetValuesByIdResponse
{
	MdaResponseReturnResult result = 1;
}