Cloud

Class: Cloud

Version 1.5 - Updated on 03/23/2017

Contents

Introduction

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.

  • Parameters:
    • client_key — Key obtained from the ThingSpace portal
    • client_secret — Secret obtained from the ThingSpace portal
    • callback_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.
  • Returns: SDK instance

Authentication and Authorization

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.

  • Returns: A String URL used to start the authentication process.

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.

  • Returns: Token object containing the access_token and the refresh_token.
  • Errors:
    • CloudError — HTTP request failure
    • UnauthorizedError — 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.

  • Parameters:
    • auth_code — OAuth 2.0 auth code obtained from the callback.
  • Returns: Token object containing the access_token and refresh_token. The SDK may begin making authenticated calls after a successful tokens call.
  • Errors:
    • CloudError — HTTP request failure
    • UnauthorizedError — The user provided a bad auth_code.

Account Information

account

cloud.account()

Retrieves the account information.

  • Returns: An Account object containing a user’s quota usage and id.
  • Errors:
    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token.

Contacts

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 query
    • sort - Optional sort parameter. Syntax is: {field}+{asc or desc}.

  • Returns: A list of Contact objects

  • Errors:

    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

create_contact

cloud.create_contact(contact)

Creates a contact

  • Parameters:

    • contact - Contact object to be created

  • Returns: The created Contact object with id and version fields populated

  • Errors:

    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

delete_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 failure
    • UnauthorizedError — Unauthorized, bad or expired token

update_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 failure
    • UnauthorizedError — Unauthorized, bad or expired token

Favorites

favorite

cloud.favorite(uris [, createversion])

Adds a file or folder to favorites.

  • Parameters:
    • uris - string uri or list of uris returned from a fullview or metadata call
    • createversion - Specifies if a new version of a file or folder is to be created:
      • false (default) - a new version of a file or folder is not created.
      • true - a new version of a file or folder is created.
  • Returns: None
  • Errors:
    • NotFoundError - URI not found
    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

favorites

cloud.favorites([ virtualfolder [, type [, filetype]]])

Retrieves favorite files and folders.

  • Parameters:
    • virtualfolder - Optional. Virtual folder from which to get favorites. Defaults to VZMOBILE.
    • type - Used to restrict the search results. Possible values are:
      • file&folder (default)
      • file
      • folder
    • filetype - The type of the favorite. Possible values are:
      • all (default)
      • documents
      • image
      • music
      • video
  • Returns: files, folders
    • files - Array of CloudFile objects
    • folders - Array of CloudFolder objects
  • Errors:
    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

unfavorite

cloud.unfavorite(uri [, createversion])

Removes a file or folder from favorites.

  • Parameters:
    • uris - URIs returned from a fullview or metadata call
    • createversion - Specifies if a new version of a file or folder is to be created:
      • false (default) - a new version of a file or folder is not created.
      • true - a new version of a file or folder is created.
  • Returns: None
  • Errors:
    • NotFoundError - URI not found
    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

File and Folder Operations

copy

cloud.copy(file_or_path, target_path [, safe [, override [, conflictsolve ]]])

Copies a file or folder.

  • Parameters:
    • file_or_path — Path where the folder or a file is to be copied from
    • target_path — Path where the folder or a file is to be copied 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:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
    • 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.
  • Returns: the copy of the file or folder
  • Errors:
    • ConflictError - Occurs when safe is set to true and there is a conflict.
    • NotFoundError - Path not found
    • CloudError — HTTP request failure
    • UnauthorizedError — Unauthorized, bad or expired token

create_folder

cloud.create_folder_url(path [, override ])

Creates a folder.

  • Parameters:
    • path — Path where the folder is to be created
    • override — Specifies what happens when a folder of the same name already exists at the specified path:
      • overwrite - overwrites the existing folder.
      • modify - treats the new folder as a modification of the existing folder.
      If the override parameter is not set, the following algorithm is applied:
      • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
      • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
    • Returns: new folder
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    delete

    cloud.delete(file_or_path [, purge ])

    Deletes a file or folder.

    • Parameters:
      • 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.
    • Returns: None
    • Errors:
      • NotFoundError - The path not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    download

    cloud.download_url(file_or_path)

    Retrieves a download URL for a CloudFile object

    • Parameters:
      • file_or_path — a CloudFile or the path of the file to be downloaded.
    • Returns: String URL you can use to download the file.

    file_metadata

    cloud.file_metadata(path)

    Retrieves metadata for a file.

    • Parameters:
      • path — Path to the file
    • Returns: A CloudFile containing the metadata of the file
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token
      • NotFoundError - 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.

    • Parameters:
      • etag — Lucene style search query
    • Returns: files, folders
      • files - array of CloudFile objects
      • empty_folders - Array of empty CloudFolder Objects in the user’s cloud
      • etag - Etag used in subsequent fullview calls to retrieve the changes to the content of a user’s Personal Cloud Storage account
      • deleted - Array of paths that have been deleted since the last fullview call
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token
      • OutOfSyncError - 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.

    • Parameters:
      • path — Current folder’s path and name. Defaults to the root /.
    • Returns: files, folders
      • files - array of CloudFile objects
      • folders - array of CloudFolder objects
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token
      • NotFoundError - The resource was not found.

    move

    cloud.move(file_or_path, target_path [, safe [, conflictsolve ]])

    Moves a file or folder.

    • Parameters:
      • 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:
        • overwrite - overwrites the existing folder.
        • modify - treats the new folder as a modification of the existing folder.
        If the override parameter is not set, the following algorithm is applied:
        • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
        • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
      • 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.
    • Returns: The moved file or folder
    • Errors:
      • NotFoundError - The path not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    rename

    cloud.rename(file_or_path, target_path [, safe [, conflictsolve ]]) Renames a file or folder

    • Parameters:
      • file_or_path — Path to the file or folder to be renamed
      • target_path — Path to the renamed file or folder
      • 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:
        • overwrite - overwrites the existing folder.
        • modify - treats the new folder as a modification of the existing folder.
        If the override parameter is not set, the following algorithm is applied:
        • If the existing folder’s deleted attribute is set to true, the folder is overwritten.
        • If the existing folder’s deleted attribute is set to false or not set, the existing folder is modified.
      • 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.
    • Returns: The renamed CloudFile or CloudFolder
    • Errors:
      • NotFoundError - The path was not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, the user has a bad or expired token

    cloud.search(query [, sort [, virtualfolder [, page [, count]]]])

    Searches for files or folders.

    • Parameters:
      • query — Lucene style search query
      • sort - 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.
    • Returns: files, folders
      • files - array of CloudFile objects
      • folders - array of CloudFolder objects
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    upload

    cloud.upload(file_or_path, upload_path [, name [, chunked [, chunk_size ]]])

    Uploads a file.

    • Parameters:
      • 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 to
      • name - 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.
    • Returns: CloudFile object containing metadata of the uploaded file
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    Playlists

    add_playlist_items

    cloud.add_playlist_items(playlist_uid, playlist_items)

    Adds items to a playlist.

    • Parameters:
      • playlist_uid - playlist uid returned from a playlists call
      • playlist_items - array of paths to the items that are to be added
    • Returns: a list of PlaylistAdd objects
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    create_playlist

    cloud.create_playlist(name, type, paths)

    Retrieves the items in a playlist.

    • Parameters:
      • name - Name of the playlist
      • type -The type of the playlist which can be one of the following:
        • image
        • music
        • video
        • image-video
      • paths - array of paths to the items
    • Returns: the created Playlist object
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    delete_playlist

    cloud.delete_playlist(playlist_uid)

    Deletes a playlist.

    • Parameters:
      • playlist_uid - playlist UID returned from a playlists call
    • Returns: None
    • Errors:
      • NotFoundError - The playlist is not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    playlist

    cloud.playlist(playlist_uid)

    Retrieves a single playlist’s definition.

    • Parameters:
      • playlist_uid - playlist uid returned from a playlists call
    • Returns: a single Playlist object
    • Errors:
      • NotFoundError - The playlist is not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    playlist_items

    cloud.playlist_items(playlist_uid [, page [, count [, sort ]]])

    Retrieves the items in a playlist.

    • Parameters:
      • playlist_uid - playlist uid returned from a playlists call
      • 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}.
    • Returns: an array of PlaylistItem objects
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    playlists

    cloud.playlists( [, type [, page [, count [, sort ]]]])

    Retrieves all playlists.

    • Parameters:
      • type -The type of the playlist which can be one of the following:
        • image
        • music
        • video
        • image-video
      • 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}.
    • Returns: an array of Playlist objects
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    remove_playlist_item

    cloud.remove_playlist_item(playlist_uid, itemuid)

    Removes an item from a playlist.

    • Parameters:
      • playlist_uid - playlist UID returned from a playlists call
      • itemuid - playlist item returned from a playlist_items call
    • Returns: None
    • Errors:
      • NotFoundError - The playlist is not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    update_playlist

    cloud.update_playlist(playlist_uid, name, type)

    Updates the metadata of the playist. This method does not alter a playlist’s contents.

    • Parameters:
      • playlist_uid - playlist’s UID returned from a playlists call
      • name - name of the playlist
      • type -The type of the playlist which can be one of the following:
        • image
        • music
        • video
        • image-video
    • Returns: the updated Playlist object
    • Errors:
      • NotFoundError - The playlist is not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    update_playlist_definition

    cloud.update_playlist_definition(playlist_uid, name, type, paths)

    Updates the metadata and items of a playlist.

    • Parameters:
      • playlist_uid - playlist UID returned from a playlists call
      • name - name of the playlist
      • type -The type of the playlist which can be one of the following:
        • image
        • music
        • video
        • image-video
      • paths - array of paths to the items
    • Returns: the updated Playlist object
    • Errors:
      • NotFoundError - The playlist not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    Shares

    share

    cloud.share(resources [, name [, expires_seconds]])

    Shares a list of files or folders

    • Parameters:

      • resources - A ShareRequest object or a list of ShareRequest objects
      • name — Name of the share
      • expires_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 found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    shares

    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 objects
      • shares_cursor - A SharesCursor object used to paginate through shared resources.

    • Errors:

      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    unshare

    cloud.unshare(uid)

    Removes a file or folder from shares.

    • Parameters:
      • uid - Share UID returned from a share request
    • Returns: None
    • Errors:
      • NotFoundError - The Share not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    Tags

    tag

    cloud.tag(uri, tags [, createversion])

    Tags a file or folder.

    • Parameters:
      • uri - string URI returned from a fullview or metadata call
      • tags - A string of tags
      • createversion - Specifies if a new version of a file or folder is to be created:
        • false (default) - a new version of a file or folder is not created.
        • true - a new version of a file or folder is created.
    • Returns: String representing the file or folder’s updated tags
    • Errors:
      • NotFoundError - The URI not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    tags

    cloud.tags(path)

    Retrieves a list of tagged files and folders.

    • Parameters:
      • path — Full path to the file or folder
    • Returns: String representing the file or folder’s tags
    • Errors:
      • NotFoundError - The path not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    untag

    cloud.untag(uri [, createversion])

    Removes tags from a file or folder.

    • Parameters:
      • uri - String URI returned from a fullview or metadata call
      • createversion - Specifies if a new version of a file or folder is to be created:
        • false (default) - a new version of a file or folder is not created.
        • true - a new version of a file or folder is created.
    • Returns: None
    • Errors:
      • NotFoundError - The URI not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    Trash

    empty_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 found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, a bad or expired token

    restore

    cloud.restore(file_or_path)

    Restores a file or folder.

    • Parameters:
      • file_or_path — a CloudFile or the path to the file or folder to be restored.
    • Returns: None
    • Errors:
      • NotFoundError - The file or folder not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    trash

    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 1
      • count - 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 objects
      • folders - array of CloudFolder objects

    • Errors:

      • NotFoundError - The virtualfolder was not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, the user has a bad or expired token

    Virtual Folders

    create_virtualfolder

    cloud.create_virtualfolder(name)

    Creates a virtual folder.

    • Parameters:
      • name — Name of the virtual folder
    • Returns: The newly created CloudFolder object
    • Errors:
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    delete_vitualfolder

    cloud.delete_vitualfolder(name [, force ])

    Deletes a virtual folder.

    • Parameters:
      • name — Name of the virtual folder
      • force - Boolean value.
        • false (default) - does not remove the virtual folder.
        • true - removes the virtual folder even if it contains data.
    • Returns: None
    • Errors:
      • NotFoundError - The URI not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

    rename_virtualfolder

    cloud.rename_virtualfolder(old_name, new_name)

    Renames a virtual folder.

    • Parameters:
      • old_name — Current name of the virtual folder
      • force - New name of the virtual folder
    • Returns: The renamed CloudFolder
    • Errors:
      • NotFoundError - The URI not found
      • CloudError — HTTP request failure
      • UnauthorizedError — Unauthorized, bad or expired token

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