Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
en:mervis-db:10-api [2017/07/13 14:48]
m.chlupac 		en:mervis-db:10-api [2024/05/08 10:42] (current)
Line 2: Line 2:
  
 Mervis DB supports open [[https://en.wikipedia.org/wiki/SOAP|SOAP]] API described by this WSDL: Mervis DB supports open [[https://en.wikipedia.org/wiki/SOAP|SOAP]] API described by this WSDL:
-  * {{ :en:mervis-db:mervisdb_wsdl-2017-07-12.xml |}} 
  
-Contact [[:en:help:support|technical support]] for other non-public APIs that can be used for your projects.+  * {{:en:mervis-db:mervisdb_wsdl-2017-07-12.xml|mervisdb_wsdl-2017-07-12.xml}}
  
 +Contact [[:en:help:support|technical support]] for other non-public APIs that can be used for your projects.
  
 ===== List of supported functions ===== ===== List of supported functions =====
Line 25: Line 25:
 ^CheckCredentials| | ^CheckCredentials| |
  
 +===== Object Properties =====
 +  * (UTC)TimeStamp - UTC time stamp of the record
 +  * GoodThrough - UTC time stamp of the end of validity of particular record
 +  * Interval - period of time (in seconds) when next value should be recorded
  
  
 +===== Examples =====
  
 +==== C# ====
  
 +{{ :en:mervis-db:mervis_db_csharp.png?direct&800 |}}
  
 +=== Download ===
  
  
 +{{ :en:mervis-db:mervisdb_getdata_example.zip |}}\\
 +{{ :en:mervis-db:mervisdb_savedata_example.zip |}}
  
 +=== Code ===
  
  
-===== Examples =====+<code csharp MervisDB_GetData_Example.cs> 
 +using System; 
 +using System.Linq; 
 +using System.Threading.Tasks; 
 +using MervisDb_GetData_Example.MervisDbService;
  
-==== C# ==== +namespace MervisDb_GetData_Example { 
-FIXME+ class Program { 
 +  static void Main(string[] args) { 
 +   // 
 +   // Demo of asynchronous methods. 
 +   // 
 +   var task = Task.Run(async() => { 
 +    // 
 +    // Create access to the real server. 
 +    // Without SSL connections, you have to remove binding parameters "<security mode="Transport"/>" in the App.config. 
 +    // The client is automatically generated from the WSDL file available here: https://kb.mervis.info/doku.php/en:mervis-db:10-api 
 +    // 
 +    using(HistoryDbAccessClient client = new HistoryDbAccessClient("HistoryAccess", "https://localhost:9876/RcWareDbAccess")) { 
 +     // Authentication credetials in the database. 
 +     Credentials credentials = new Credentials { 
 +      Name = "XXXX", Password = "YYYY" 
 +     };
  
 +     // Specification of the variables through Key-Value.
 +     // Here we use 2 variables.
 +     KeyValuePair[][] keys = new KeyValuePair[][] {
 +      new KeyValuePair[] {
 +        new KeyValuePair {
 +         Key = "DPGuid", Value = "338E2882-D72B-4D17-A241-73E8BC30F458"
 +        }, new KeyValuePair {
 +         Key = "StationName", Value = "AAABBB"
 +        }
 +       },
 +       new KeyValuePair[] {
 +        new KeyValuePair {
 +         Key = "DPGuid", Value = "CC80211D-3D29-4CC2-91A2-F69483D566B5"
 +        }, new KeyValuePair {
 +         Key = "StationName", Value = "AAABBB"
 +        }
 +       }
 +     };
 +
 +     // From-To dates. The dates must be specified in the UTC time zone.
 +     DateTime utcTo = DateTime.UtcNow;
 +     DateTime utcFrom = DateTime.UtcNow.AddDays(-1);
 +
 +     // Retrieving the data goes through cycling of values and variables. The server returns recommended values needed for the the next cycle.
 +     int variableOffset = 0; // the offset of the variable
 +     int variableCount = 10; // maximal number of variables returned in one request
 +     int valueOffset; // the offset of the value
 +     int valueCount = 1000; // maximal values in on request
 +
 +     Console.WriteLine("Reading values...");
 +
 +     do {
 +      valueOffset = 0;
 +      do {
 +       // Execute the request.
 +       var result = await client.GetDataAsyncAsync(credentials, keys, utcFrom, utcTo, variableOffset, variableCount, valueOffset, valueCount);
 +
 +       // Check the return code. "0;OK" is what we want.
 +       if (!result.ReturnCode.StartsWith("0;")) {
 +        Console.WriteLine("Error on reading: {0}", result.ReturnCode);
 +       }
 +
 +       // Cycle through the data and print it out.
 +       foreach(var valRecord in result.Data) {
 +        Console.WriteLine("Variable: {0}", String.Concat(valRecord.Keys.Select((i) => {
 +         return String.Format("{0}={1}; ", i.Key, i.Value);
 +        })));
 +
 +        foreach(var value in valRecord.Vals) {
 +         Console.WriteLine("{0}->{1} [{2}] {3}", value.Ts, value.Gt, value.Hvt, value.Dv /* Use value type according to the Hvt (History Value Type) */ );
 +        }
 +       }
 +
 +       valueOffset = result.NextValueOffset;
 +       variableOffset = result.NextVariableOffset;
 +      }
 +      while (valueOffset != -1);
 +     }
 +     while (variableOffset != -1);
 +    }
 +   });
 +
 +   Console.WriteLine("DB communication is running in background");
 +
 +   try {
 +    task.Wait();
 +   } catch (Exception exc) {
 +    Console.WriteLine("Exception: {0}", exc.ToString());
 +   }
 +
 +   Console.WriteLine("DB communication finished");
 +
 +   Console.ReadLine();
 +  }
 + }
 +}</code>
 +
 +<code csharp MervisDB_SaveData_Example.cs>
 +using System;
 +using System.Collections.Generic;
 +using System.Threading.Tasks;
 +using MervisDb_SaveData_Example.MervisDbService;
 +
 +namespace MervisDb_SaveData_Example
 +{
 + class Program
 + {
 + static void Main(string[] args)
 + {
 + //
 + // Demo of asynchronous methods.
 + //
 + var task = Task.Run(async () =>
 + {
 + //
 + // Create access to the real server.
 + // Without SSL connections, you have to remove binding parameters "<security mode="Transport"/>" in the App.config.
 + // The client is automatically generated from the WSDL file available here: https://kb.mervis.info/doku.php/en:mervis-db:10-api
 + //
 + using (HistoryDbAccessClient client = new HistoryDbAccessClient("HistoryAccess", "https://localhost:9876/RcWareDbAccess"))
 + {
 + // Authentication credetials in the database.
 + Credentials credentials = new Credentials { Name = "XXXX", Password = "YYYY" };
 +
 + // Adding records...
 + List<ValueRecord> records = new List<ValueRecord>();
 +
 + DateTime utcTimeStamp = new DateTime(2018, 1, 1, 12, 0, 0, DateTimeKind.Utc);
 +
 + // Each value is stored in a ValueRecord structure
 + ValueRecord rec = new ValueRecord();
 +
 + rec.UtcTimeStamp = utcTimeStamp;                // time stamp of the value, UTC date time must be used
 + rec.HistoryValueType = HistoryValueType.Double; // type of the value
 + rec.DoubleValue = 23.4;                         // value itself
 + rec.Interval = 60.0;                            // sampling period in seconds. When the difference of timestamps of subsequent values if greater than 1.1 multiple of the interval, the data should be considered incomplete.
 + rec.Keys = new KeyValuePair[] // identification of the variable. At least one key-value pair must be "IsKey" to identify a variable.
 + {
 + new KeyValuePair { IsKey = true, Key = "Root", Value = "Building A"},
 +                                                new KeyValuePair { IsKey = true, Key = "Guid", Value = "T26549821654"},
 + new KeyValuePair { IsKey = false, Key = "Level1", Value = "Floor 1"},
 + new KeyValuePair { IsKey = false, Key = "Level2", Value = "Room 7"},
 + new KeyValuePair { IsKey = false, Key = "Name", Value = "Temperature"},
 + new KeyValuePair { IsKey = false, Key = "Description", Value = "Temperature in the room 7"},
 + new KeyValuePair { IsKey = false, Key = "Unit", Value = "°C"},
 + };
 +
 + records.Add(rec);
 +
 + // Save data method returns the number of stored records
 + int recordsSaved = await client.SaveDataAsync(credentials, records.ToArray());
 +
 + Console.WriteLine("Records saved: {0}", recordsSaved);
 + }
 + });
 +
 + Console.WriteLine("DB communication is running in background");
 +
 + try
 + {
 + task.Wait();
 + }
 + catch (Exception exc)
 + {
 + Console.WriteLine("Exception: {0}", exc.ToString());
 + }
 +
 + Console.WriteLine("DB communication finished");
 +
 + Console.ReadLine();
 + }
 + }
 +}</code>
 ==== Matlab ==== ==== Matlab ====
 +
 +{{  :en:mervis-db:mervisdb_matlab_api.png?direct&800  }}
 +
 === Supported functions === === Supported functions ===
 +
 ^Function^Description| ^Function^Description|
 ^SaveData|Save one or multiple records from one or multiple variables| ^SaveData|Save one or multiple records from one or multiple variables|
Line 50: Line 237:
 ^GetRequiredTimestamp|Get time stamp depending on input options.| ^GetRequiredTimestamp|Get time stamp depending on input options.|
  
 +=== Toolbox ===
  
-You need to import specialized toolbox to communicate with Mervis DB from Matlab: {{ :en:mervis-db:mervisdb_matlabtoolbox.zip |}}. +You need to import specialized toolbox to communicate with Mervis DB from Matlab:
  
-There is a help available for all toolbox functions. +  * {{:en:mervis-db:mervisdb_matlabtoolbox.zip|mervisdb_matlabtoolbox.zip}}. 
 +  * There is a help available for all toolbox functions. To display the help use:
  
-To display the help use:  +<code matlab> 
-<code matlab>help MerbonDatabase.supported_function_name</code>+help MervisDatabase.supported_function_name 
 +</code>
  
-<code matlab MervisDB_GetData_example.m>% Instance of Mervis DB  +=== Code === 
-mervisDB = MerbonDatabase('username', 'password', 'dbUrl');+ 
 + 
 + 
 +<code matlab MervisDB_GetData_example.m> 
 +% Instance of Mervis DB 
 +mervisDB = MervisDatabase('username', 'password', 'dbUrl');
  
 % Time interval definition % Time interval definition
Line 72: Line 267:
 varKeys2 = {'DPGuid', 'CC80211D-3D29-4CC2-91A2-F69483D566B5';... varKeys2 = {'DPGuid', 'CC80211D-3D29-4CC2-91A2-F69483D566B5';...
             'StationName', 'YYYYYYY'}; % Keys definition of second variable             'StationName', 'YYYYYYY'}; % Keys definition of second variable
-  
-variable1 = MerbonDbVariable(varKeys1); % Create MerbonDbVariable object from defined keys 
-variable2 = MerbonDbVariable(varKeys2); 
  
-arrayOfVarKeys = [variable1; variable2]; % array of MerbonDbVariables objects +variable1 = MervisDbVariable(varKeys1); % Create MervisDbVariable object from defined keys 
- +variable2 = MervisDbVariable(varKeys2); 
 + 
 +arrayOfVarKeys = [variable1; variable2]; % array of MervisDbVariables objects 
 % help for function getData % help for function getData
-help MerbonDatabase.getData +help MervisDatabase.getData
  
 % Download required data % Download required data
Line 85: Line 280:
  
 % Get all variables with defined keys % Get all variables with defined keys
-allVaribales = db.getAllVars(varKeys1);</code> +allVaribales = db.getAllVars(varKeys1); 
 +</code>
  
 ==== PHP ==== ==== PHP ====
  
 +=== Code ===
  
-  + 
-<code php MervisDB_GetData_example.php><?php+<code php MervisDB_GetData_example.php> 
 +<?php
 /* /*
 Mervis DB PHP example - getdata Mervis DB PHP example - getdata
 */ */
 try { try {
-  +
   $soapClient = new SoapClient('./wsdl/singlewsdl.xml', array(   $soapClient = new SoapClient('./wsdl/singlewsdl.xml', array(
     'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP,     'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP,
Line 104: Line 301:
   ));   ));
   $soapClient->__setLocation('http://localhost:9876/RcWareDbAccess');   $soapClient->__setLocation('http://localhost:9876/RcWareDbAccess');
-  +
   $credentials = array(   $credentials = array(
     'Name' => 'XXXXXXX',     'Name' => 'XXXXXXX',
     'Password' => 'YYYYYYY'     'Password' => 'YYYYYYY'
   );   );
-  +
   $utcTZ   = new DateTimezone('UTC'); //all time realted values are expected in UTC   $utcTZ   = new DateTimezone('UTC'); //all time realted values are expected in UTC
   $utcFrom = new DateTime('-120minutes', $utcTZ); //   $utcFrom = new DateTime('-120minutes', $utcTZ); //
   $utcTo   = new DateTime('now', $utcTZ); //   $utcTo   = new DateTime('now', $utcTZ); //
-  +
   $valOffset = 0;   $valOffset = 0;
   $valCount  = 20; //how many values should be returned in one request at most. Recommended value: 5000   $valCount  = 20; //how many values should be returned in one request at most. Recommended value: 5000
   $varOffset = 0;   $varOffset = 0;
   $varCount  = 4; //how many variable should be returned in on request at most   $varCount  = 4; //how many variable should be returned in on request at most
-   +
-  +
   $variablesKey = array(   $variablesKey = array(
     array(     array(
Line 146: Line 342:
     )     )
   );   );
-   +
-  +
   echo "Reading values from: {$utcFrom->format('c')} to: {$utcTo->format('c')}\n\n";   echo "Reading values from: {$utcFrom->format('c')} to: {$utcTo->format('c')}\n\n";
-  +
   $counter = 0;   $counter = 0;
-  +
   do {   do {
     $response  = null;     $response  = null;
Line 168: Line 363:
       $valOffset = $response->nextValueOffset;       $valOffset = $response->nextValueOffset;
       $varOffset = $response->nextVariableOffset;       $varOffset = $response->nextVariableOffset;
-       +
-      +
       foreach ($response->GetDataResult->Mvr as $varArray) {       foreach ($response->GetDataResult->Mvr as $varArray) {
         foreach ($varArray->Keys->KeyValuePair as $kvp) //the set of keys depends on the source of the data         foreach ($varArray->Keys->KeyValuePair as $kvp) //the set of keys depends on the source of the data
Line 178: Line 372:
           }           }
         }         }
-         +
-        +
         if (isset($varArray->Vals->I)) {         if (isset($varArray->Vals->I)) {
           foreach ($varArray->Vals->I as $val) {           foreach ($varArray->Vals->I as $val) {
Line 187: Line 380:
           echo "empty\n";           echo "empty\n";
         }         }
-        +
       }       }
-       + 
-    } while ($response->nextValueOffset != -1); //-1 - no more data available  +    } while ($response->nextValueOffset != -1); //-1 - no more data available
   } while ($response->nextVariableOffset != -1); //-1 - no more data available   } while ($response->nextVariableOffset != -1); //-1 - no more data available
 } }
Line 196: Line 389:
   print_r($e);   print_r($e);
 } }
-?></code>+?> 
 +</code> 
 + 
 +\\
  
  
  • © Energocentrum Plus, s.r.o. 2017 - 2025