Version 1.5 - Updated on 03/23/2017
Cloud(client_key, client_secret, callback_url [, access_token [, refresh_token [, on_refreshed ]]]
The Python SDK Personal Cloud Storage class. For most applications, you there is one instance of this class for each user.
client_key
— Key obtained from the ThingSpace portalclient_secret
— Secret obtained from the ThingSpace portalcallback_url
— Callback URL obtained from the ThingSpace portal.access_token
- Optional OAuth 2.0 access token that allows the SDK to immediately begin making authenticated calls.refresh_token
- Optional OAuth 2.0 refresh token.on_refreshed
— Callback function you can use to refresh tokens. Passes the Token
object as the only argument.authorize_url
cloud.authorize_url()
Obtains a URL used to start the OAuth 2.0 authorization flow. The URI prompts the users to log on and grant access to their Personal Cloud Storage content.
refresh
cloud.refresh()
Called when an OAuth 2.0 access token expires. Uses a refresh token to obtain a new access token. This call fails if the refresh token has expired.
This method id called internally by the SDK, when an expired access token is detected.
Token
object containing the access_token
and the refresh_token
.CloudError
— HTTP request failureUnauthorizedError
— The user provided a bad or expired refresh token.token
cloud.token(auth_code)
The second part of the standard OAuth 2.0 authorization flow. Uses an authorization code obtained through the OAuth 2.0 redirect_uri
to obtain an access and refresh tokens, used to access an user’s Cloud Storage content.
auth_code
— OAuth 2.0 auth code obtained from the callback.Token
object containing the access_token
and refresh_token
. The SDK may begin making authenticated calls after a successful tokens call.CloudError
— HTTP request failureUnauthorizedError
— The user provided a bad auth_code
.account
cloud.account()
Retrieves the account information.
Account
object containing a user’s quota usage and id.CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired token.contacts
cloud.contacts([ page [, count [, query [, sort]]]])
Retrieves a list of a user’s contacts.
Parameters:
page
- Optional page number, defaults to 1.count
- Optional number of results to return. Defaults to 200.query
— Lucene style search querysort
- Optional sort parameter. Syntax is: {field}+{asc or desc}
.Returns: A list of Contact
objects
Errors:
CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokencreate_contact
cloud.create_contact(contact)
Creates a contact
Parameters:
contact
- Contact object to be createdReturns: The created Contact
object with id
and version
fields populated
Errors:
CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokendelete_contact
cloud.delete_contact(contact)
Deletes a contact
Parameters:
contact
- Contact object to be deleted. id
must be populated.Returns: None
Errors:
CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenupdate_contact
cloud.update_contact(contact)
Updates a contact.
Parameters:
contact
- Contact object to be updated. version
and id
must be populated.Returns: The updated Contact
object with id
and version
fields populated. version
field is incremented upon a successful update.
Errors:
ConflictError
- The version provied does not match the server’s record.CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenfavorite
cloud.favorite(uris [, createversion])
Adds a file or folder to favorites.
uris
- string uri or list of uris returned from a fullview or metadata callcreateversion
- Specifies if a new version of a file or folder is to be created:NotFoundError
- URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenfavorites
cloud.favorites([ virtualfolder [, type [, filetype]]])
Retrieves favorite files and folders.
virtualfolder
- Optional. Virtual folder from which to get favorites. Defaults to VZMOBILE
.type
- Used to restrict the search results. Possible values are:filetype
- The type of the favorite. Possible values are:files
- Array of CloudFile
objectsfolders
- Array of CloudFolder
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenunfavorite
cloud.unfavorite(uri [, createversion])
Removes a file or folder from favorites.
uris
- URIs returned from a fullview
or metadata
callcreateversion
- Specifies if a new version of a file or folder is to be created:NotFoundError
- URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokencopy
cloud.copy(file_or_path, target_path [, safe [, override [, conflictsolve ]]])
Copies a file or folder.
file_or_path
— Path where the folder or a file is to be copied fromtarget_path
— Path where the folder or a file is to be copied tosafe
- If set to true, ensures that name conflicts are resolved according to the value of the conflictsolve
parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name.override
- Specifies what happens when a folder of the same name already exists at the specified path:conflictsolve
- Defines how name conflicts are resolved when safe
parameter is set to true. If conflictsolve is set to copy, a new file is written to the destination folder with a non-conflicting name. If conflictsolve is not set, the file is not copied and a ConflictError
is raised.ConflictError
- Occurs when safe
is set to true and there is a conflict.NotFoundError
- Path not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokencreate_folder
cloud.create_folder_url(path [, override ])
Creates a folder.
path
— Path where the folder is to be createdoverride
— Specifies what happens when a folder of the same name already exists at the specified path:CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokendelete
cloud.delete(file_or_path [, purge ])
Deletes a file or folder.
file_or_path
— a CloudFile or the path of the file to be deleted.purge
— If set to true, permanently deletes a file or folder. Defaults to false.NotFoundError
- The path not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokendownload
cloud.download_url(file_or_path)
Retrieves a download URL for a CloudFile
object
file_or_path
— a CloudFile
or the path of the file to be downloaded.file_metadata
cloud.file_metadata(path)
Retrieves metadata for a file.
path
— Path to the fileCloudFile
containing the metadata of the fileCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenNotFoundError
- The resource was not found.fullview
cloud.fullview(etag)
Obtains information on all files and folders in a user’s Personal Cloud Storage account.
Return value contains a property etag
. Use etag
as an argument to a fullview
call to retrieve changes between two subsequent fullview
calls.
etag
— Lucene style search queryfiles
- array of CloudFile
objectsempty_folders
- Array of empty CloudFolder
Objects in the user’s cloudetag
- Etag
used in subsequent fullview
calls to retrieve the changes to the content of a user’s Personal Cloud Storage accountdeleted
- Array of paths that have been deleted since the last fullview callCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenOutOfSyncError
- Specified etag
is too far out of date. Delete cached files and resync by calling fullview
without etag
.metadata
cloud.metadata(path)
Retrieves the metadata of a folder. The response includes the metadata for the folder’s contents, including files and subfolders.
path
— Current folder’s path and name. Defaults to the root /
.files
- array of CloudFile
objectsfolders
- array of CloudFolder
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenNotFoundError
- The resource was not found.move
cloud.move(file_or_path, target_path [, safe [, conflictsolve ]])
Moves a file or folder.
file_or_path
— Path where the folder or a file is to be moved from.target_path
— Path where the folder or a file is to be moved to.safe
- If set to true, ensures that name conflicts are resolved according to the value of the conflictsolve
parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name.override
- Specifies what happens when a folder of the same name already exists at the specified path:conflictsolve
- Defines how name conflicts are resolved when safe
parameter is set to true. If conflictsolve is set to copy, a new file is written to the destination folder with a non-conflicting name. If conflictsolve is not set, the file is not copied and a ConflictError
is raised.NotFoundError
- The path not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenrename
cloud.rename(file_or_path, target_path [, safe [, conflictsolve ]]) Renames a file or folder
file_or_path
— Path to the file or folder to be renamedtarget_path
— Path to the renamed file or foldersafe
- If set to true, ensures that name conflicts are resolved according to the value of the conflictsolve
parameter. Defaults to false, in which case the operation overwrites an existing file or folder of the same name.override
- Specifies what happens when a folder of the same name already exists at the specified path:conflictsolve
- Defines how name conflicts are resolved when safe
parameter is set to true. If conflictsolve is set to copy, a new file is written to the destination folder with a non-conflicting name. If conflictsolve is not set, the file is not copied and a ConflictError
is raised.NotFoundError
- The path was not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, the user has a bad or expired tokensearch
cloud.search(query [, sort [, virtualfolder [, page [, count]]]])
Searches for files or folders.
query
— Lucene style search querysort
- Optional sort parameter. Syntax is: {field}+{asc or desc}
.virtualfolder
- Optional virtualfolder to search in. Default is VZMOBILE
.page
- Optional page number. Default is 1.count
- Optional number of results to return. Default is 20, max is 100.files
- array of CloudFile
objectsfolders
- array of CloudFolder
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenupload
cloud.upload(file_or_path, upload_path [, name [, chunked [, chunk_size ]]])
Uploads a file.
file_or_path
— Either a file object or a path from where the file is to be uploaded.upoad_path
- Path where the file is to be uploaded toname
- Optional. New name of the file, defaults to the current name.chunked
- Optional. If set to true, forces smaller files to be uploaded in chunks.chunk_size
- Optional chunk size in bytes.CloudFile
object containing metadata of the uploaded fileCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenadd_playlist_items
cloud.add_playlist_items(playlist_uid, playlist_items)
Adds items to a playlist.
playlist_uid
- playlist uid returned from a playlists
callplaylist_items
- array of paths to the items that are to be addedPlaylistAdd
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokencreate_playlist
cloud.create_playlist(name, type, paths)
Retrieves the items in a playlist.
name
- Name of the playlisttype
-The type of the playlist which can be one of the following:paths
- array of paths to the itemsPlaylist
objectCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokendelete_playlist
cloud.delete_playlist(playlist_uid)
Deletes a playlist.
playlist_uid
- playlist UID returned from a playlists
callNotFoundError
- The playlist is not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenplaylist
cloud.playlist(playlist_uid)
Retrieves a single playlist’s definition.
playlist_uid
- playlist uid returned from a playlists
callPlaylist
objectNotFoundError
- The playlist is not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenplaylist_items
cloud.playlist_items(playlist_uid [, page [, count [, sort ]]])
Retrieves the items in a playlist.
playlist_uid
- playlist uid returned from a playlists
callpage
- Optional page number, defaults to 1.count
- Optional number of results to return. Defaults to 20, max is 100.sort
- Controls the sort order of the response. Syntax is {field}+{asc or desc}
.PlaylistItem
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenplaylists
cloud.playlists( [, type [, page [, count [, sort ]]]])
Retrieves all playlists.
type
-The type of the playlist which can be one of the following:page
- Optional page number, defaults to 1.count
- Optional number of results to return. Defaults to 20, max is 100.sort
- Controls the sort order of the response. Syntax is {field}+{asc or desc}
.Playlist
objectsCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenremove_playlist_item
cloud.remove_playlist_item(playlist_uid, itemuid)
Removes an item from a playlist.
playlist_uid
- playlist UID returned from a playlists
callitemuid
- playlist item returned from a playlist_items
callNotFoundError
- The playlist is not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenupdate_playlist
cloud.update_playlist(playlist_uid, name, type)
Updates the metadata of the playist. This method does not alter a playlist’s contents.
playlist_uid
- playlist’s UID returned from a playlists
callname
- name of the playlisttype
-The type of the playlist which can be one of the following:Playlist
objectNotFoundError
- The playlist is not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenupdate_playlist_definition
cloud.update_playlist_definition(playlist_uid, name, type, paths)
Updates the metadata and items of a playlist.
playlist_uid
- playlist UID returned from a playlists
callname
- name of the playlisttype
-The type of the playlist which can be one of the following:paths
- array of paths to the itemsPlaylist
objectNotFoundError
- The playlist not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenshare
cloud.share(resources [, name [, expires_seconds]])
Shares a list of files or folders
Parameters:
resources
- A ShareRequest
object or a list of ShareRequest
objectsname
— Name of the shareexpires_seconds
- Number of seconds the is to last. Defaults to one day. If 0 is passed shares wont expire.Returns: a Share
object containing the resources shared.
Errors:
NotFoundError
- The resource not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenshares
cloud.shares([ count [, cursor [, filter [, since [, until ]]]]])
Retrieves shared files and folders.
Parameters:
count
- Optional number of results to return. Defaults to 20, max is 200.cursor
— Used in pagination of the response. Returned in SharesCursor
object from other shares calls.filter
- Filters returned shares. Currently the value can only be outbound (shared by the user).since
- The date and time in the W3C date and time format, after which messages are to be returned.until
- The date and time in the W3C date and time format, until which messages are to be returned.Returns:
shares
- List of Share
objectsshares_cursor
- A SharesCursor
object used to paginate through shared resources.Errors:
CloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenunshare
cloud.unshare(uid)
Removes a file or folder from shares.
uid
- Share UID returned from a share
requestNotFoundError
- The Share not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokentag
cloud.tag(uri, tags [, createversion])
Tags a file or folder.
uri
- string URI returned from a fullview
or metadata
calltags
- A string of tagscreateversion
- Specifies if a new version of a file or folder is to be created:NotFoundError
- The URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokentags
cloud.tags(path)
Retrieves a list of tagged files and folders.
path
— Full path to the file or folderNotFoundError
- The path not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenuntag
cloud.untag(uri [, createversion])
Removes tags from a file or folder.
uri
- String URI returned from a fullview
or metadata
callcreateversion
- Specifies if a new version of a file or folder is to be created:NotFoundError
- The URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenempty_trash
cloud.empty_trash([virtualfolder])
Permenantly removes all files and folders from the trash.
Parameters:
virtualfolder
- Optional virtual folder to empty, defaults to ‘VZMOBILE’.Returns: None
Errors:
NotFoundError
- The virtual not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, a bad or expired tokenrestore
cloud.restore(file_or_path)
Restores a file or folder.
file_or_path
— a CloudFile or the path to the file or folder to be restored.NotFoundError
- The file or folder not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokentrash
cloud.trash([virtualfolder [, sort [, page [, count [, deep [, filter ]]]]])
Retrieves a list of deleted files and folders.
Parameters:
virtualfolder
- Optional virtualfolder to empty, defaults to ‘VZMOBILE’sort
- Optional sort parameter. Syntax is: {field}+{asc or desc}
.virtualfolder
- Optional virtualfolder to search in, defaults to ‘VZMOBILE’page
- Optional page number, defaults to 1count
- Optional number of results to return. Defaults to 20, max is 100.filter
- Optional filter, If set to file, returns files in the response. If set to folder, returns folders in the response. The default will return files and folders.Returns: files, folders
files
- array of CloudFile
objectsfolders
- array of CloudFolder
objectsErrors:
NotFoundError
- The virtualfolder was not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, the user has a bad or expired tokencreate_virtualfolder
cloud.create_virtualfolder(name)
Creates a virtual folder.
name
— Name of the virtual folderCloudFolder
objectCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokendelete_vitualfolder
cloud.delete_vitualfolder(name [, force ])
Deletes a virtual folder.
name
— Name of the virtual folderforce
- Boolean value.NotFoundError
- The URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenrename_virtualfolder
cloud.rename_virtualfolder(old_name, new_name)
Renames a virtual folder.
old_name
— Current name of the virtual folderforce
- New name of the virtual folderCloudFolder
NotFoundError
- The URI not foundCloudError
— HTTP request failureUnauthorizedError
— Unauthorized, bad or expired tokenCopyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.