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
Next revision Both sides next revision
en:mervis-db:10-api [2017/07/13 14:48]
m.chlupac 		en:mervis-db:10-api [2019/03/06 12:31]
m.chlupac
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| |
  
 +===== 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 ===
  
  
 +<code csharp MervisDB_GetData_Example.cs>
 +using System;
 +using System.Linq;
 +using System.Threading.Tasks;
 +using MervisDb_GetData_Example.MervisDbService;
  
 +namespace MervisDb_GetData_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"
 +     };
  
-===== Examples =====+     // 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" 
 +        } 
 +       } 
 +     };
  
-==== C# ==== +     // From-To dates. The dates must be specified in the UTC time zone. 
-FIXME+     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 231:
 ^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 261:
 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 274:
  
 % 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 295:
   ));   ));
   $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 336:
     )     )
   );   );
-   +
-  +
   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 357:
       $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 366:
           }           }
         }         }
-         +
-        +
         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 374:
           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 383:
   print_r($e);   print_r($e);
 } }
-?></code>+?> 
 +</code> 
 + 
 +\\
  
  
  • © Energocentrum Plus, s.r.o. 2017 - 2024