About File And Folder Operations

About File and Folder Operations

Contents

For all the API calls, first create an object of the SDK class so that you can access the SDK functions.

To create an object of the SDK class, pass the following information to the SDK constructor:

  • clientKey - obtained when you created an application in Key Management
  • clientSecret - obtained when you created an application in Key Management
  • callbackUrl - HTTP callback address where the user can access the application. Your app must specify it exactly as you have entered it in Key Management as it is case sensitive.
$sdk = new Thingspace\Cloud\Sdk(clientKey,clientSecret,callbackUrl);

Copy

copy method creates a copy of a file or folder. Any missing folder in the target path is created.

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

Request 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

       try {
	$response = $sdk->copy($source,$target,$safe,$conflictsolve,$override);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

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

createFolder creates a folder at the specified path.

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

Request Parameters

  • name – The 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

       try {
	$response = $sdk->createFolder($name,$path,$override);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

Example Return Response

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

Delete

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

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

Request Parameters

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

Code Sample

       try {
	$response = $sdk->deleteData($path, $purge);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

File Download

getFileContent retrieves content of a specified file.

Required Parameters

  • path – The path to the file or folder.

Code Sample

try {
	$response = $sdk->getFileContent($path);
	$response = $response->getBody()->getContents();
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	} 

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.

File Upload Limit

By default, PHP is set to allow uploads of files with a size of 2 MB or less.

There are many ways to increase the upload size in PHP, such as:

  • configuration changes in .htaccess files (distributed configuration files)
  • configuration options set in ini_set file for Apache HTTP Server

Virutal Folders
You cannot perform the file upload operation on a virutal folder.

NOTES:
- .htaccess is is only used by Apache HTTP Server.
- NGINX server has different way to override the default PHP settings. - You need to set Apache to execute .htaccess file.

SEE ALSO:

File Upload Intent

Use fileUploadIntent method to initiate 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 commitUpload to upload the pieces of the file.

Request Parametes

  • 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

   try {
	$response = $sdk->fileUploadIntent($path,$name,$size,$checksum,$chunk);
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

Response Parameters

  • uploadurl = URL of the uploaded file
  • commiturl = URL which is used in commit call to upload the pieces of file

Example Return Response

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

Non-Chunked File Upload

Use uploadCompleteData 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.
  • filepath – Path of the file. This path is required by the SDK to calculate binary data of uploaded file.

Code Sample

       try {
	$response = $sdk->uploadCompleteData($uploadurl,$checksum,$filepath);
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	return $e->getMessage();	
	}

Chunked File Upload

Chunked file upload is performed in two steps:

  1. Call to uploadChunkData to upload chunks of a file.
  2. Call to commitUpload to complete chunked file upload.

uploadChunkData:

Request Parametes

  • chunk - must be true.
  • Uploadurl – URL of the uploaded file which has been returned from a call to fileUploadIntent.
  • offset– offset number of the file chunk. For example, if the file is to be sent in three chunks, offsets are set to 1,2, and 3 for three consecutive files.
  • filepath – Path of the file. This path is required by the SDK to calculate binary data of the uploaded file.

Code Sample

   try {
	$response = $sdk->uploadChunkData($uploadurl,$offset,$filepath);
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

commitUpload:

This call is only required for chunked file uploads. This is a POST call and requires one parameter as a request parameter:

Code Sample

       try {
	$response = $sdk->commitUpload($commiturl);
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	return $e->getMessage();	
	}

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

getFullview retrieves information on all files and folders in a user’s Personal Cloud Storage account.

Request Parameters

  • 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: FullView call without request parameter

       try {
		$response = $sdk->getFullview();
		$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

Code Sample: FullView call with request parameter (delta view)

   try {
		$response = $sdk->deltaView($virtualfolder,$xHeaderETag);
		$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

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

getMetadata retrieves the metadata for the root folder contents.

Request Parameters

  • include_deleted:
    • Set to true to include deleted files and folders in the response
    • Set to false to exclude deleted files and folders from the response. 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
  • start - Starting point for partial responses, for folder requests. Default is 1.
  • 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

   try {
	$response = $sdk->getMetadata($path,$includeDeleted,$sort, $start, $count , $filter );
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
		try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

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 Parameter

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

Request Parameters

  • path - The path to the file or folder.
  • include_deleted:
    • Set to true to include deleted files and folders in the response
    • Set to false to exclude deleted files and folders from the response. 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
  • start - Starting point for partial responses, for folder requests. Default is 1.
  • 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

   try {

	$response = $sdk->getMetadata($path,$includeDeleted,$sort, $start, $count , $filter );
	$response = json_decode($response->getBody()->getContents(),true);
	} catch (Exception $e) {
		try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

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 Update

updateMetadata updates the metadata of a file.

Request Parameters

  • name – The name of the system attribute to be updated
  • value – The value of the system attribute
  • uri – The URI to the file to be updated

Parameter request format:

{
  "name": "string",
  "value": "string",
  "uri": "string"
}

Code Sample

       try {
	$response = $sdk->updateMetadata($name, $value, $uri);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

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

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

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

Request Parameters

  • src – Full path of the file or folder to be moved
  • target – Full path of the target file or folder to be moved. For files, include the full or changed 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 move a file or a folder.

Parameter request format:

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

Code Sample

       try {
	$response = $sdk->move($source,$target,$safe,$conflictsolve);
	} catch (Exception $e) {
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

Rename

Rename renames a file or a folder.

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

Request Parameters

  • src – Path of the source file which needs 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

       try {
	$response = $sdk->rename($source,$target,$safe,$conflictsolve);
	} catch (Exception $e) {	
	 	try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}  

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

getThumbnail retrieves thumbnails for a file. This method returns the binary data of the requested thumbnail.

Required Parameters

  • content-token – The file’s content token obtained from a call to GET metadata{path} 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

       try {
	$response = $sdk->getThumbnail($contenttoken, $size, $th, $tw);
	$response = $response->getBody()->getContents();
	} catch (Exception $e) {
		try
		{
	  	   return $e->getResponse();	
		}
		finally {
		   return false;
		}
	}

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.