Skip to main content

1E SDK

HttpGetFile

Function

HttpGetFile

Action

A built-in function for downloading content (resources) over HTTP(S) via the Tachyon Background channel, or from an external web-server.

If the file cannot be downloaded, or the downloaded content does not match the hash and size supplied, an error occurs and the instruction is terminated.

The file is downloaded into a randomly named sub-directory of TemporaryDirectory. From version 5.1 onwards, the location of TemporaryDirectory is a configuration setting of the 1E Client.1E Client settings

The sub-directory and file is deleted when the instruction ends. If you want to keep the file, make the instruction copy it to a permanent location.

The following table shows the OS-specific defaults used if the setting is omitted, blank, or invalid. The default is recommended.

Platform

Environment Variable(s)

Default

Windows

TMP

TEMP

%windir%\Temp which is the default %TEMP% location for SYSTEM.

Linux

TMPDIR

/tmp

Nomad integration

If 1E Nomad is available, it will optimize the download, storing a local copy of the file in the Nomad cache, with cache priority 1 and is subject to normal Nomad cache management.

Parameters

URL (string): Either (a) the relative path to be appended to the "Content" directory under the Background Channel URL, or (b) a full URL starting with "http" or "https".

It is a runtime error if the status code from a GET request on the full absolute URL is not 200.

Note

"Content" is created as a virtual folder in IIS during installation of the Tachyon platform.

Note

When an absolute URL is specified and the schema is 'https' then the endpoint requesting the resource will attempt to verify the entire certificate chain of the resource as normal. This can fail if the endpoint does not recognize all the links in the chain of trust. The rules of checking are more rigorous than some browsers, which are often relaxed about the very root of the chain if it is signed using a sha1 algorithm. This means whilst a browser may download the resource and display it, the endpoint might actually complain about the validity of the root Certificate Authority certificate.

To resolve this, you need to get hold of the public key for the root certificate and:

  • On Windows, it must be placed into the local machine trusted root certificate store

  • On macOS, it needs to be in the 'System' folder of the Key Chain and explicitly trusted

  • On other Unix/Linux-based endpoints that use a cacert.pem file, the root certificate should be exported as a base64-encoded CER format file and then the text appended to the cacert.pem file and the Agent restarted.

Hash (string): The SHA256 hash of the file. If the downloaded file's hash does not match this, a runtime error occurs.

Size (integer) : The size of the file in bytes. If the downloaded file's size does not match this, a runtime error occurs.

Suffix (string, optional): Adds the specified suffix to the temporary file name. Usually this is not necessary, but some applications require a filename to end with a certain suffix. If the specified suffix does not start with a '.' then one is added automatically. Cannot be used with the PreserveName parameter.

Stagger (boolean, optional, default:true): Instructs the download operation to either adhere to the configured random execution stagger setting if true, or cause it to download immediately (so no staggering) if set to false. If the agent is running on Windows AND Nomad is installed and available AND it is decided by other means that Nomad will be used, then staggering will not come into effect, regardless of the value, because Nomad will take care of not overloading the network.

PreserveName (boolean, optional, default:false): If false the directory will be the system temporary setting and the filename will be random. If true then directory will be some unique space for the execution of the containing instruction and the stem and suffix in the URL parameter are used as the filename. Cannot be used with the Suffix parameter.

Return values

FilePath (string): The full path of the downloaded file.

Warning

This is a temporary file that persists only while the instruction is live. When the instruction ends the file will be deleted. If you want to keep the file, make the instruction copy it to a permanent location.

Example

A common use for this function is to download a script which can then be executed locally.

Example - download and execute a script

/* Download the script. Since we specify a partial URL (just the filename),
   the full URL is built by combining the specified URL with the root
   of the Tachyon Background channel. Note that because HttpGetFile
   is a built-in function, there is no need to specify a Module name */
@resource1 = HttpGetFile(URL:"MyCustomScript.ps1",
                         Size:2137,
                         Hash:"e0b5bb08b68ed4cdd73d035a775458e34bce1d68ec93a11defa62ca25e3d7037");

/* @script now contains a single row with one column named FilePath, so can
   be passed directly to the Scripting module */
@result = Scripting.Run(Language: "PowerShell", Script: @resource1, InterpretAsJson: true);

To download content from an external web-server, you can instead set the URL property to the full URL of the file to be downloaded.

Example - downloading content from an external URL

/* Download file from web server */
@resource1 = HttpGetFile(URL:"http://webserver.acme.com/MyFile.jpg",
                         Size:73355,
                         Hash:"c9411ef157a1b9e7d8418d0d9297b8df3f633b6a1b2250d735c9b5cd32f1f795");

/* Build command line to copy temporary downloaded file to final location */
@cmd = SELECT "cmd.exe /c copy " || FilePath || " C:\\Pictures\\MyFile.jpg" AS CommandLine
       FROM @resource1;

/* Run the command built above */
NativeServices.RunCommand(CommandLine: @cmd.CommandLine);

/* Downloaded file will now be in C:\Pictures\MyFile.jpg */

Platforms

  • All

Notes

In this section: