Informizely customer feedback surveys
By using the Aculab site, you agree with our use of cookies.

Managing Files

This describes the web services that manage both media files and REST log files that reside on the file store for an account on Aculab Cloud.

When specifying directories, use forward slash as the delimiter.

For services that accept a filetype parameter, the options are "media" or "rest". These correspond to the Media and REST logs tabs on the File Management page at cloud.aculab.com. When working with REST application log files, choose "rest", when working with wav or tiff files, choose "media".

Media files (unencrypted):

Unencrypted media files are uploaded using File Write. Their format is immediately checked for compatibility. Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

Encrypted media files:

To upload a file that you have encrypted, use File Write with the encrypted flag set to true.

Note that encrypted files cannot be checked for compatibility on upload, as they are encrypted. Instead they will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

 This is a low level API. For information on higher level APIs see the High-level Language Wrappers
  • File List

    This lists all the files of a specified type present on the file store of a cloud account. An optional prefix can be specified to determine a subset of files to list.

    Url:https://ws.aculabcloud.net/file_list
    Methods:GET, POST

    ParameterValueDescription
    filetypestringthe type of files to list ("media" or "rest").
    filenamestring (optional)a filename to match. Matches just one file whose name is this string. An empty string matches all files in all folders (the default). The last character can be a '*' wildcard in which case the preceding filename acts exactly as prefix does and lists all files that start with it. If both filename and prefix are provided, filename takes precedence.
    prefixstring (optional)a prefix to match. Matches any file whose name starts with the string. An empty string matches all files in all folders (the default). If both filename and prefix are provided, filename takes precedence.
    maxcountinteger (optional)the maximum number of files to list. The default is 10,000 which is also the maximum value for this parameter.
    startposinteger (optional)the zero-based index of the first file to list. This enables files to be listed in batches when more than 10,000 are present on the cloud. The default is 0.
    tostring (optional)indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is up to the time (exclusive) given. May be used with from to select ranges of dates.
    fromstring (optional)indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is after the time (exclusive) given. May be used with to to select ranges of dates.

    Returns:

    A JSON object containing the files stored on the cloud account together with details of each file represented in a JSON object.

    ParameterValueDescription
    modifiedstringthe last modification time for the file.
    sizeintegerthe size of the file in bytes.
    encryptedbooleantrue if the file is encrypted, false if the file is unencrypted.

    Example:

    https://ws.aculabcloud.net/file_list?filetype=media&prefix=/recordings/voice

    Response:

      {
        "/recordings/voicemail/recording_1.wav": 
        {
          "modified": "2016-09-30_05:54:47", 
          "encrypted": true,
          "size": 254034
        }, 
        "/recordings/voicemail/recording_2.wav": 
        {
          "modified": "2016-09-30_10:31:44", 
          "encrypted": false,
          "size": 245634
        } 
      }
  • File Write

    This uploads a local file onto the cloud file store for a cloud account. Only .wav audio and .tif image media files can be uploaded. The .tif files are constrained to fax format images. For a PUT, the file data to upload is the body of the request. For a POST, the body must contain an HTML form, the file data being the value of one of its fields.

    Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

    Unencrypted media files

    Unencrypted media file formats are checked for compatibility during upload.

    Encrypted media files:

    To upload a file that you have encrypted, set the encrypted flag to true.

    The format of an encrypted file cannot be checked for compatibility on upload, as it is encrypted. Instead it will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

    Url:https://ws.aculabcloud.net/file_write
    Methods:POST, PUT

    ParameterValueDescription
    filetypestringthe type of files to write ("media").
    encryptedstring (optional)whether the file is encrypted ("true", "false"). The default is "false"
    filenamestringthe target filename on the cloud file store, including path.
    time_to_livestringthe time to live (TTL) of the file, expressed as Xm (X minutes), Xh (X hours), or Xd (X days).

    Returns:

    Nothing.

    Example:

    https://ws.aculabcloud.net/file_write?filetype=media&filename=mediafiles/message_1.wav

  • File Move

    This renames a file that is present on the file store of a cloud account.

    Url:https://ws.aculabcloud.net/file_move
    Methods:GET, POST, HEAD

    ParameterValueDescription
    filetypestringthe type of file to rename ("media").
    fromstringthe filename of the file to rename, including path.
    tostringthe target filename, including path.

    Returns:

    Nothing.

    Example:

    https://ws.aculabcloud.net/file_move?filetype=media&from=rec_1.wav&to=rec_2.wav

  • File Get

    This downloads a file present on the file store of a cloud account.

    Url:https://ws.aculabcloud.net/file_get
    Methods:GET, POST, HEAD

    ParameterValueDescription
    filetypestringthe type of file to get ("media" or "rest").
    filenamestringthe filename of a file on the file store on the cloud to download. This must be an exact match of the file that is to be downloaded. Only one file can be downloaded at a time.

    Returns:

    The file data.

    Example:

    https://ws.aculabcloud.net/file_get?filetype=rest&filename=/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.log

  • File Delete

    This deletes one or more files from the file store of a cloud account. Call file_delete_progress to monitor the progress of the deletion of multiple files.

    Url:https://ws.aculabcloud.net/file_delete
    Methods:DELETE, GET, POST

    ParameterValueDescription
    filetypestringthe type of file to delete ("media" or "rest").
    filenamestringa filename specifying the file to delete. This can be a prefix followed by a '*' to match all files and directories starting with the prefix. Setting to '*' will delete all files.
    tostring (optional)indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is up to the time (exclusive) given. May be used with from to select ranges of dates.
    fromstring (optional)indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is after the time (exclusive) given. May be used with to to select ranges of dates.

    Returns:

    A JSON object that contains the following properties:

    ParameterValueDescription
    tokenstringa token that identifies the deletion requested. This token can be used with the file_delete_progress web service to monitor the progress of a deletion.

    Example:

    https://ws.aculabcloud.net/file_delete?filetype=media&filename=voicemail*

    Response:

      {
        token: "2e8903c1_2.1367569618.101"
      }
  • File Delete Progress

    This retrieves the progress of a file deletion from a cloud account initiated by file_delete.

    Url:https://ws.aculabcloud.net/file_delete_progress
    Methods:GET, POST

    ParameterValueDescription
    tokenstringa token returned by a call to the file_delete web service.

    Returns:

    A JSON object describing the status of the deletion.

    ParameterValueDescription
    statusstringthe status of the deletion. Either "in progress" or "completed".
    files_deletedintegerthe number of files deleted. This value will be updated in chunks of up to 10k files while status is 'in progress'. Once the status is 'deleted' then it will contain the total number of files deleted.

    Example:

    https://ws.aculabcloud.net/file_delete_progress?token=2e8903c1_2.1367569618.101

    Response:

      {
        "status": "in progress",
        "files_deleted": 10000
      }
    
      or
    
      {
        "status": "completed",
        "files_deleted": 52820
      }
  • Upload

    Upload provides an asynchronous mechanism for uploading files to Aculab cloud. This API functions slightly differently from the other file management API's

    The first thing to note is that this call doesn't have a return value, on completion it returns a 307 redirect containing the URL where you should PUT your file.

    The second thing to note is that this API doesn't return a JSON response like other API's, only the HTTP status code. In order to know if the file was successfully uploaded you can then call the upload_status call to check on the validation progress.

    If you are using the High-level Language Wrappers then these changes should not be noticable. If you are writing your own wrappers then you will need to take these into consideration.

    Url:https://ws.aculabcloud.net/​upload
    Methods:PUT

    ParameterValueDescription
    filenamestringthe name of the file in your Media Files Store.
    encryptedstringTrue to indicate this is an encrypted file and should not be validated.

    Returns:

    None

    Example:

    https://ws.aculabcloud.net/​upload?​filename=​my_upload.wav

    Response:

    None
  • Upload Status

    This API allows you to check on the status of a file that has been uploaded via the upload API.

    When a non-encrypted file is uploaded it will be validated by a separate service once the upload completes. The status of that validation is then stored in a cache for 1 hour after the upload.

    If a file fails validation that upload_status will contain a detailed error message explaining why the file was rejected. This information will remain available for the next hour. However the underlying file will be automatically deleted. After 1 hour, a deleted file will return the status 'Unknown File' as though the file had never been seen.

    The status for files that pass validation or that are encrypted are retained indefinitely.

    Url:https://ws.aculabcloud.net/​upload_status
    Methods:GET

    ParameterValueDescription
    filenamestringthe name of the file in your Media Files Store.

    Returns:

    A JSON object describing the status of the upload validation.

    ParameterValueDescription
    upload_statusstringThe validation status.

    The upload_status values have the following meanings

    ParameterValueDescription
    In ProgressstringValidation is pending.
    ValidatedstringThe file has passed validation and is ready for use on Aculab Cloud.
    EncryptedstringThe file was uploaded with the encrypted flag, so it can not be validated.
    Unknown FilestringThe file does not exist in at the path specified. This may mean the path or filename is incorrect. Of the file failed validation as was deleted more than 1 hour ago.
    All other valuesstringAll other values are the error message describing the validation failure.

    Example:

    https://ws.aculabcloud.net/​upload_status?​filename=​my_upload.wav

    Response:

      {
        "upload_status": "Validated",
      }