About File And Folder Operations

About File and Folder Operations

For all the API calls, you must first obtain an access token. The access token is used to create an instance of the SDK which allows you to access the SDk methods.

Code Sample

 SdkClient.new(session[:access_token])

Copy

file_copy creates a copy of a file or a folder. Any missing folder in the target path will be created.

NOTE:
You cannot perform the file_copy operation on a virutal folder.

Required Parameters

src – Path of the source file to be renamed.
target – Path of the file with the updated name.
safe:
- If set to true, name conflicts are resolved according to the value of the conflictsolve parameter.
- If set to false, the operation overwrites an existing file or folder of the same name. This is the default.
conflictsolve – Defines how name conflicts are resolved if the safe parameter is set to true:
- Set to copy to write a file to the destination folder with a non-conflicting name.
- If not set, the operation is rolled back and operation returns 409 Conflict.
override – Specifies what happens if a file of the same name exists at the target path and the safe parameter is not set:
- Set to overwrite to treat the copied file as completely new.
- Set to modify to treat the new file as a modification of the old one.
- If not set:
  - If the existing file has a deleted attribute set to true, the file is overwritten.
  - If the old file’s deleted attribute is false or not set, the file is modified.

Note: safe, conflictsolve, and override are optional parameters in the request object to copy a file or a folder.

Parameter request format:

 {
        "src": "string",
        "target": "string",
        "safe": false,
        "conflictsolve": "string",
        "override": "string"
    }

Code Sample

 begin
      
        entry = client.file_copy(src,target,safe,conflictsolve,override)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

Example Return Response

 {
        "file": {
            "name": "string",
            "parentPath": "string",
            "checksum": "string",
            "contentAccessible": true,
            "contentToken": "string",
            "deleted": true,
            "extension": "string",
            "size": 0,
            "systemAttributes": {},
            "version": 0,
            "versionCreated": "string",
            "viewUid": [{
                "type": "string",
                "viewType": "string",
                "uid": "string"
            }],
            "uri": "string",
            "shareAssociation": [{
                "uid": "string",
                "visibility": "string",
                "name": "string",
                "type": "string"
            }]
        },
        "folder": {
            "name": "string",
            "parentPath": "string",
            "size": 0,
            "version": 0,
            "versionCreated": "string",
            "count": 0,
            "deleted": true,
            "viewUid": [null],
            "uri": "string",
            "shareAssociation": [null],
            "file": [{
                "name": "string",
                "parentPath": "string",
                "checksum": "string",
                "contentAccessible": true,
                "contentToken": "string",
                "deleted": true,
                "extension": "string",
                "size": 0,
                "systemAttributes": {},
                "version": 0,
                "versionCreated": "string",
                "viewUid": [{
                    "type": "string",
                    "viewType": "string",
                    "uid": "string"
                }],
                "uri": "string",
                "shareAssociation": [{
                    "uid": "string",
                    "visibility": "string",
                    "name": "string",
                    "type": "string"
                }]
            }],
            "folder": [{
                "name": "string",
                "parentPath": "string",
                "size": 0,
                "version": 0,
                "versionCreated": "string",
                "count": 0,
                "deleted": true,
                "viewUid": [null],
                "uri": "string",
                "shareAssociation": [null]
            }]
        }
    }

Create Folder

create_folder creates a folder at the specified path.

NOTE:
You cannot perform the create_folder operation on a virutal folder.

Required Parameters

name – Name of the folder to be created.
path – Path where the folder is to be created.
override – Specifies what happens if a file of the same name exists at the target path and the safe parameter is not set:
- Set to overwrite to treat the copied file as completely new.
- Set to modify to treat the new file as a modification of the old one.
- If not set:
  - If the existing file has a deleted attribute set to true, the file is overwritten.
  - If the old file’s deleted attribute is false or not set, the file is modified.

Note: override is an optional parameter in the request object to create a folder.

Parameter Request Format

 {
        "name": "string",
        "path": "string",
        "override": "string"
    }

Code Sample

 begin
        entry = client.create_folder(folderdata)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

Example Return Response

 {
        "name": "string",
        "parentPath": "string",
        "size": 0,
        "version": 0,
        "versionCreated": "string",
        "count": 0,
        "deleted": true,
        "viewUid": [null],
        "uri": "string",
        "shareAssociation": [null]
    }

Delete

file_delete deletes a file or a folder at the specified path.

NOTE:
You cannot perform the file_delete operation on a virutal folder.

Required Parameters

path – Full path of the file or folder to be deleted.
purge - If true, permanently deletes the file or folder.

Code Sample

 begin
        entry = client.file_delete(path,purge)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

File Download

get_file retrieves file content. Returns the content of the file at the specified path.

Required Parameters

path – The path to the file or folder.

Code Sample

 begin
        path = params[:path] || '/' 
        entry = client.get_file(path)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

File Upload

Chunked and Non-Chunked File Upload

Chunked file uploads allow you to break a large file into small chunks, and then send these pieces to the upload server one-by-one. If an upload were to fail, your app would not have to resend the whole file. It can resume the file upload from the last successfully sent chunk.

NOTE:
You cannot perform the file upload operation on a virutal folder.

File Upload Intent

Use fileUploadIntent to initialize a file upload intent request. A call to this method returns the URL of the uploaded file and the URL which is used in a call to uploadCommit to upload the pieces of the file.

Request Parameters

path – Path where the file is to be uploaded, such as /VZMOBILE
name – Name of the file to be uploaded
size – Size of the file to be uploaded.
checksum – SHA256SUM of the uploaded file
chunk:
- Set to true for chunked file upload.
- Set to false for un-chunked file upload.

Code Sample

 begin
        path = params[:path] || ''
        name = params[:name] || ''
        size = params[:size] || ''
        checksum = params[:checksum] || ''
        chunk = params[:chunk] || 'false'
        entry = client.fileUploadIntent(path,name,size,checksum,chunk)   
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end
    
    Sdk method used in sample: 
    fileUploadIntent

Example Return Response

 {
        "uploadurl": "string",
        "commiturl": "string"
    }

Return Parameters

uploadurl - URLof the uploaded file
commiturl - URL used in a call to uploadCommit to upload the chunks of the file.

Non-Chunked File Upload

Use upload_data method for non-chunked file uploads. A successful call results in the uploaded file.

Request Parametes

chunk - must be false.
Uploadurl – URL of the uploaded file which has been returned from a call to [fileUploadIntent]().
checksum – Checksum specified in a call to [fileUploadIntent]().
offset– The number that represents we need to send the multiple file for the request. For e.g. if the user breaks the file in 3 parts then offset is 1,2, 3 for three consecutive files.
filepath – Path of the file. This path is required by the SDK to calculate binary data of uploaded file.

Code Sample

  begin
        entry = client.upload_data(uploadUrl, checksum,temp_file.read)
    
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        return html_page "Sdk auth error"
      rescue SdkError => e
        logger.info e
        return html_page "Sdk API error #{e}"
      end

Example Return Response

 {
        "uploadurl": "string",
        "commiturl": "string"
    }

Chunked File Upload

Chunked file upload is performed in two steps:

Call to upload_chunk_data to upload chunks of a file.
Call to uploadCommit to complete chunked file upload.

upload_chunk_data:

Request Parametes

chunk - must be true.
Uploadurl – URL of the uploaded file which has been returned from a call to fileUploadIntent.
checksum – Checksum specified in a call to fileUploadIntent.
offset– The number that represents we need to send the multiple file for the request. For e.g. if the user breaks the file in 3 parts then offset is 1,2, 3 for three consecutive files.
filepath – Path of the file. This path is required by the SDK to calculate binary data of uploaded file.

Code Sample

 begin
        offset = 1
        file.each do |filedata|
            temp_file = filedata[:tempfile]
            client.upload_chunk_data(uploadUrl, offset,temp_file.read)	
            offset +=offset
        end
        entry = client.uploadCommit(uploadUrl)	
    
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        return html_page "Sdk auth error"
      rescue SdkError => e
        logger.info e
        return html_page "Sdk API error #{e}"
      end

Example Return Response

 {
        "uploadurl": "string",
        "commiturl": "string"
    }

uploadCommit:

Completes chunked file upload.

Request Parameters

uploadid – URL of the uploaded file which has been returned from a call to fileUploadIntent.

Code Sample

 begin
    
        entry = client.uploadCommit(uploadUrl)	
    
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        return html_page "Sdk auth error"
      rescue SdkError => e
        logger.info e
        return html_page "Sdk API error #{e}"
      end

Example Return Response

 {
        "name": "string",
        "parentPath": "string",
        "checksum": "string",
        "contentAccessible": true,
        "contentToken": "string",
        "deleted": true,
        "extension": "string",
        "size": 0,
        "systemAttributes": {},
        "version": 0,
        "versionCreated": "string",
        "viewUid": [{
            "type": "string",
            "viewType": "string",
            "uid": "string"
        }],
        "uri": "string",
        "shareAssociation": [{
            "uid": "string",
            "visibility": "string",
            "name": "string",
            "type": "string"
        }]
    }

Fullview

fullview retrieves information on all file and folder content.

Required Parameter

virtualfolder – Folder that represents various client types at the root level and contains their respective data.
X-Header-ETag – Omit this header to request a full response. To request only changes since a previous call to fullview, include this header as copied from the response to your previous call to GET /fullview API.

Code Sample

 begin
        entry = client.fullview(virtualfolder,xheaderetag)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error #{e}"
        end
      end

Example Return Response

 {
        "data": {
            "file": [{
                "name": "string",
                "parentPath": "string",
                "checksum": "string",
                "contentAccessible": true,
                "contentToken": "string",
                "deleted": true,
                "extension": "string",
                "size": 0,
                "systemAttributes": {},
                "version": 0,
                "versionCreated": "string",
                "viewUid": [{
                    "type": "string",
                    "viewType": "string",
                    "uid": "string"
                }],
                "uri": "string"
            }],
            "folder": [{
                "name": "string",
                "parentPath": "string",
                "size": 0,
                "version": 0,
                "versionCreated": "string",
                "count": 0,
                "deleted": true,
                "viewUid": [null],
                "uri": "string"
            }],
            "deleted": {
                "path": ["string"]
            }
        }
    }

Metadata

metadata retrieves metadata for the root folder of a user’s Personal Cloud Storage account.

Request Parameters

include_deleted - If set to true, the response includes deleted files and folders. Default is false.
sort - Specifies the sort order of the response items. Syntax is :{field}+{asc|desc}. Valid values for field are:
- name
- versionCreated
- size
- extension
- album, artist
- captureDate
- compilation
- contentType
- creationDate
- favorite
- genre
- height
- modificationDate
- priority
- source
- tags
- title
- timelineDate
count - Maximum items to include in a paginated response, for folder requests. Required if start is specified.
filter - Set to file or folder, to include only those types of items in the response.

Code Sample

 begin
        path = params[:path] || '/'
        entry = client.metadata(path)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          return html_page "Sdk API error  #{e}"
        end
      end

Example Return Response

 {
        "file": {
            "name": "string",
            "parentPath": "string",
            "checksum": "string",
            "contentAccessible": true,
            "contentToken": "string",
            "deleted": true,
            "extension": "string",
            "size": 0,
            "systemAttributes": {},
            "version": 0,
            "versionCreated": "string",
            "viewUid": [{
                "type": "string",
                "viewType": "string",
                "uid": "string"
            }],
            "uri": "string",
            "shareAssociation": [{
                "uid": "string",
                "visibility": "string",
                "name": "string",
                "type": "string"
            }]
        },
        "folder": {
            "name": "string",
            "parentPath": "string",
            "size": 0,
            "version": 0,
            "versionCreated": "string",
            "count": 0,
            "deleted": true,
            "viewUid": [null],
            "uri": "string",
            "shareAssociation": [null],
            "file": [{
                "name": "string",
                "parentPath": "string",
                "checksum": "string",
                "contentAccessible": true,
                "contentToken": "string",
                "deleted": true,
                "extension": "string",
                "size": 0,
                "systemAttributes": {},
                "version": 0,
                "versionCreated": "string",
                "viewUid": [{
                    "type": "string",
                    "viewType": "string",
                    "uid": "string"
                }],
                "uri": "string",
                "shareAssociation": [{
                    "uid": "string",
                    "visibility": "string",
                    "name": "string",
                    "type": "string"
                }]
            }],
            "folder": [{
                "name": "string",
                "parentPath": "string",
                "size": 0,
                "version": 0,
                "versionCreated": "string",
                "count": 0,
                "deleted": true,
                "viewUid": [null],
                "uri": "string",
                "shareAssociation": [null]
            }]
        }
    }

Metadata with Path

metadata retrieves the metadata for a file or folder in a user’s Personal Cloud Storage Account.

Request Parameters

path - Path to the file or folder
include_deleted - If set to true, the response includes deleted files and folders. Default is false.
sort - Specifies the sort order of the response items. Syntax is :{field}+{asc|desc}. Valid values for field are:
- name
- versionCreated
- size
- extension
- album, artist
- captureDate
- compilation
- contentType
- creationDate
- favorite
- genre
- height
- modificationDate
- priority
- source
- tags
- title
- timelineDate
count - Maximum items to include in a paginated response, for folder requests. Required if start is specified.
filter - Set to file or folder, to include only those types of items in the response.

Code Sample

 begin
        path = params[:path] || '/'
        entry = client.metadata(path)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          return html_page "Sdk API error  #{e}"
        end
      end

Example Return Response

 {
        "file": {
            "name": "string",
            "parentPath": "string",
            "checksum": "string",
            "contentAccessible": true,
            "contentToken": "string",
            "deleted": true,
            "extension": "string",
            "size": 0,
            "systemAttributes": {},
            "version": 0,
            "versionCreated": "string",
            "viewUid": [{
                "type": "string",
                "viewType": "string",
                "uid": "string"
            }],
            "uri": "string",
            "shareAssociation": [{
                "uid": "string",
                "visibility": "string",
                "name": "string",
                "type": "string"
            }]
        },
        "folder": {
            "name": "string",
            "parentPath": "string",
            "size": 0,
            "version": 0,
            "versionCreated": "string",
            "count": 0,
            "deleted": true,
            "viewUid": [null],
            "uri": "string",
            "shareAssociation": [null],
            "file": [{
                "name": "string",
                "parentPath": "string",
                "checksum": "string",
                "contentAccessible": true,
                "contentToken": "string",
                "deleted": true,
                "extension": "string",
                "size": 0,
                "systemAttributes": {},
                "version": 0,
                "versionCreated": "string",
                "viewUid": [{
                    "type": "string",
                    "viewType": "string",
                    "uid": "string"
                }],
                "uri": "string",
                "shareAssociation": [{
                    "uid": "string",
                    "visibility": "string",
                    "name": "string",
                    "type": "string"
                }]
            }],
            "folder": [{
                "name": "string",
                "parentPath": "string",
                "size": 0,
                "version": 0,
                "versionCreated": "string",
                "count": 0,
                "deleted": true,
                "viewUid": [null],
                "uri": "string",
                "shareAssociation": [null]
            }]
        }
    }

Move

file_move moves a file or a folder. Any missing folder in the target path will be created.

NOTE:
You cannot perform file_move operation on a virutal folder.

Required Parameters

src – Path of the source file to be renamed.
target – Path of the file with the updated name.
safe:
- If set to true, name conflicts are resolved according to the value of the conflictsolve parameter.
- If set to false, the operation overwrites an existing file or folder of the same name. This is the default.
conflictsolve – Defines how name conflicts are resolved if the safe parameter is set to true:
- Set to copy to write a file to the destination folder with a non-conflicting name.
- If not set, the operation is rolled back and operation returns 409 Conflict.

Note: safe and conflictsolve are optional parameters in the request object to rename a file or a folder.

Parameter Request Format

 {
        "src": "string",
        "target": "string",
        "safe": false,
        "conflictsolve": "string"
    }

Code Sample

 begin
        entry = client.file_move(src,target,safe,conflictsolve)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end
    ```	
        
    ### Rename
    
    [`fileorfolder_rename`](/resources/documentation/vzcloud/Ruby_Reference/Fileops/) renames a file or a folder.
    
    **NOTE:**  
    You cannot perform [`fileorfolder_rename`](/resources/documentation/vzcloud/Ruby_Reference/Fileops/) operation on a [virutal folder](/resources/documentation/vzcloud/API_Developer_Guide/About_Virtual_Folders/).
    
    **Required Parameters**
    
    - `src` – Path of the source file to be renamed.
    - `target` – Path of the file with the updated name.
    - `safe `:
        - If set to *true*, name conflicts are resolved according to the value of the `conflictsolve` parameter. 
        - If set to *false*, the operation overwrites an existing file or folder of the same name. This is the default.
    - `conflictsolve` – Defines how name conflicts are resolved if the `safe` parameter is set to *true*:
        -  Set to *copy* to write a file to the destination folder with a non-conflicting name. 
        -  If not set, the operation is rolled back and operation returns `409 Conflict`.
    
    **Note:** `safe` and `conflictsolve` are optional parameters in the request object to rename a file or a folder.
    
    **Parameter Request Format**
    
    ```json
    {
        "src": "string",
        "target": "string",
        "safe": false,
        "conflictsolve": "string"
    }

Code Sample

 begin
       
        entry = client.fileorfolder_rename(src,target,safe,conflictsolve)
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

Example Return Response

 {
        "file": {
            "name": "string",
            "parentPath": "string",
            "checksum": "string",
            "contentAccessible": true,
            "contentToken": "string",
            "deleted": true,
            "extension": "string",
            "size": 0,
            "systemAttributes": {},
            "version": 0,
            "versionCreated": "string",
            "viewUid": [{
                "type": "string",
                "viewType": "string",
                "uid": "string"
            }],
            "uri": "string",
            "shareAssociation": [{
                "uid": "string",
                "visibility": "string",
                "name": "string",
                "type": "string"
            }]
        },
        "folder": {
            "name": "string",
            "parentPath": "string",
            "size": 0,
            "version": 0,
            "versionCreated": "string",
            "count": 0,
            "deleted": true,
            "viewUid": [null],
            "uri": "string",
            "shareAssociation": [null],
            "file": [{
                "name": "string",
                "parentPath": "string",
                "checksum": "string",
                "contentAccessible": true,
                "contentToken": "string",
                "deleted": true,
                "extension": "string",
                "size": 0,
                "systemAttributes": {},
                "version": 0,
                "versionCreated": "string",
                "viewUid": [{
                    "type": "string",
                    "viewType": "string",
                    "uid": "string"
                }],
                "uri": "string",
                "shareAssociation": [{
                    "uid": "string",
                    "visibility": "string",
                    "name": "string",
                    "type": "string"
                }]
            }],
            "folder": [{
                "name": "string",
                "parentPath": "string",
                "size": 0,
                "version": 0,
                "versionCreated": "string",
                "count": 0,
                "deleted": true,
                "viewUid": [null],
                "uri": "string",
                "shareAssociation": [null]
            }]
        }
    }

Thumbnails

thumbnail retrieves thumbnails for a file. Returns the binary data of the requested thumbnail.

Required Parameters

content-token – The file’s content token, obtained from a call to GET /metadata or GET /fullview.
size – Thumbnail size: xs (24x24), s (64x64), or m (128x128). Either size or th and tw are required.
th – Thumbnail height (in pixels). Either size or th and tw are required.
tw – Thumbnail width (in pixels). Either size or th and tw are required.

Code Sample

 begin
        contentToken = params[:contenttoken] || '/'
        mimetype = params[:mimetype] || '/'
        thumbnail = client.thumbnail(contentToken)
        if mimetype == 'image/jpeg'
        
        thumbimage = '<img  src="data:image/jpeg;base64,'+Base64.encode64(thumbnail)+'"/>'
        end
        if mimetype == 'image/png'
    
        thumbimage = '<img src="data:image/png;base64,'+Base64.encode64(thumbnail)+'"/>'
        end
      rescue SdkAuthError => e
        session.delete(:access_token)  # An auth error means the access token is probably bad
        logger.info "Sdk auth error: #{e}"
        return html_page "Sdk auth error"
      rescue SdkError => e
        if e.http_response.code == '404'
          return html_page "Path not found: #{h path}"
        else
          logger.info "Sdk API error: #{e}"
          return html_page "Sdk API error  #{e}"
        end
      end

About File And Folder Operations

Contents

Copy

Create Folder

Delete

File Download

File Upload

File Upload Intent

Non-Chunked File Upload

Chunked File Upload

Fullview

Metadata

Metadata with Path

Move

Thumbnails