The da_rest_client download action

\[DRAFT\]

The SiteController module da_rest_client is able to perform download actions with a configuration like

configuration

...    
<action action_id="download_memodata" device_id="rest_test">
  <commands>
     <command command_id="download">download(<'uri to request'> method=<'get'/'post'> timeout=<positive floating point number>)</command>
  </commands>
</action>
...

The action_id and the command_id can be freely chosen. The device_id must be equal to the configured da_rest_client device in the same sensor configuration.

The function download is currently the only choice of an action executed by da_rest_client. The parameter <'uri to request'> must be set, for example like '/fcgi/control/memodata_download'. The parameter method is by default 'get' and the parameter timeout is by default 5 (seconds).

In case of default value usage the action command can be configured as in this example:

<command command_id="download">download('/fcgi/control/memodata_download')</command>

In case of usage with all parameters the action command can be configured as in this example:

<command command_id="download">download('/rest/memodata_download.php', method='post', timeout=3)</command>

response

The received data of the executed request are the content of the download data. Once the action was executed, the da_rest_client signals the download in a raw result. The sensor_gateway_id of this raw result is equal to the configured device_id of the da_rest_client, which performs the download action (in our example the device_id is 'rest_test').

{
    "error_code": 0, 
    "partial": false, 
    "result_dict": {
        "dl_file": {
            "changed": true, 
            "value": "/opt/azeti/SiteController/tmp/dl-rest_test-2019-03-28T15:30:46.881+0100.zip"
        }, 
        "dl_time": {
            "changed": true, 
            "value": 0.006723880767822266
        }
    }, 
    "sensor_gateway_id": "rest_test", 
    "timestamp": "2019-03-28T15:30:46.882+0100"
}

The keys dl_file and dl_time are fixed for that raw result. dl_file shows file and path of the downloaded data, dl_time shows the download time in seconds.

Both items can be observed by calibrated results:

    <sensor sensor_id="rest_download_file">
    <sensor_class>unknown</sensor_class>
      <upload>always</upload>
      <error_severity>200</error_severity>
      <state_evaluation_expressions>
      <state_evaluation_expression>
        <expression>True</expression>
          <true>%value%</true>
        </state_evaluation_expression>
      </state_evaluation_expressions>
      <sensor_gateway sensor_gateway_id="rest_test">
      <demux>
        <keys>
          <key>dl_file</key>
          </keys>
        </demux>
      </sensor_gateway>
    </sensor>
    <sensor sensor_id="rest_download_time">
    <sensor_class>unknown</sensor_class>
      <unit>seconds</unit>
      <sensor_gateway sensor_gateway_id="rest_test">
      <demux>
        <keys>
          <key>dl_time</key>
          </keys>
        </demux>
        <calibration_rule>
        <rounding_precision>2</rounding_precision>
        </calibration_rule>
      </sensor_gateway>
    </sensor>

The download file handling

The downloaded data are saved in files, the path to that files is by default /opt/azeti/SiteController/tmp, which can be changed in the SiteController.cfg in a section like this:

[da_rest_client]
download_path = /opt/azeti/SiteController/tmp

The download file name is a concatenation of dl-<device_id>-<timestamp>.zip.

During the file write the extension .lock is used and renamed to the extension .zip after ready with writing. This should prevent further file processing before the file write is terminated.