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). 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.

    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
      }