Class: DropboxApi::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dropbox_api/client.rb,
lib/dropbox_api/endpoints/virtual/upload_by_chunks.rb

virtual collapse

sharing collapse

files collapse

users collapse

auth collapse

Instance Method Summary collapse

Constructor Details

#initialize(oauth_bearer = ENV['DROPBOX_OAUTH_BEARER']) ⇒ Client

Returns a new instance of Client.



4
5
6
# File 'lib/dropbox_api/client.rb', line 4

def initialize(oauth_bearer = ENV['DROPBOX_OAUTH_BEARER'])
  @connection_builder = ConnectionBuilder.new(oauth_bearer)
end

Instance Method Details

#add_file_member(file, members, options = {}) ⇒ Object

Adds specified members to a file.

The members parameter can be an Array or a single member element. Each element is represented by either a String or a Metadata::Member object. You can identify a member using his email or a Dropbox ID.

Parameters:

  • file (String)

    File to which to add members. It can be a path or an ID such as id:3kmLmQFnf1AAAAAAAAAAAw.

  • members

    Members to add. Note that even if an email address is given, this may result in a user being directy added to the membership if that email is the user's main account email.

Options Hash (options):

  • quiet (Boolean)

    Whether added members should be notified via email and device notifications of their invite. The default for this field is false.

  • custom_message (String)

    Message to send to added members in their invitation. This field is optional.

  • access_level (AccessLevel)

    AccessLevel union object, describing what access level we want to give new members. The default for this is :viewer.

  • add_message_as_comment (String)

    Optional message to display to added members in their invitation. This field is optional.

See Also:



34
35
36
37
38
39
40
41
42
43
44
45
# File 'lib/dropbox_api/endpoints/sharing/add_file_member.rb', line 34

add_endpoint :add_file_member do |file, members, options = {}|
  validate_options([:quiet, :custom_message, :access_level, :add_message_as_comment], options)
  options[:quiet] ||= false
  options[:custom_message] ||= nil
  options[:access_level] ||= :viewer
  options[:add_message_as_comment] ||= false

  perform_request options.merge({
    file: file,
    members: build_members_param(members)
  })
end

#add_folder_member(folder_id, members, options = {}) ⇒ Object

Allows an owner or editor (if the ACL update policy allows) of a shared folder to add another member.

For the new member to get access to all the functionality for this folder, you will need to call mount_folder on their behalf.

Apps must have full Dropbox access to use this endpoint.

The members parameter can be an Array or a single member element. Each element is represented by either a String or a Metadata::AddMember object. This parameter can be just a string with an email.

You can also build a Metadata::AddMember object and use it in the members parameter, this allows custom options for each member.

Examples:

client = DropboxApi::Client.new
client.add_folder_member "1363389221", "[email protected]"

Parameters:

  • folder_id (String)

    The ID for the shared folder.

  • members (Array<AddMember,String>)

    The intended list of members to add. Added members will receive invites to join the shared folder.

Options Hash (options):

  • quiet (Boolean)

    Whether added members should be notified via email and device notifications of their invite. The default for this field is False.

  • custom_message (String)

    Optional message to display to added members in their invitation. This field is optional.

See Also:



39
40
41
42
43
44
45
46
47
48
# File 'lib/dropbox_api/endpoints/sharing/add_folder_member.rb', line 39

add_endpoint :add_folder_member do |folder_id, members, options = {}|
  validate_options([:quiet, :custom_message], options)
  options[:quiet] ||= false
  options[:custom_message] ||= nil

  perform_request options.merge({
    shared_folder_id: folder_id.to_s,
    members: build_members_param(members)
  })
end

#copy(from, to) ⇒ Object

Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.

Parameters:

  • from (String)

    Path in the user's Dropbox to be copied or moved.

  • to (String)

    Path in the user's Dropbox that is the destination.

Returns:

  • The moved file.



15
16
17
18
19
20
# File 'lib/dropbox_api/endpoints/files/copy.rb', line 15

add_endpoint :copy do |from, to|
  perform_request({
    from_path: from,
    to_path: to
  })
end

#copy_batch(entries, options = {}) ⇒ String, Array

Copy multiple files or folders to different locations at once in the user's Dropbox.

This will either finish synchronously, or return a job ID and do the async copy job in background. Please use #copy_batch_check to check the job status.

Note: No errors are returned by this endpoint.

Parameters:

  • entries (Array<Hash>)

    List of entries to be moved or copied. Each entry must be a hash with two keys: :from_path & :to_path.

Options Hash (options):

  • autorename (Boolean)

    If there's a conflict with any file, have the Dropbox server try to autorename that file to avoid the conflict. The default for this field is false.

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.



25
26
27
28
29
30
31
32
33
34
# File 'lib/dropbox_api/endpoints/files/copy_batch.rb', line 25

add_endpoint :copy_batch do |entries, options = {}|
  validate_options([
    :autorename
  ], options)
  options[:autorename] ||= false

  perform_request(options.merge({
    entries: entries
  }))
end

#copy_batch_check(async_job_id) ⇒ :in_progress, Array

Returns the status of an asynchronous job for #copy_batch. It returns a list of results for each entry.

Parameters:

  • async_job_id (String)

    Id of the asynchronous job. This is the value of a response returned from the method that launched the job.

Returns:

  • (:in_progress, Array)

    This could be either the :in_progress flag or a list of job statuses.



17
18
19
# File 'lib/dropbox_api/endpoints/files/copy_batch_check.rb', line 17

add_endpoint :copy_batch_check do |async_job_id|
  perform_request async_job_id: async_job_id
end

#copy_reference_get(path) ⇒ DropboxApi::Results::GetCopyReferenceResult

Get a copy reference to a file or folder. This reference string can be used to save that file or folder to another user's Dropbox by passing it to #copy_reference_save.

Parameters:

  • path (String)

    The path to the file or folder you want to get a copy reference to.

Returns:



16
17
18
19
20
# File 'lib/dropbox_api/endpoints/files/copy_reference_get.rb', line 16

add_endpoint :copy_reference_get do |path|
  perform_request({
    path: path
  })
end

#copy_reference_save(copy_reference, path) ⇒ DropboxApi::Results::SaveCopyReferenceResult

Save a copy reference returned by #copy_reference_get to the user's Dropbox.

Parameters:

  • copy_reference (String)

    A copy reference returned by #copy_reference_get.

  • path (String)

    Path in the user's Dropbox that is the destination.

Returns:



16
17
18
19
20
21
# File 'lib/dropbox_api/endpoints/files/copy_reference_save.rb', line 16

add_endpoint :copy_reference_save do |copy_reference, path|
  perform_request({
    copy_reference: copy_reference,
    path: path
  })
end

#create_file_request(title, destination) ⇒ Object

Create a file request for a given path.

Parameters:

  • title (String)

    The title of the file request. Must not be empty.

  • destination (String)

    The path of the folder in the Dropbox where uploaded files will be sent. For apps with the app folder permission, this will be relative to the app folder.



15
16
17
18
19
20
# File 'lib/dropbox_api/endpoints/file_requests/create_file_request.rb', line 15

add_endpoint :create_file_request do |title, destination|
  perform_request({
    title: title,
    destination: destination
  })
end

#create_folder(path) ⇒ DropboxApi::Metadata::Folder

Create a folder at a given path.

Parameters:

  • path (String)

    Path in the user's Dropbox to create.

Returns:



13
14
15
16
17
# File 'lib/dropbox_api/endpoints/files/create_folder.rb', line 13

add_endpoint :create_folder do |path|
  perform_request({
    path: path
  })
end

#create_folder_batch(paths, options = {}) ⇒ String, Array

Create multiple folders at once.

This route is asynchronous for large batches, which returns a job ID immediately and runs the create folder batch asynchronously. Otherwise, creates the folders and returns the result synchronously for smaller inputs. You can force asynchronous behaviour by using the :force_async flag. Use #create_folder_batch_check to check the job status.

Note: No errors are returned by this endpoint.

Parameters:

  • paths (Array)

    List of paths to be created in the user's Dropbox. Duplicate path arguments in the batch are considered only once.

Options Hash (options):

  • autorename (Boolean)

    If there's a conflict, have the Dropbox server try to autorename the folder to avoid the conflict. The default for this field is false.

  • force_async (Boolean)

    Whether to force the create to happen asynchronously. The default for this field is false.

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.



28
29
30
31
32
33
34
35
36
37
38
39
# File 'lib/dropbox_api/endpoints/files/create_folder_batch.rb', line 28

add_endpoint :create_folder_batch do |paths, options = {}|
  validate_options([
    :autorename,
    :force_async
  ], options)
  options[:autorename] ||= false
  options[:force_async] ||= false

  perform_request(options.merge({
    paths: paths
  }))
end

#create_folder_batch_check(async_job_id) ⇒ Array

Returns the status of an asynchronous job for create_folder_batch. If success, it returns list of result for each entry.

Parameters:

  • async_job_id (String)

    Id of the asynchronous job. This is the value of a response returned from the method that launched the job.

Returns:

  • (Array)

    A list of one result for each entry.



16
17
18
19
20
# File 'lib/dropbox_api/endpoints/files/create_folder_batch_check.rb', line 16

add_endpoint :create_folder_batch_check do |async_job_id|
  perform_request({
    async_job_id: async_job_id
  })
end

Create a shared link with custom settings. If no settings are given then the default visibility is :public. (The resolved visibility, though, may depend on other aspects such as team and shared folder settings).

NOTE: The settings parameter will only work for pro, business or enterprise accounts. It will return no permission error otherwise.

Parameters:

  • path (String)

    The path to be shared by the shared link.

  • settings (SharedLinkSettings) (defaults to: {})

    The requested settings for the newly created shared link This field is optional.

Options Hash (settings):

  • requested_visibility (Object)

    The requested access for this shared link. This field is optional. Must be one of "public", "team_only" or "password".

  • link_password (Object)

    If requested_visibility is "password" this is needed to specify the password to access the link. This field is optional.

  • expires (Object)

    Expiration time of the shared link. By default the link won't expire. This field is optional.

Returns:



32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# File 'lib/dropbox_api/endpoints/sharing/create_shared_link_with_settings.rb', line 32

add_endpoint :create_shared_link_with_settings do |path, settings = {}|
  validate_options([
    :requested_visibility,
    :link_password,
    :expires
  ], settings)
  settings[:requested_visibility] ||= 'public'
  settings[:link_password] ||= nil
  settings[:expires] ||= nil

  perform_request({
    path: path,
    settings: settings
  })
end

#delete(path, options = {}) ⇒ Object

Delete the file or folder at a given path.

If the path is a folder, all its contents will be deleted too.

A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding Metadata::File or Metadata::Folder for the item at time of deletion, and not a Metadata::Deleted object.

Parameters:

  • path (String)

    Path in the user's Dropbox to delete.

Options Hash (options):

  • parent_rev (String)

    Perform delete if given "rev" matches the existing file's latest "rev". This field does not support deleting a folder. If the given "rev" doesn't match, a Errors::FileConflictError will be raised.



25
26
27
28
29
30
31
# File 'lib/dropbox_api/endpoints/files/delete.rb', line 25

add_endpoint :delete do |path, options = {}|
  validate_options([:parent_rev], options)

  perform_request options.merge({
    path: path
  })
end

#delete_batch(entries) ⇒ String, Array

Delete multiple files/folders at once.

This route is asynchronous, which returns a job ID immediately and runs the delete batch asynchronously. Use #delete_batch_check to check the job status.

Parameters:

  • entries (Array)

    List of entries, each entry is a Hash with these fields: path (mandatory) & parent_rev (optional).

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.



17
18
19
20
21
# File 'lib/dropbox_api/endpoints/files/delete_batch.rb', line 17

add_endpoint :delete_batch do |entries|
  perform_request({
    entries: entries
  })
end

#delete_batch_check(async_job_id) ⇒ :in_progress, Array

Returns the status of an asynchronous job for delete_batch. If success, it returns list of result for each entry.

Parameters:

  • async_job_id (String)

    Id of the asynchronous job.

Returns:

  • (:in_progress, Array)

    This could be either the :in_progress flag or a list of job statuses.



15
16
17
18
19
# File 'lib/dropbox_api/endpoints/files/delete_batch_check.rb', line 15

add_endpoint :delete_batch_check do |async_job_id|
  perform_request({
    async_job_id: async_job_id
  })
end

#download(path, &block) ⇒ Object

Download a file from a user's Dropbox.

Parameters:

  • path (String)

    The path of the file to download.



12
13
14
# File 'lib/dropbox_api/endpoints/files/download.rb', line 12

add_endpoint :download do |path, &block|
  perform_request({path: path}, &block)
end

#get_account(account_id) ⇒ BasicAccount

Get information about a user's account.

Parameters:

  • account_id (String)

    A user's account identifier.

Returns:

  • (BasicAccount)

    Basic information about any account.



13
14
15
# File 'lib/dropbox_api/endpoints/users/get_account.rb', line 13

add_endpoint :get_account do ||
  perform_request account_id: 
end

#get_account_batch(account_ids) ⇒ Array<BasicAccount>

Get information about multiple user accounts. At most 300 accounts may be queried per request.

Parameters:

  • account_ids (Array<String>)

    List of user account identifiers. Should not contain any duplicate account IDs.

Returns:

  • (Array<BasicAccount>)

    Basic information about any account.



15
16
17
# File 'lib/dropbox_api/endpoints/users/get_account_batch.rb', line 15

add_endpoint :get_account_batch do ||
  perform_request account_ids: 
end

#get_current_accountBasicAccount

Get information about the current user's account.

Returns:

  • (BasicAccount)

    Detailed information about the current user's account.



12
13
14
# File 'lib/dropbox_api/endpoints/users/get_current_account.rb', line 12

add_endpoint :get_current_account do
  perform_request nil
end

#get_metadata(path, options = {}) ⇒ Object

Returns the metadata for a file or folder.

Note: Metadata for the root folder is unsupported.

If you request the media_info attribute, note that it could be set to :pending or nil.

Parameters:

  • path (String)

    The path of a file or folder on Dropbox.

Options Hash (options):

  • include_media_info (Boolean)

    If true, media_info is set for photo and video. The default for this field is false.

  • include_has_explicit_shared_members (Boolean)

    If true, the results will include a flag for each file indicating whether or not that file has any explicit members. The default for this field is false.

  • include_deleted (Boolean)

    If true, Metadata::Deleted will be returned for deleted file or folder, otherwise Errors::NotFoundError will be raised. The default for this field is false.



30
31
32
33
34
35
36
37
38
39
40
# File 'lib/dropbox_api/endpoints/files/get_metadata.rb', line 30

add_endpoint :get_metadata do |path, options = {}|
  validate_options([
    :include_media_info,
    :include_deleted,
    :include_has_explicit_shared_members
  ], options)

  perform_request(options.merge({
    path: path
  }))
end

#get_preview(path, &block) ⇒ Object

Get a preview for a file. Currently previews are only generated for the files with the following extensions: .doc, .docx, .docm, .ppt, .pps, .ppsx, .ppsm, .pptx, .pptm, .xls, .xlsx, .xlsm, .rtf

Parameters:

  • path (String)

    The path of the file to preview.



14
15
16
# File 'lib/dropbox_api/endpoints/files/get_preview.rb', line 14

add_endpoint :get_preview do |path, &block|
  perform_request({path: path}, &block)
end

Get the Metadata for a shared link

If a preview url is given, returns the shared file or folder that is represent by that link.

Options Hash (options):

  • path (String)

    If the shared link is to a folder, this parameter can be used to retrieve the metadata for a specific file or sub-folder in this folder. A relative path should be used.

  • link_password (String)

    If the shared link has a password, this parameter can be used.

Returns:

  • (SharedFileMembers)


23
24
25
26
27
28
29
# File 'lib/dropbox_api/endpoints/sharing/get_shared_link_metadata.rb', line 23

add_endpoint :get_shared_link_metadata do |preview_link, options = {}|
  validate_options([:path, :link_password], options)

  perform_request options.merge(
    url: preview_link
  )
end

#get_space_usageSpaceUsage

Get the space usage information for the current user's account.

Returns:

  • (SpaceUsage)

    Information about a user's space usage and quota.



12
13
14
# File 'lib/dropbox_api/endpoints/users/get_space_usage.rb', line 12

add_endpoint :get_space_usage do
  perform_request nil
end

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. Content-Type of the link is determined automatically by the file's mime type.

Parameters:

  • path (String)

    The path to the file you want a temporary link to.



14
15
16
# File 'lib/dropbox_api/endpoints/files/get_temporary_link.rb', line 14

add_endpoint :get_temporary_link do |path|
  perform_request({path: path})
end

#get_thumbnail(path, options = {}, &block) ⇒ Object

Get a thumbnail for an image.

This method currently supports files with the following file extensions: jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB in size won't be converted to a thumbnail.

Examples:

# Save thumbnail to a local file
client = DropboxApi::Client.new
file = File.open("thumbnail.png", "w")
client.get_thumbnail "/dropbox_image.png" do |thumbnail_content|
  file.write thumbnail_content
end
file.close
# Save thumbnail to a local file with .jpg format
client = DropboxApi::Client.new
file = File.open("thumbnail.jpg", "w")
client.get_thumbnail("/dropbox_image.png", :format => :jpeg) do |thumbnail_content|
  file.write thumbnail_content
end
file.close
# Upload thumbnail to Amazon S3 (assuming you're using their SDK)
s3_object = AWS::S3.new.s3.buckets['my-bucket'].objects['key']
#=> <AWS::S3::S3Object ...>
client = DropboxApi::Client.new
client.get_thumbnail "/dropbox_image.png" do |thumbnail_content|
  s3_object.write thumbnail_content
end

Parameters:

  • path (String)

    The path to the image file you want to thumbnail.

Options Hash (options):

  • format (:jpeg, :png)

    The format for the thumbnail image, :jpeg (default) or :png. For images that are photos, :jpeg should be preferred, while png is better for screenshots and digital arts. The default is :jpeg.

  • size (:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768)

    The size for the thumbnail image. The default is :w64h64.



48
49
50
51
52
53
54
55
56
# File 'lib/dropbox_api/endpoints/files/get_thumbnail.rb', line 48

add_endpoint :get_thumbnail do |path, options = {}, &block|
  validate_options([:format, :size], options)
  options[:format] ||= :jpeg
  options[:size] ||= :w64h64

  perform_request(options.merge({
    path: path
  }), &block)
end

#get_thumbnail_batch(paths, options = {}) ⇒ Object

Get a thumbnails for a batch of images.

Parameters:

  • paths (Array<String>)

    The paths to the image files you want thumbnails for.

Options Hash (options):

  • format (:jpeg, :png)

    The format for the thumbnail image, :jpeg (default) or :png. For images that are photos, :jpeg should be preferred, while png is better for screenshots and digital arts. The default is :jpeg.

  • size (:w32h32, :w64h64, :w128h128, :w640h480, :w1024h768)

    The size for the thumbnail image. The default is :w64h64.

  • mode (:strict, :bestfit, :fitone_bestfit)

    How to resize and crop the image to achieve the desired size. The default for this union is strict.



23
24
25
26
27
28
29
30
# File 'lib/dropbox_api/endpoints/files/get_thumbnail_batch.rb', line 23

add_endpoint :get_thumbnail_batch do |paths, options = {}|
  validate_options([:format, :size, :mode], options)
  options[:format] ||= :jpeg
  options[:size] ||= :w64h64
  options[:mode] ||= :strict

  perform_request entries: build_entries_params(paths, options)
end

#list_file_members(file_id, actions = [], options = {}) ⇒ SharedFileMembers

Use to obtain the members who have been invited to a file, both inherited and uninherited members.

Apps must have full Dropbox access to use this endpoint.

Examples:

List file members.

client.list_file_members "1231273663"

List file members, with detail of permission to make owner.

client.list_file_members "1231273663", [:make_owner]

List file members, using the path instead of file ID.

client.list_file_members "/my/file.pdf"

Parameters:

  • file_id (String)

    The ID for the shared file.

  • actions (Array) (defaults to: [])

    This is an optional list of actions. The permissions for the actions requested will be included in the result.

Options Hash (options):

  • include_inherited (Boolean)

    Whether to include members who only have access from a parent shared folder. The default for this field is true.

  • limit (Numeric)

    The maximum number of results that include members, groups and invitees to return per request. The default for this field is 100.

Returns:

  • (SharedFileMembers)

    Shared file user and group membership.

See Also:



37
38
39
40
41
42
43
44
45
# File 'lib/dropbox_api/endpoints/sharing/list_file_members.rb', line 37

add_endpoint :list_file_members do |file_id, actions = [], options = {}|
  validate_options([:limit, :include_inherited], options)
  options[:limit] ||= 100

  perform_request options.merge({
    file: file_id,
    actions: DropboxApi::Metadata::MemberActionList.new(actions)
  })
end

#list_folder(path, options = {}) ⇒ Object

Returns the contents of a folder.

Parameters:

  • path (String)

    The path to the folder you want to read.

Options Hash (options):

  • recursive (Boolean)

    If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is false.

  • include_media_info (Boolean)

    If true, media_info is set for photo and video. The default for this field is false.

  • include_deleted (Boolean)

    If true, Metadata::Deleted will be returned for deleted file or folder, otherwise Errors::NotFoundError will be raised. The default for this field is false.

  • limit (Numeric)

    If present, will specify max number of results per request (Note: Dropbox docs indicate this is "approximate", and more may be returned)



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# File 'lib/dropbox_api/endpoints/files/list_folder.rb', line 29

add_endpoint :list_folder do |path, options = {}|
  validate_options([
    :recursive,
    :include_media_info,
    :include_deleted,
    :shared_link,
    :include_has_explicit_shared_members,
    :limit
  ], options)
  options[:recursive] ||= false
  options[:include_media_info] ||= false
  options[:include_deleted] ||= false
  options[:shared_link] = build_shared_link_param(options[:shared_link]) if options[:shared_link]
  options[:limit] = options[:limit] if options[:limit]
  
  perform_request options.merge({
    path: path
  })
end

#list_folder_continue(cursor) ⇒ Object

Once a cursor has been retrieved from list_folder, use this to paginate through all files and retrieve updates to the folder.

Parameters:

  • cursor (String)

    The cursor returned by your last call to list_folder or list_folder_continue.



17
18
19
# File 'lib/dropbox_api/endpoints/files/list_folder_continue.rb', line 17

add_endpoint :list_folder_continue do |cursor|
  perform_request cursor: cursor
end

#list_folder_get_latest_cursor(options = {}) ⇒ Object

A way to quickly get a cursor for the folder's state. Unlike #list_folder, this doesn't return any entries. This endpoint is for app which only needs to know about new files and modifications and doesn't need to know about files that already exist in Dropbox.

Options Hash (options):

  • path (String)

    The path to the folder you want to read.

  • recursive (Boolean)

    If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. The default for this field is false.

  • include_media_info (Boolean)

    If true, media_info is set for photo and video. The default for this field is false.

  • include_deleted (Boolean)

    If true, Metadata::Deleted will be returned for deleted file or folder, otherwise Errors::LookupError will be returned. The default for this field is false.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
# File 'lib/dropbox_api/endpoints/files/list_folder_get_latest_cursor.rb', line 28

add_endpoint :list_folder_get_latest_cursor do |options = {}|
  validate_options([
    :path,
    :recursive,
    :include_media_info,
    :include_deleted,
    :include_has_explicit_shared_members
  ], options)
  options[:recursive] ||= false
  options[:include_media_info] ||= false
  options[:include_deleted] ||= false

  perform_request options
end

#list_folder_longpoll(cursor, options = {}) ⇒ Object

A longpoll endpoint to wait for changes on an account. In conjunction with list_folder, this call gives you a low-latency way to monitor an account for file changes. The connection will block until there are changes available or a timeout occurs. This endpoint is useful mostly for client-side apps. If you're looking for server-side notifications, check out our webhooks documentation.

Parameters:

  • cursor (String)

    A cursor as returned by list_folder or list_folder_continue.

Options Hash (options):

  • timeout (Numeric)

    A timeout in seconds. The request will block for at most this length of time, plus up to 90 seconds of random jitter added to avoid the thundering herd problem. Care should be taken when using this parameter, as some network infrastructure does not support long timeouts. The default for this field is 30.



25
26
27
28
29
30
31
32
33
34
# File 'lib/dropbox_api/endpoints/files/list_folder_longpoll.rb', line 25

add_endpoint :list_folder_longpoll do |cursor, options = {}|
  validate_options([
    :timeout
  ], options)
  options[:timeout] ||= 30

  perform_request options.merge({
    cursor: cursor
  })
end

#list_folder_members(folder_id, actions = [], options = {}) ⇒ SharedFolderMembers

Returns shared folder membership by its folder ID.

Apps must have full Dropbox access to use this endpoint.

Examples:

List folder members.

client.list_folder_members "1231273663"

List folder members, with detail of permission to make owner.

client.list_folder_members "1231273663", [:make_owner]

Parameters:

  • folder_id (String)

    The ID for the shared folder.

  • actions (Array) (defaults to: [])

    This is an optional list of actions. The permissions for the actions requested will be included in the result.

Options Hash (options):

  • limit (Numeric)

    The maximum number of results that include members, groups and invitees to return per request. The default for this field is 1000.

Returns:

  • (SharedFolderMembers)

    Shared folder user and group membership.

See Also:



30
31
32
33
34
35
36
37
38
# File 'lib/dropbox_api/endpoints/sharing/list_folder_members.rb', line 30

add_endpoint :list_folder_members do |folder_id, actions = [], options = {}|
  validate_options([:limit], options)
  options[:limit] ||= 100

  perform_request options.merge({
    shared_folder_id: folder_id,
    actions: DropboxApi::Metadata::MemberActionList.new(actions)
  })
end

#list_revisions(path, options = {}) ⇒ Object

Return revisions of a file

Parameters:

  • path (String)

    The path to file you want to see the revisions of.

Options Hash (options):

  • limit (Numeric)

    The maximum number of revision entries returned. The default for this field is 10.



16
17
18
19
20
21
22
23
24
25
# File 'lib/dropbox_api/endpoints/files/list_revisions.rb', line 16

add_endpoint :list_revisions do |path, options = {}|
  validate_options([
    :limit
  ], options)
  options[:limit] ||= 10

  perform_request options.merge({
    path: path
  })
end

List shared links of this user.

If no path is given or the path is empty, returns a list of all shared links for the current user.

If a non-empty path is given, returns a list of all shared links that allow access to the given path - direct links to the given path and links to parent folders of the given path. Links to parent folders can be suppressed by setting direct_only to true.

Options Hash (options):

  • path (String)
  • cursor (String)

    The cursor returned by your last call.

  • direct_only (Boolean)

Returns:

  • (ListSharedLinksResult)


25
26
27
28
29
# File 'lib/dropbox_api/endpoints/sharing/list_shared_links.rb', line 25

add_endpoint :list_shared_links do |options = {}|
  validate_options([:path, :cursor, :direct_only], options)

  perform_request options
end

#middlewareObject



8
9
10
# File 'lib/dropbox_api/client.rb', line 8

def middleware
  @connection_builder.middleware
end

#move(from, to, options = {}) ⇒ Object

Move a file or folder to a different location in the user's Dropbox.

If the source path is a folder all its contents will be moved.

Parameters:

  • from (String)

    Path in the user's Dropbox to be copied or moved.

  • to (String)

    Path in the user's Dropbox that is the destination.

Options Hash (options):

  • autorename (Boolean)

    If there's a conflict, have the Dropbox server try to autorename the file to avoid the conflict. The default for this field is false.



20
21
22
23
24
25
26
27
28
29
30
31
32
# File 'lib/dropbox_api/endpoints/files/move.rb', line 20

add_endpoint :move do |from, to, options = {}|
  # We're not implementing support for the `allow_shared_folder` option
  # because according to Dropbox's documentation: "This field is always
  # true for move".
  validate_options([
    :autorename
  ], options)

  perform_request options.merge({
    from_path: from,
    to_path: to
  })
end

#permanently_delete(path, options = {}) ⇒ Object

Permanently delete the file or folder at a given path.

See https://www.dropbox.com/en/help/40

Note: This endpoint is only available for Dropbox Business apps.

Parameters:

  • path (String)

    Path in the user's Dropbox to delete.

Options Hash (options):

  • parent_rev (String)

    Perform delete if given "rev" matches the existing file's latest "rev". This field does not support deleting a folder.



21
22
23
24
25
26
27
# File 'lib/dropbox_api/endpoints/files/permanently_delete.rb', line 21

add_endpoint :permanently_delete do |path, options = {}|
  validate_options([:parent_rev], options)

  perform_request options.merge({
    path: path
  })
end

#restore(path, rev) ⇒ Object

Restore a file to a specific revision

Parameters:

  • path (String)

    The path to the file you want to restore.

  • rev (String)

    The revision to restore for the file.



13
14
15
16
17
18
# File 'lib/dropbox_api/endpoints/files/restore.rb', line 13

add_endpoint :restore do |path, rev|
  perform_request({
    path: path,
    rev: rev
  })
end

Revoke a shared link.

Note that even after revoking a shared link to a file, the file may be accessible if there are shared links leading to any of the file parent folders.

A successful response indicates that the shared link was revoked.

Parameters:

  • url (String)

    shared url which needs to be revoked.



18
19
20
21
22
# File 'lib/dropbox_api/endpoints/sharing/revoke_shared_link.rb', line 18

add_endpoint :revoke_shared_link do |url|
  perform_request({
    url: url
  })
end

#save_url(path, url) ⇒ Object

Save a specified URL into a file in user's Dropbox. If the given path already exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt).

Parameters:

  • path (String)

    The path in Dropbox where the URL will be saved to.

  • url (String)

    The URL to be saved.

Returns:

  • Either the saved file or a reference to the async job.



16
17
18
19
20
21
# File 'lib/dropbox_api/endpoints/files/save_url.rb', line 16

add_endpoint :save_url do |path, url|
  perform_request({
    path: path,
    url: url
  })
end

#save_url_check_job_status(job_id) ⇒ Object

Check the status of a save_url job.

Parameters:

  • job_id (String)

    Id of the asynchronous job. This is the value of a response returned from the method that launched the job.

Returns:

  • The current status of the job.



14
15
16
17
18
# File 'lib/dropbox_api/endpoints/files/save_url_check_job_status.rb', line 14

add_endpoint :save_url_check_job_status do |job_id|
  perform_request({
    async_job_id: job_id
  })
end

#search(query, options = nil, match_field_options = nil) ⇒ Object

Searches for files and folders.

Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing.

Parameters:

  • query (String)

    The string to search for. May match across multiple fields based on the request arguments.

  • options (DropboxApi::Metadata::SearchOptions) (defaults to: nil)

    Options for more targeted search results. This field is optional.

  • match_field_options (DropboxApi::Metadata::SearchMatchFieldOptions) (defaults to: nil)

    Options for search results match fields. This field is optional.



22
23
24
25
26
27
28
29
30
# File 'lib/dropbox_api/endpoints/files/search.rb', line 22

add_endpoint :search do |query, options = nil, match_field_options = nil|
  params = { query: query }

  params[:options] = options.to_hash unless options.nil?

  params[:match_field_options] = match_field_options.to_hash unless match_field_options.nil?

  perform_request(params)
end

#share_folder(path, options = {}) ⇒ DropboxApi::Results::ShareFolderLaunch

Share a folder with collaborators.

Most sharing will be completed synchronously. Large folders will be completed asynchronously. To make testing the async case repeatable, set force_async.

If a ShareFolderLaunch.async_job_id is returned, you'll need to call check_share_job_status until the action completes to get the metadata for the folder.

Apps must have full Dropbox access to use this endpoint.

Parameters:

  • path (String)

    The path to the folder to share. If it does not exist, then a new one is created.

Options Hash (options):

  • member_policy (:anyone, :team)

    Who can be a member of this shared folder. Only applicable if the current user is on a team. The default is :anyone.

  • acl_update_policy (:owner, :editors)

    Who can add and remove members of this shared folder. The default is :owner.

  • shared_link_policy (:anyone, :members)

    The policy to apply to shared links created for content inside this shared folder. The current user must be on a team to set this policy to :members. The default is anyone.

  • force_async (Boolean)

    Whether to force the share to happen asynchronously. The default for this field is false.

Returns:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# File 'lib/dropbox_api/endpoints/sharing/share_folder.rb', line 37

add_endpoint :share_folder do |path, options = {}|
  validate_options([
    :member_policy,
    :acl_update_policy,
    :shared_link_policy,
    :force_async
  ], options)
  options[:member_policy] ||= :anyone
  options[:acl_update_policy] ||= :owner
  options[:shared_link_policy] ||= :anyone
  options[:force_async] ||= false

  begin
    perform_request options.merge({
      path: path
    })
  rescue DropboxApi::Errors::AlreadySharedError => error
    error.shared_folder
  end
end

#token_revokeObject

Revoke the access token for the current account



11
12
13
# File 'lib/dropbox_api/endpoints/auth/token_revoke.rb', line 11

add_endpoint :token_revoke do
  perform_request(nil)
end

#unshare_file(file) ⇒ Object

Remove all members from this file. Does not remove inherited members.

A successful response indicates that the file was unshared.

Parameters:

  • file (String)

    Path or ID of the file in the user's Dropbox to unshare.



14
15
16
17
18
# File 'lib/dropbox_api/endpoints/sharing/unshare_file.rb', line 14

add_endpoint :unshare_file do |file|
  perform_request({
    file: file
  })
end

#upload(path, content, options = {}) ⇒ Object

Creates a new file.

Do not use this to upload a file larger than 150 MB.

For larger files you can use #upload_by_chunks.

Examples:

client = DropboxApi::Client.new
file_content = IO.read "local_image.png"
client.upload "/image.png", file_content
#=> #<DropboxApi::Metadata::File: @name="image.png" ...>
client = DropboxApi::Client.new
client.upload "/file.txt", "Contents of a plain text file."
#=> #<DropboxApi::Metadata::File: @name="file.txt" ...>
client = DropboxApi::Client.new
client.upload "/file.txt", "File contents...", :mode => :add
#=> #<DropboxApi::Metadata::File: @name="file (1).txt" ...>

Parameters:

  • path (String)

    Path in the user's Dropbox to save the file.

  • content

    The contents of the file that will be uploaded. This could be the result of the IO::read method.

Options Hash (options):

  • mode (DropboxApi::Metadata::WriteMode)

    Selects what to do if the file already exists. The default is add.

  • autorename (Boolean)

    If there's a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict. The default for this field is false.

  • client_modified (DateTime)

    The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.

  • mute (Boolean)

    Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If true, this tells the clients that this modification shouldn't result in a user notification. The default for this field is false.

See Also:



50
51
52
53
54
55
56
57
58
59
60
61
# File 'lib/dropbox_api/endpoints/files/upload.rb', line 50

add_endpoint :upload do |path, content, options = {}|
  validate_options([
    :mode,
    :autorename,
    :client_modified,
    :mute
  ], options)

  options[:path] = path
  commit_info = DropboxApi::Metadata::CommitInfo.build_from_options options
  perform_request(commit_info.to_hash, content)
end

#upload_by_chunks(path, content, options = {}) ⇒ Object

Creates a new file using the upload session endpoints. You can use this method to upload files larger than 150 MB.

Examples:

client = DropboxApi::Client.new
File.open "large file.avi" do |file|
  client.upload "/large file.avi", file
  #=> #<DropboxApi::Metadata::File: @name="large file.avi" ...>
end
client = DropboxApi::Client.new
client.upload "/file.txt", "File contents...", :mode => :add
#=> #<DropboxApi::Metadata::File: @name="file (1).txt" ...>

Parameters:

  • path (String)

    Path in the user's Dropbox to save the file.

  • content

    The contents of the file that will be uploaded. This could be the result of the IO::read method.

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • mode (DropboxApi::Metadata::WriteMode)

    Selects what to do if the file already exists. The default is add.

  • autorename (Boolean)

    If there's a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict. The default for this field is false.

  • client_modified (DateTime)

    The value to store as the client_modified timestamp. Dropbox automatically records the time at which the file was written to the Dropbox servers. It can also record an additional timestamp, provided by Dropbox desktop clients, mobile clients, and API apps of when the file was actually created or modified.

  • mute (Boolean)

    Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If true, this tells the clients that this modification shouldn't result in a user notification. The default for this field is false.

  • chunk_size (Numeric)

    The size of each upload chunk. It defaults to 4 MiB.

See Also:



41
42
43
44
45
46
47
48
# File 'lib/dropbox_api/endpoints/virtual/upload_by_chunks.rb', line 41

def upload_by_chunks(path, content, options = {})
  content = StringIO.new(content) if content.is_a?(String)

  uploader = DropboxApi::ChunkedUploader.new(self, path, content, options)
  uploader.start
  uploader.upload
  uploader.finish
end

#upload_session_append_v2(cursor, content, options = {}) ⇒ Object

Append more data to an upload session.

When the parameter close is set, this call will close the session.

A single request should not upload more than 150 MB.

The maximum size of a file one can upload to an upload session is 350 GB.

Calling this method may update the cursor received. In particular, the offset variable will be increased to match the new position. This allows you to make subsequent calls to the endpoint using the same cursor, as you can see in the example.

Examples:

# Rely on the offset position updated by `upload_session_append_v2`
client = DropboxApi::Client.new
cursor = client.upload_session_start('abc')      # cursor.offset => 3
client.upload_session_append_v2(cursor, 'def')   # cursor.offset => 6
client.upload_session_append_v2(cursor, 'ghi')   # cursor.offset => 9
client.upload_session_finish(...)

Parameters:

Options Hash (options):

  • close (Boolean)

    If true, the current session will be closed, at which point you won't be able to call #upload_session_append_v2 anymore with the current session. The default for this field is false.

See Also:

  • UploadSessionCursor


39
40
41
42
43
44
45
46
47
48
49
# File 'lib/dropbox_api/endpoints/files/upload_session_append_v2.rb', line 39

add_endpoint :upload_session_append_v2 do |cursor, content, options = {}|
  validate_options([
    :close
  ], options)

  perform_request(options.merge({
    cursor: cursor.to_hash
  }), content)

  cursor.offset += content.bytesize
end

#upload_session_finish(cursor, commit, content = nil) ⇒ Object

Finish an upload session and save the uploaded data to the given file path.

A single request should not upload more than 150 MB.

The maximum size of a file one can upload to an upload session is 350 GB.

Parameters:



22
23
24
25
26
27
# File 'lib/dropbox_api/endpoints/files/upload_session_finish.rb', line 22

add_endpoint :upload_session_finish do |cursor, commit, content = nil|
  perform_request({
    cursor: cursor.to_hash,
    commit: commit.to_hash
  }, content)
end

#upload_session_start(content, options = {}) ⇒ DropboxApi::Metadata::UploadSessionCursor

Upload sessions allow you to upload a single file in one or more requests, for example where the size of the file is greater than 150 MB.

This call starts a new upload session with the given data. You can then use #upload_session_append_v2 to add more data and #upload_session_finish to save all the data to a file in Dropbox.

A single request should not upload more than 150 MB of file contents.

Options Hash (options):

  • close (Boolean)

    If true, the current session will be closed, at which point you won't be able to call #upload_session_append_v2 anymore with the current session. The default for this field is false.

Returns:



26
27
28
29
30
31
32
33
34
35
36
37
# File 'lib/dropbox_api/endpoints/files/upload_session_start.rb', line 26

add_endpoint :upload_session_start do |content, options = {}|
  validate_options([
    :close
  ], options)

  session = perform_request(options, content)

  DropboxApi::Metadata::UploadSessionCursor.new({
    'session_id' => session.session_id,
    'offset' => content.bytesize
  })
end