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/11 19:02]
m.chlupac [Examples] 		en:mervis-db:10-api [2024/05/08 10:42] (current)
Line 1: Line 1:
 ====== API ====== ====== API ======
  
-Mervis DB supports open [[https://en.wikipedia.org/wiki/SOAP|SOAP]] API.+Mervis DB supports open [[https://en.wikipedia.org/wiki/SOAP|SOAP]] API described by this WSDL:
  
-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 24: 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 ====
-FIXME 
  
 +{{  :en:mervis-db:mervisdb_matlab_api.png?direct&800  }}
 +
 +=== Supported functions ===
 +
 +^Function^Description|
 +^SaveData|Save one or multiple records from one or multiple variables|
 +^GetData|Read one or multiple records from one or multiple variables.|
 +^GetDataUnmerged|Read one or multiple records from one or multiple variables. Allow more setting options than GetData function|
 +^GetDataOrigin|Read data exactly as are stored in the database.|
 +^DeleteVariable|Delete entire variable or some certain interval.|
 +^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|mervisdb_matlabtoolbox.zip}}.
 +  * There is a help available for all toolbox functions. To display the help use:
 +
 +<code matlab>
 +help MervisDatabase.supported_function_name
 +</code>
 +
 +=== Code ===
 +
 +
 +
 +<code matlab MervisDB_GetData_example.m>
 +% Instance of Mervis DB
 +mervisDB = MervisDatabase('username', 'password', 'dbUrl');
 +
 +% Time interval definition
 +from = localMatlab2utcMatlab(datenum(2017, 1, 1)); %1.1.2017 in utc
 +to = localMatlab2utcMatlab(datenum(2017, 31, 1)); %31.1.2017 in utc
 +samplePeriod = 5*60; % 5 minutes
 +outputTimeZone = 'Local'; % possible 'Local' or  'Utc' parameter;
 +
 +% Specifying varibles to download
 +varKeys1 = {'DPGuid', '338E2882-D72B-4D17-A241-73E8BC30F458';...
 +            'StationName', 'XXXXXXX'}; % Keys definition of first variable
 +varKeys2 = {'DPGuid', 'CC80211D-3D29-4CC2-91A2-F69483D566B5';...
 +            'StationName', 'YYYYYYY'}; % Keys definition of second variable
 +
 +variable1 = MervisDbVariable(varKeys1); % Create MervisDbVariable object from defined keys
 +variable2 = MervisDbVariable(varKeys2);
 +
 +arrayOfVarKeys = [variable1; variable2]; % array of MervisDbVariables objects
 +
 +% help for function getData
 +help MervisDatabase.getData
 +
 +% Download required data
 +[data, time] = db.getData(arrayOfVarKeys, from, to, samplePeriod, outputTimeZone);
 +
 +% Get all variables with defined keys
 +allVaribales = db.getAllVars(varKeys1);
 +</code>
  
 ==== PHP ==== ==== PHP ====
  
-  * Download {{ :en:mervis-db:mervisdb_getdata_example_php.zip |mervisdb_getdata_example_php.zip}}  +=== Code === 
-  + 
-<code php><?php+ 
 +<code php MervisDB_GetData_example.php> 
 +<?php
 /* /*
 Mervis DB PHP example - getdata Mervis DB PHP example - getdata
 */ */
 +try {
  
- +  $soapClient = new SoapClient('./wsdl/singlewsdl.xml', array( 
-try +    'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP, 
-{ +    'trace' => 0, 
-   +    'features' => SOAP_SINGLE_ELEMENT_ARRAYS 
-  $soapClient = new SoapClient('./wsdl/RcWareDbAccess.wsdl.xml',array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP ,'trace' => 0,'features' => SOAP_SINGLE_ELEMENT_ARRAYS));+  ));
   $soapClient->__setLocation('http://localhost:9876/RcWareDbAccess');   $soapClient->__setLocation('http://localhost:9876/RcWareDbAccess');
  
-  $credentials = array('Name'=>'XXXXXXXXX', 'Password'=>'YYYYYYYY');+  $credentials = array( 
 +    'Name' => 'XXXXXXX', 
 +    '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('-1hour', $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+  $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('IsKey'=>true, 'Key'=>'DPGuid', 'Value'=>'338E2882-D72B-4D17-A241-73E8BC30F458'), array('IsKey'=>true, 'Key'=>'StationName', 'Value'=>'AAAAAAAAAA')), +    array( 
-                        array(array('IsKey'=>true, 'Key'=>'DPGuid', 'Value'=>'CC80211D-3D29-4CC2-91A2-F69483D566B5'), array('IsKey'=>true, 'Key'=>'StationName', 'Value'=>'BBBBBBBBBB')), +      array( 
-                    ); +        'IsKey' => true, 
-   +        'Key' => 'DPGuid', 
-  +        'Value' => '338E2882-D72B-4D17-A241-73E8BC30F458' 
 +      ), 
 +      array( 
 +        'IsKey' => true, 
 +        'Key' => 'StationName', 
 +        'Value' => 'AAAAAAAAAA' 
 +      ) 
 +    ), 
 +    array( 
 +      array( 
 +        'IsKey' => true, 
 +        'Key' => 'DPGuid', 
 +        'Value' => 'CC80211D-3D29-4CC2-91A2-F69483D566B5' 
 +      ), 
 +      array( 
 +        'IsKey' => true, 
 +        'Key' => 'StationName', 
 +        'Value' => 'BBBBBBB' 
 +      ) 
 +    ) 
 +  ); 
   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;+
     $valOffset = 0;     $valOffset = 0;
-    do +    do { 
-    { +      $response  = $soapClient->GetData(array( 
-      $response = $soapClient->GetData(array( 'credentials'=>$credentials,  +        'credentials' => $credentials, 
-                                                            'variablesKey'=>$variablesKey,  +        'variablesKey' => $variablesKey, 
-                                                            'utcFrom'=>$utcFrom->format('Y-m-d\TH:i:s\Z'), +        'utcFrom' => $utcFrom->format('Y-m-d\TH:i:s\Z'), 
-                                                            'utcTo'=>$utcTo->format('Y-m-d\TH:i:s\Z'),  +        'utcTo' => $utcTo->format('Y-m-d\TH:i:s\Z'), 
-                                                            'valueOffset'=>$valOffset,  +        'valueOffset' => $valOffset, 
-                                                            'valueCount'=>$valCount, +        'valueCount' => $valCount, 
-                                                            'variableCount'=>$varCount, +        'variableCount' => $varCount, 
-                                                            'variableOffset'=>$varOffset));+        'variableOffset' => $varOffset 
 +      ));
       $valOffset = $response->nextValueOffset;       $valOffset = $response->nextValueOffset;
 +      $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 +
-       { +
-        if($kvp->Key == 'DPName') +
-        { +
-          echo "\n{$kvp->Value}\n"; +
-          $counter++; +
-        } +
-       } +
-        +
-        +
-       if(isset($varArray->Vals->I)){ +
-         foreach($varArray->Vals->I as $val)+
           {           {
-            echo "  t: ", $val->Ts,"   Interval: ",$val->Ivl, "\n";+          if ($kvp->Key == 'DPName') { 
 +            echo "\n{$kvp->Value}\n"; 
 +            $counter++;
           }           }
         }         }
-        else + 
-        {+        if (isset($varArray->Vals->I)) { 
 +          foreach ($varArray->Vals->I as $val) { 
 +            echo "  t: {$val->Ts}   Interval: {$val->Ivl}  {$valOffset} {$varOffset}\n"; 
 +          } 
 +        } else {
           echo "empty\n";           echo "empty\n";
         }         }
-       +
       }       }
-        
-    } while($response->nextValueOffset != -1);//-1 - no more data available 
  
-    echo "---- {$counter}\n"; +    } while ($response->nextValueOffset != -1); //-1 - no more data available
-    $varOffset = $response->nextVariableOffset; +
-  +
   } while ($response->nextVariableOffset != -1); //-1 - no more data available   } while ($response->nextVariableOffset != -1); //-1 - no more data available
 } }
-catch (Exception $e) +catch (Exception $e) {
-{+
   print_r($e);   print_r($e);
 } }
 +?>
 +</code>
  
- +\\
-?></code>+
  
  
  • © Energocentrum Plus, s.r.o. 2017 - 2025