Class: DropboxApi::Client

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

def initialize(
  oauth_bearer = ENV['DROPBOX_OAUTH_BEARER'],
  access_token: nil,
  on_token_refreshed: nil
)
  if access_token
    @connection_builder = ConnectionBuilder.new(
      access_token: access_token,
      on_token_refreshed: on_token_refreshed
    )
  elsif oauth_bearer
    @connection_builder = ConnectionBuilder.new(oauth_bearer)
  else
    raise ArgumentError, "Either oauth_bearer or access_token should be set"
  end
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:

Metadata::Member

Specifications:

adds 1 member to a file

# File 'spec/endpoints/sharing/add_file_member_spec.rb', line 34

file = '/bsd.pdf'
members = @client.add_file_member(file, 'a@test.com')

expect(members)
  .to be_a(DropboxApi::Results::AddFileMemberResultList)
expect(members.first)
  .to be_a(DropboxApi::Metadata::AddFileMemberResult)
expect(members.first.result)
  .to eq(:viewer)

adds 2 members to a file

# File 'spec/endpoints/sharing/add_file_member_spec.rb', line 34

file = '/bsd.pdf'
members = @client.add_file_member(file, %w(a@test.com b@test.com))

expect(members)
  .to be_a(DropboxApi::Results::AddFileMemberResultList)
expect(members.map(&:class).uniq)
  .to eq([DropboxApi::Metadata::AddFileMemberResult])
expect(members.map(&:result).uniq)
  .to eq([:viewer])

adds a member with comment

# File 'spec/endpoints/sharing/add_file_member_spec.rb', line 34

file = '/bsd.pdf'
members = @client.add_file_member file,
                                  'a@test.com',
                                  custom_message: 'See my file down here.'

expect(members)
  .to be_a(DropboxApi::Results::AddFileMemberResultList)

adds a member with access level

# File 'spec/endpoints/sharing/add_file_member_spec.rb', line 34

file = '/bsd.pdf'

# Using :viewer_no_comment as access level will fail with no_permission.
expect {
  @client.add_file_member file,
                          'a@test.com',
                          access_level: :viewer_no_comment
}.to raise_error(DropboxApi::Errors::NoPermissionError)

# 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", "somebody@test.com"

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:

Metadata::AddMember

Specifications:

shares the folder

7 8	# File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 39 folder_id = '1236358158' folder = @client.add_folder_member folder_id, 'somebody@test.com'

shares the folder, if the folder id is a number



14
15

# File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 39

folder_id = 1236358158
folder = @client.add_folder_member folder_id, 'somebody@test.com'

shares the folder, if the param is an AddMember object



21
22

# File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 39

folder_id = 1236358158
folder = @client.add_folder_member folder_id, 'somebody@test.com'

shares the folder, if the member param is an email string



28
29

# File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 39

folder_id = 1236358158
folder = @client.add_folder_member folder_id, 'somebody@test.com'

fails with an invalid folder id

# File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 39

folder_id = 'xxx'
expect {
  folder = @client.add_folder_member folder_id, 'somebody@test.com'

}.to raise_error(DropboxApi::Errors::InvalidIdError)

# 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.

Specifications:

returns the copied file on success

# File 'spec/endpoints/files/copy_spec.rb', line 15

file = @client.copy('/a.jpg', '/b.jpg')

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('b.jpg')

raises an error if the file can't be found



14
15
16

# File 'spec/endpoints/files/copy_spec.rb', line 15

expect {
  @client.copy('/z.jpg', '/b.jpg')
}.to raise_error(DropboxApi::Errors::NotFoundError)

raises an error if the path is invalid



20
21
22

# File 'spec/endpoints/files/copy_spec.rb', line 15

expect {
  @client.copy('/../invalid_path.jpg', '/b.jpg')
}.to raise_error(DropboxApi::Errors::MalformedPathError)

# 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.

Specifications:

returns an async job id

# File 'spec/endpoints/files/copy_batch_spec.rb', line 25

job_id = @client.copy_batch [{
  from_path: "#{path_prefix}/regular_file.txt",
  to_path: "#{path_prefix}/regular_file_renamed.txt"
}]

expect(job_id)
  .to eq('dbjid:AAA6b4uwc19nEau5k-OBI_h-hjrR7pNDaUA3_0hOwV-UZ2pkw_zXWp3FSuVZrQ0d9IXKGkwB5JdYI4mJZumLc6qZ')

if autorename option is true, returns an async job id

# File 'spec/endpoints/files/copy_batch_spec.rb', line 25

job_id = @client.copy_batch([{
  from_path: "#{path_prefix}/regular_file_2.txt",
  to_path: "#{path_prefix}/regular_file_2_renamed.txt"
}], autorename: true)

expect(job_id)
  .to eq('dbjid:AABe-bOUUq5nrybciMJxIxaGAD16nGCKByGyY3Z_2m6kshGW903XTikVT3_5V6JQQu20p3QxoCfws7_hT40deF6q')

# 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.

Specifications:

returns all types of entries

# File 'spec/endpoints/files/copy_batch_check_spec.rb', line 17

result = @client.copy_batch_check 'dbjid:AADOVgzSRvtiBJ9dZaE8VUp07JT-zO7k9TrjEfwnzTfGGDuEi1pTRB2vFufnQfX9Yf-N_tzVl52rGEK4GYI8zzsU'

expect(result).to include(a_kind_of(DropboxApi::Metadata::Folder))
expect(result).to include(a_kind_of(DropboxApi::Metadata::File))
expect(result).to include(a_kind_of(DropboxApi::Errors::NotFoundError))

returns 'invalid_async_job_id' error



15
16
17

# File 'spec/endpoints/files/copy_batch_check_spec.rb', line 17

expect {
  @client.copy_batch_check 'dbjid:AADOVgzSRvtiBJ9dZaE8VUp07JT-zO7k9TrjEfwnzTfGGDuEi1pTRB2vFufnQfX9Yf-N_tzVl52rGEK4GYI8zzsE'
}.to raise_error(DropboxApi::Errors::InvalidIdError)



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:

(DropboxApi::Results::GetCopyReferenceResult)

Specifications:

returns a copy reference

# File 'spec/endpoints/files/copy_reference_get_spec.rb', line 16

result = @client.copy_reference_get '/file.txt'

expect(result).to be_a(DropboxApi::Results::GetCopyReferenceResult)
expect(result.resource.name).to eq('file.txt')
expect(result.copy_reference).to be_a(String)
expect(result.expires).to be_a(Time)

returns a copy reference

# File 'spec/endpoints/files/copy_reference_get_spec.rb', line 16

result = @client.copy_reference_get('/folder')

expect(result).to be_a(DropboxApi::Results::GetCopyReferenceResult)
expect(result.resource.name).to eq('folder')
expect(result.copy_reference).to be_a(String)
expect(result.expires).to be_a(Time)

raises an error



30
31
32

# File 'spec/endpoints/files/copy_reference_get_spec.rb', line 16

expect {
  @client.copy_reference_get('/c.jpg')
}.to raise_error(DropboxApi::Errors::NotFoundError)

# 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:

(DropboxApi::Results::SaveCopyReferenceResult)

Specifications:

returns the saved file

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

result = @client.copy_reference_save @copy_reference, '/copied-file.txt'

expect(result).to be_a(DropboxApi::Results::SaveCopyReferenceResult)
expect(result.resource.name).to eq('copied-file.txt')

returns the saved folder

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

copy_reference = 'WI-v42h5NWxnbDZ2enpjbw'
result = @client.copy_reference_save copy_reference, '/copied-folder'

expect(result).to be_a(DropboxApi::Results::SaveCopyReferenceResult)
expect(result.resource.name).to eq('copied-folder')

raises an error



30
31
32

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

expect {
  @client.copy_reference_save @copy_reference, '/copied-file.txt'
}.to raise_error(DropboxApi::Errors::FileConflictError)

raises an error



38
39
40

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

expect {
  @client.copy_reference_save 'invalid-reference', '/copied-file.txt'
}.to raise_error(DropboxApi::Errors::InvalidCopyReferenceError)

raises an error



46
47
48

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

expect {
  @client.copy_reference_save @copy_reference, '//copied-file.txt'
}.to raise_error(DropboxApi::Errors::MalformedPathError)

raises an error



54
55
56

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

expect {
  @client.copy_reference_save @copy_reference, '/copied-file.txt'
}.to raise_error(DropboxApi::Errors::NoPermissionError)

raises an error



62
63
64

# File 'spec/endpoints/files/copy_reference_save_spec.rb', line 16

expect {
  @client.copy_reference_save @copy_reference, '/copied-file.txt'
}.to raise_error(DropboxApi::Errors::NotFoundError)

# 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.

Specifications:

returns the new file request on success

# File 'spec/endpoints/file_requests/create_file_request_spec.rb', line 15

file_request = @client.create_file_request 'Arizona, baby', "#{path_prefix}/arizona_baby"

expect(file_request).to be_a(DropboxApi::Metadata::FileRequest)
expect(file_request.title).to eq('Arizona, baby')

raises something if wrong path



15
16
17

# File 'spec/endpoints/file_requests/create_file_request_spec.rb', line 15

expect {
  @client.create_file_request 'Arizona, baby', "#{path_prefix}/regular_file.txt"
}.to raise_error(DropboxApi::Errors::CreateFileRequestError)

# 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:

(DropboxApi::Metadata::Folder) —
The new folder.

Specifications:

returns the new folder on success

# File 'spec/endpoints/files/create_folder_spec.rb', line 13

folder = @client.create_folder('/arizona_baby')

expect(folder).to be_a(DropboxApi::Metadata::Folder)
expect(folder.name).to eq('arizona_baby')

raises an error if the name is invalid



14
15
16

# File 'spec/endpoints/files/create_folder_spec.rb', line 13

expect {
  @client.create_folder('/arizona\\baby')
}.to raise_error(DropboxApi::Errors::MalformedPathError)

raises an error if the resource causes a conflict



20
21
22

# File 'spec/endpoints/files/create_folder_spec.rb', line 13

expect {
  @client.create_folder('/b.jpg')
}.to raise_error(DropboxApi::Errors::FileConflictError)

# 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.

Specifications:

returns the created folders synchronously

# File 'spec/endpoints/files/create_folder_batch_spec.rb', line 28

result = @client.create_folder_batch ['/Create Batch', '/Create Batch 1']

expect(result.first).to be_a(DropboxApi::Metadata::Folder)
expect(result.last).to be_a(DropboxApi::Metadata::Folder)

returns async_job_id when large entries are passed

# File 'spec/endpoints/files/create_folder_batch_spec.rb', line 28

paths = []
100.times { |i| paths << "/Folder #{i}"}

async_result = @client.create_folder_batch(paths)
expect(async_result).to be_a(Hash)
expect(async_result).to have_key('async_job_id')

returns async_job_id when force_async is true

# File 'spec/endpoints/files/create_folder_batch_spec.rb', line 28

async_result = @client.create_folder_batch(['/Create Batch 2', '/Create Batch 3'], { force_async: true })

expect(async_result).to be_a(Hash)
expect(async_result).to have_key('async_job_id')

when autorename is true, does not return error for repeated entries



30
31
32

# File 'spec/endpoints/files/create_folder_batch_spec.rb', line 28

result = @client.create_folder_batch(['/Create Batch 1', '/Create Batch 1'], { autorename: true })

expect(result).not_to include(a_kind_of(DropboxApi::Errors::FolderConflictError))

raises error, when invalid option is passed



36
37
38

# File 'spec/endpoints/files/create_folder_batch_spec.rb', line 28

expect {
  @client.create_folder_batch(['/Create Batch 4', '/Create Batch 5'], { async: true })
}.to raise_error(ArgumentError)

# 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.

Specifications:

returns mixed results with failure and success status for each entry

# File 'spec/endpoints/files/create_folder_batch_check_spec.rb', line 16

async_result = @client.create_folder_batch_check('dbjid:AAA8ixe2PLtuFEtS216inFdIa5J8PM5f8c9IcRimbLVqQ-0-bzq0yFEv1yu4UeCSUyZqQn80SjL5cbY-Ow9RBNQE')

expect(async_result).to include(a_kind_of(DropboxApi::Metadata::Folder))
expect(async_result).to include(a_kind_of(DropboxApi::Errors::MalformedPathError))
expect(async_result).to include(a_kind_of(DropboxApi::Errors::FolderConflictError))

raises an error with an invalid async job id



15
16
17

# File 'spec/endpoints/files/create_folder_batch_check_spec.rb', line 16

expect {
  @client.create_folder_batch_check('dbjid:AAA8ixe2PLtuFEtS216inFdIa5J8PM5f8c9IcRimbLVqQ-0-bzq0yFEv1yu4UeCSUyZqQn80SjL5cbY-Ow9RBNQT')
}.to raise_error(DropboxApi::Errors::InvalidIdError)

# 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_shared_link_with_settings(path, settings = {}) ⇒ `DropboxApi::Metadata::SharedLinkMetadata`

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:

(DropboxApi::Metadata::SharedLinkMetadata)

Specifications:

creates a shared link for basic and pro users



8
9
10

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

link = @client.create_shared_link_with_settings '/file_for_sharing.docx'

expect(link).to be_a(DropboxApi::Metadata::FileLinkMetadata)

creates a shared link with settings for pro users



14
15
16

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

link = @client.create_shared_link_with_settings('/file_for_sharing.docx', { expires: '2019-03-12T10:34:42Z' })

expect(link).to be_a(DropboxApi::Metadata::FileLinkMetadata)

raises an error if settings options are passed for basic users



20
21
22

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

expect {
  @client.create_shared_link_with_settings('/file_for_sharing.docx', { expires: '2019-03-12T10:34:42Z' })
}.to raise_error(DropboxApi::Errors::NoPermissionError)

raises an error if already shared for basic and pro users



26
27
28

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

expect {
  @client.create_shared_link_with_settings '/file_for_sharing.docx'
}.to raise_error(DropboxApi::Errors::SharedLinkAlreadyExistsError)

creates a shared link for basic and pro users



34
35
36

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

link = @client.create_shared_link_with_settings '/folder_for_sharing'

expect(link).to be_a(DropboxApi::Metadata::FolderLinkMetadata)

creates a shared link with settings for pro users



40
41
42

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

link = @client.create_shared_link_with_settings('/folder_for_sharing', { expires: '2019-03-12T10:34:42Z' })

expect(link).to be_a(DropboxApi::Metadata::FolderLinkMetadata)

raises an error if settings options are passed for basic user



46
47
48

# File 'spec/endpoints/sharing/create_shared_link_with_settings_spec.rb', line 32

expect {
  @client.create_shared_link_with_settings('/folder_for_sharing', { expires: '2019-03-12T10:34:42Z' })
}.to raise_error(DropboxApi::Errors::NoPermissionError)

# 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.

Specifications:

returns the deleted file

# File 'spec/endpoints/files/delete_spec.rb', line 25

file = @client.delete "#{path_prefix}/will_be_deleted.txt"

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('will_be_deleted.txt')

won't delete the file if `parent_rev` doesn't match



15
16
17

# File 'spec/endpoints/files/delete_spec.rb', line 25

expect {
  @client.delete "#{path_prefix}/wont_be_deleted.txt", parent_rev: '1c0576c68d6'
}.to raise_error(DropboxApi::Errors::FileConflictError)

returns the deleted folder

# File 'spec/endpoints/files/delete_spec.rb', line 25

folder = @client.delete "#{path_prefix}/folder"

expect(folder).to be_a(DropboxApi::Metadata::Folder)
expect(folder.name).to eq('folder')

raises an error if the name is invalid



28
29
30

# File 'spec/endpoints/files/delete_spec.rb', line 25

expect {
  @client.delete '/unexisting folder'
}.to raise_error(DropboxApi::Errors::NotFoundError)

# 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.

Specifications:

returns async_job_id for multiple entries

# File 'spec/endpoints/files/delete_batch_spec.rb', line 17

entries = [{ path: '/folder_to_delete_1' }, { path: '/folder_to_delete_2' }]
async_result = @client.delete_batch entries

expect(async_result).to be_a(Hash)
expect(async_result).to have_key('async_job_id')

returns async_job_id for single entry too

# File 'spec/endpoints/files/delete_batch_spec.rb', line 17

entries = [{ path: '/folder_to_delete/file_to_delete.docx', parent_rev: '1c0576c68d6' }]
async_result = @client.delete_batch entries

expect(async_result).to be_a(Hash)
expect(async_result).to have_key('async_job_id')

# 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.

Specifications:

returns mixed results when complete

# File 'spec/endpoints/files/delete_batch_check_spec.rb', line 15

async_result = @client.delete_batch_check('dbjid:AAC2JUPMEtK-kEg7QVrNEemnX-FfQkJ_0r_tJJ2UpHhwvrUGrpw19CH4U5cfZKWPLxLVJoKgffTOy_zSKk6W953h')

expect(async_result).to include(a_kind_of(DropboxApi::Metadata::Folder))
expect(async_result).to include(a_kind_of(DropboxApi::Metadata::File))
expect(async_result).to include(a_kind_of(DropboxApi::Errors::FileConflictError))
expect(async_result).to include(a_kind_of(DropboxApi::Errors::NotFoundError))

raises an error with an invalid async job id



16
17
18

# File 'spec/endpoints/files/delete_batch_check_spec.rb', line 15

expect {
  @client.delete_batch_check('dbjid:AAA8ixe2PLtuFEtS216inFdIa5J8PM5f8c9IcRimbLVqQ-0-bzq0yFEv1yu4UeCSUyZqQn80SjL5cbY-Ow9RBNQT')
}.to raise_error(DropboxApi::Errors::InvalidIdError)

# 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.

Specifications:

returns the file

# File 'spec/endpoints/files/download_spec.rb', line 12

file = @client.download '/file.txt'

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

yields the file contents

# File 'spec/endpoints/files/download_spec.rb', line 12

file_contents = ''
file = @client.download '/file.txt' do |chunk|
  file_contents = "#{file_contents}#{chunk}"
end

expect(file_contents).to eq("Hola Leo!\n")

raises an error if the name is invalid



23
24
25

# File 'spec/endpoints/files/download_spec.rb', line 12

expect {
  @client.download('/c.jpg')
}.to raise_error(DropboxApi::Errors::NotFoundError)



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.

Specifications:

returns the account information



7
8
9

# File 'spec/endpoints/users/get_account_spec.rb', line 13

account = @client.get_account 'dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs'

expect(account).to be_a(DropboxApi::Metadata::BasicAccount)

raises an error if the account can't be found



13
14
15

# File 'spec/endpoints/users/get_account_spec.rb', line 13

expect {
  @client.get_account 'dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtXXX'
}.to raise_error(DropboxApi::Errors::NoAccountError)



13
14
15

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

add_endpoint :get_account do |account_id|
  perform_request account_id: 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.

Specifications:

returns account information of all given IDs

# File 'spec/endpoints/users/get_account_batch_spec.rb', line 15

test_accounts = {
  'dbid:AACiYqkuK0t_wIvlr9BduHKdhzk_H28Dg0U' => 'Antonio Hidalgo',
  'dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs' => 'Jesus Burgos'
}
accounts = @client.get_account_batch test_accounts.keys

accounts.each do |account|
  expect(account).to be_a(DropboxApi::Metadata::BasicAccount)
  expect(account.name.display_name)
    .to eq(test_accounts[account.account_id])
end

raises an error if one account cannot be found

# File 'spec/endpoints/users/get_account_batch_spec.rb', line 15

account_ids = %w(
  dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtXXX
  dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs
)

expect {
  @client.get_account_batch account_ids
}.to raise_error(DropboxApi::Errors::NoAccountError)



15
16
17

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

add_endpoint :get_account_batch do |account_ids|
  perform_request account_ids: account_ids
end

#get_current_account ⇒ `BasicAccount`

Get information about the current user's account.

Returns:

(BasicAccount) —
Detailed information about the current user's account.

Specifications:

returns the account usage information



7
8
9

# File 'spec/endpoints/users/get_space_usage_spec.rb', line 12

space_usage = @client.get_space_usage

expect(space_usage).to be_a(DropboxApi::Metadata::SpaceUsage)

returns the current account information

# File 'spec/endpoints/users/get_current_account_spec.rb', line 12

account = @client.get_current_account

expect(account).to be_a(DropboxApi::Metadata::BasicAccount)
expect(account.root_info).to be_a(DropboxApi::Metadata::UserRootInfo)



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.

Specifications:

may return a `File`

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

file = @client.get_metadata("#{path_prefix}/file.txt")

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

will parse time specific fields



15
16
17

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

file = @client.get_metadata("#{path_prefix}/file.txt")

expect(file.client_modified).to eq(Time.new(1988, 12, 8, 1, 1, 0, '+00:00'))

may return a `Folder`

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

folder = @client.get_metadata("#{path_prefix}/folder")

expect(folder).to be_a(DropboxApi::Metadata::Folder)
expect(folder.name).to eq('folder')

raises an error if the path is wrong



28
29
30

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

expect {
  @client.get_metadata("#{path_prefix}/unexisting_folder")
}.to raise_error(DropboxApi::Errors::NotFoundError)

raises an error if an invalid option is given



34
35
36

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

expect {
  @client.get_metadata("#{path_prefix}/file.txt", invalid_option: true)
}.to raise_error ArgumentError

raises an error



41
42
43

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

expect {
  @client.get_metadata("#{path_prefix}/deleted_file.txt")
}.to raise_error(DropboxApi::Errors::NotFoundError)

with `:include_deleted`, returns a `File`

# File 'spec/endpoints/files/get_metadata_spec.rb', line 30

file = @client.get_metadata("#{path_prefix}/deleted_file.txt", include_deleted: true)

expect(file).to be_a(DropboxApi::Metadata::Deleted)
expect(file.name).to eq('deleted_file.txt')

# 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.

Specifications:

returns the file

# File 'spec/endpoints/files/get_preview_spec.rb', line 14

file = @client.get_preview('/file.docx')

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.docx')

raises an error if the name is invalid



14
15
16

# File 'spec/endpoints/files/get_preview_spec.rb', line 14

expect {
  @client.get_preview('/unknown_file.jpg')
}.to raise_error(DropboxApi::Errors::NotFoundError)



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_shared_link_metadata(preview_link, options = {}) ⇒ `SharedFileMembers`

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)

Specifications:

works with a file

# File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 23

shared_link = @client
  .list_shared_links(path: "#{path_prefix}/shared_file.txt")
  .links
  .first
result = @client.get_shared_link_metadata shared_link.url

expect(result).to be_a(DropboxApi::Metadata::FileLinkMetadata)

works with a folder

# File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 23

shared_link = @client
  .list_shared_links(path: "#{path_prefix}/shared_folder")
  .links
  .first
result = @client.get_shared_link_metadata shared_link.url

expect(result).to be_a(DropboxApi::Metadata::FolderLinkMetadata)

raises an error if the link can't be found

# File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 23

bad_link = 'https://www.dropbox.com/sh/abcd/1234?dl=0'

expect {
  @client.get_shared_link_metadata bad_link
}.to raise_error(DropboxApi::Errors::SharedLinkNotFoundError)

# 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_usage ⇒ `SpaceUsage`

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_temporary_link(path) ⇒ `Object`

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.

Specifications:

returns a GetTemporaryLinkResult with file and link

# File 'spec/endpoints/files/get_temporary_link_spec.rb', line 14

result = @client.get_temporary_link '/img.png'

expect(result).to be_a(DropboxApi::Results::GetTemporaryLinkResult)
expect(result.file.name).to eq('img.png')

raises an error if the file can't be found



14
15
16

# File 'spec/endpoints/files/get_temporary_link_spec.rb', line 14

expect {
  @client.get_preview '/unknown_file.jpg'
}.to raise_error(DropboxApi::Errors::NotFoundError)



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.

Specifications:

returns a file

# File 'spec/endpoints/files/get_thumbnail_spec.rb', line 48

file = @client.get_thumbnail '/img.png'

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('img.png')

raises an error if the file can't be found



14
15
16

# File 'spec/endpoints/files/get_thumbnail_spec.rb', line 48

expect {
  @client.get_thumbnail '/unknown_file.jpg'
}.to raise_error(DropboxApi::Errors::NotFoundError)

raises an argument error with invalid options



20
21
22

# File 'spec/endpoints/files/get_thumbnail_spec.rb', line 48

expect {
  @client.get_thumbnail '/img.png', invalid_arg: 'value'
}.to raise_error(ArgumentError)

# 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.

Specifications:

returns files

# File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 23

result = @client.get_thumbnail_batch ["#{path_prefix}/img.png"]
entry = result.entries.first

expect(entry.metadata).to be_a(DropboxApi::Metadata::File)
expect(entry.thumbnail).to be_a(String)
expect(entry.metadata.name).to eq('img.png')

includes an error entry if the file can't be found



18
19

# File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 23

result = @client.get_thumbnail_batch ["#{path_prefix}/unknown_file.jpg"]
expect(result.entries.first).to be_a(DropboxApi::Errors::NotFoundError)

raises an argument error with invalid options



23
24
25

# File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 23

expect {
  @client.get_thumbnail_batch ["#{path_prefix}/img.png"], invalid_arg: 'value'
}.to raise_error(ArgumentError)

# 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:

Metadata::MemberActionList

Specifications:

lists file members



7
8
9

# File 'spec/endpoints/sharing/list_file_members_spec.rb', line 37

result = @client.list_file_members '1231273663'

expect(result).to be_a(DropboxApi::Results::SharedFileMembers)

lists file members including member actions



13
14
15

# File 'spec/endpoints/sharing/list_file_members_spec.rb', line 37

result = @client.list_file_members '1231273663', [:remove, :make_owner]

expect(result).to be_a(DropboxApi::Results::SharedFileMembers)

# 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)

Specifications:

returns a ListFolderResult



8
9
10

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

result = @client.list_folder ''

expect(result).to be_a(DropboxApi::Results::ListFolderResult)

raises an error if the file can't be found



14
15
16

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

expect {
  @client.list_folder '/unexisting_folder'
}.to raise_error(DropboxApi::Errors::NotFoundError)

returns all entries as metadata objects

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

result = @client.list_folder ''

result.entries.each do |resource|
  expect(resource).to be_a(DropboxApi::Metadata::Base)
end

lists entries in shared folder if given

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

result = @client.list_shared_links(path: "#{path_prefix}/shared_folder")
result = @client.list_folder '', shared_link: result.links.first.url

result.entries.each do |resource|
  expect(resource).to be_a(DropboxApi::Metadata::Base)
end
expect(result.entries.map(&:name).inspect).to include('cow.txt')

raises an argument error with invalid options



38
39
40

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

expect {
  @client.list_folder '/img.png', invalid_arg: 'value'
}.to raise_error(ArgumentError)

works with a namespace_id



45
46

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

@client.namespace_id = 70721710
@client.list_folder '/dropbox_api_fixtures'

fails with an invalid namespace ID

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

@client.namespace_id = 938429923

expect do
  @client.list_folder '/dropbox_api_fixtures'
end.to raise_error(DropboxApi::Errors::HttpError)

works if namespace ID is unset

# File 'spec/endpoints/files/list_folder_spec.rb', line 29

@client.namespace_id = 70721710

# we expect this to use a namespace ID
@client.list_folder '/dropbox_api_fixtures'

@client.namespace_id = nil
# we expect the next not to use any namespace ID
@client.list_folder '/dropbox_api_fixtures'

# 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.

Specifications:

returns a ListFolderResult



15
16
17

# File 'spec/endpoints/files/list_folder_continue_spec.rb', line 17

result = @client.list_folder_continue(@cursor)

expect(result).to be_a(DropboxApi::Results::ListFolderResult)



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.

Specifications:

returns a ListFolderGetLatestCursorResult

# File 'spec/endpoints/files/list_folder_get_latest_cursor_spec.rb', line 28

result = @client.list_folder_get_latest_cursor path: '/folder'

expect(result)
  .to be_a(DropboxApi::Results::ListFolderGetLatestCursorResult)

# 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.

Specifications:

returns a ListFolderLongpollResult



13
14
15

# File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 25

result = @client.list_folder_longpoll @cursor

expect(result).to be_a(DropboxApi::Results::ListFolderLongpollResult)

indicates if there're changes



19
20
21

# File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 25

result = @client.list_folder_longpoll @cursor

expect(result.changes).to be_truthy

raises an error with an invalid cursor



25
26
27

# File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 25

expect {
  @client.list_folder_longpoll 'I believe in the blerch'
}.to raise_error DropboxApi::Errors::HttpError

# 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:

Metadata::MemberActionList

Specifications:

lists folder members



7
8
9

# File 'spec/endpoints/sharing/list_folder_members_spec.rb', line 30

result = @client.list_folder_members '1231273663'

expect(result).to be_a(DropboxApi::Results::SharedFolderMembers)

lists folder members including member actions



13
14
15

# File 'spec/endpoints/sharing/list_folder_members_spec.rb', line 30

result = @client.list_folder_members '1231273663', [:remove, :make_owner]

expect(result).to be_a(DropboxApi::Results::SharedFolderMembers)

# 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.

Specifications:

returns a ListRevisionsResult



7
8
9

# File 'spec/endpoints/files/list_revisions_spec.rb', line 16

result = @client.list_revisions '/file.txt'

expect(result).to be_a(DropboxApi::Results::ListRevisionsResult)

raises an error if the file can't be found



13
14
15

# File 'spec/endpoints/files/list_revisions_spec.rb', line 16

expect {
  @client.list_revisions '/unexisting_file'
}.to raise_error(DropboxApi::Errors::NotFoundError)

returns all revisions as metadata objects

# File 'spec/endpoints/files/list_revisions_spec.rb', line 16

result = @client.list_revisions '/file.txt'

result.entries.each do |resource|
  expect(resource).to be_a(DropboxApi::Metadata::Base)
end

indicates if the file has been deleted



27
28
29

# File 'spec/endpoints/files/list_revisions_spec.rb', line 16

result = @client.list_revisions '/file.txt'

expect(result.is_deleted?).to be_truthy

# 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(options = {}) ⇒ `ListSharedLinksResult`

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)

Specifications:

returns a file link



8
9
10

# File 'spec/endpoints/sharing/list_shared_links_spec.rb', line 25

result = @client.list_shared_links path: '/some_folder/file.txt'

expect(result.links.last).to be_a(DropboxApi::Metadata::FileLinkMetadata)

lists all shared links

# File 'spec/endpoints/sharing/list_shared_links_spec.rb', line 25

links = @client.list_shared_links(path: '/some_folder/file.txt').links

expect(links.map &:url).to match_array(%w(
  https://www.dropbox.com/sh/5b0bmldpa1qi772/AAAwKkKiTdb1A78bzHCKQLeHa?dl=0
  https://www.dropbox.com/s/sp5cuhaxfn8126z/file.txt?dl=0
))

gets the direct shared link

# File 'spec/endpoints/sharing/list_shared_links_spec.rb', line 25

links = @client.list_shared_links({
  path: '/some_folder/file.txt',
  direct_only: true
}).links

expect(links.map &:url).to match_array(%w(
  https://www.dropbox.com/s/sp5cuhaxfn8126z/file.txt?dl=0
))

returns a folder link



36
37
38

# File 'spec/endpoints/sharing/list_shared_links_spec.rb', line 25

result = @client.list_shared_links path: '/some_folder/another_folder'

expect(result.links.last).to be_a(DropboxApi::Metadata::FolderLinkMetadata)

lists all shared links

# File 'spec/endpoints/sharing/list_shared_links_spec.rb', line 25

links = @client.list_shared_links(path: '/some_folder/another_folder').links

expect(links.map &:url).to match_array(%w(
  https://www.dropbox.com/sh/5b0bmldpa1qi772/AAAwKkKiTdb1A78bzHCKQLeHa?dl=0
  https://www.dropbox.com/sh/h3slcnfcs3w7sdk/AADlUYcssd70EWHX3n9CJCWwa?dl=0
))

# 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

#middleware ⇒ `Object`



21
22
23

# File 'lib/dropbox_api/client.rb', line 21

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.

Specifications:

returns the moved file on success

# File 'spec/endpoints/files/move_spec.rb', line 20

file = @client.move('/img.png', '/image.png')

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('image.png')

returns the moved folder on success

# File 'spec/endpoints/files/move_spec.rb', line 20

file = @client.move('/folder', '/test/folder')

expect(file).to be_a(DropboxApi::Metadata::Folder)
expect(file.name).to eq('folder')

renames the moved file if required

# File 'spec/endpoints/files/move_spec.rb', line 20

file = @client.move('/a.jpg', '/photo.jpg', autorename: true)

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('photo (1).jpg')

raises an error if the file can't be found



28
29
30

# File 'spec/endpoints/files/move_spec.rb', line 20

expect {
  @client.move('/z.jpg', '/b.jpg')
}.to raise_error(DropboxApi::Errors::NotFoundError)

# 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

#namespace_id ⇒ `Object`



29
30
31

# File 'lib/dropbox_api/client.rb', line 29

def namespace_id
  @connection_builder.namespace_id
end

#namespace_id=(value) ⇒ `Object`



25
26
27

# File 'lib/dropbox_api/client.rb', line 25

def namespace_id=(value)
  @connection_builder.namespace_id = value
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.

Specifications:

can't be tested without a Dropbox Business account :(



8
9
10

# File 'spec/endpoints/files/permanently_delete_spec.rb', line 21

expect {
  @client.permanently_delete "#{path_prefix}/file.txt"
}.to raise_error(DropboxApi::Errors::HttpError)

# 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.

Specifications:

returns the restored file on success



7
8
9

# File 'spec/endpoints/files/restore_spec.rb', line 13

file = @client.restore('/file.txt', '1a6a24061bdd')

expect(file).to be_a(DropboxApi::Metadata::File)

raises an error with an invalid revision



14
15
16

# File 'spec/endpoints/files/restore_spec.rb', line 13

expect {
  file = @client.restore('/file.txt', '1a6a24061000')
}.to raise_error(DropboxApi::Errors::InvalidRevisionError)

# File 'lib/dropbox_api/endpoints/files/restore.rb', line 13

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

#revoke_shared_link(url) ⇒ `Object`

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.

Specifications:

revoke a shared link

8	# File 'spec/endpoints/sharing/revoke_shared_link_spec.rb', line 18 link = @client.revoke_shared_link 'https://www.dropbox.com/sh/t0ebpiojwy4l1bn/AAAcU6qf20b8R-SG5_PJCBOQa?dl=0'

raises an error if link is not found



14
15
16

# File 'spec/endpoints/sharing/revoke_shared_link_spec.rb', line 18

expect {
  @client.revoke_shared_link 'https://www.dropbox.com/sh/t0ebpiojwy4l1bn/AAAcU6qf20b8R-SG5_PJCBOQa?dl=0'
}.to raise_error(DropboxApi::Errors::SharedLinkNotFoundError)

raises access denied error if not permitted



20
21
22

# File 'spec/endpoints/sharing/revoke_shared_link_spec.rb', line 18

expect {
  @client.revoke_shared_link 'https://www.dropbox.com/s/al0w4e11j0e1kp3/file_for_sharing.docx?dl=0'
}.to raise_error(DropboxApi::Errors::SharedLinkAccessDeniedError)

raises shared link malformed error if link is malformed



26
27
28

# File 'spec/endpoints/sharing/revoke_shared_link_spec.rb', line 18

expect {
  @client.revoke_shared_link 'https://www.dropbox.com/al0w4e11j0e1kp3/file_for_sharing.docx?dl=0'
}.to raise_error(DropboxApi::Errors::SharedLinkMalformedError)

# 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.

Specifications:

returns the saved file on success



7
8
9

# File 'spec/endpoints/files/save_url_spec.rb', line 16

result = @client.save_url('/photo_1.jpg', 'https://www.dropbox.com/s/834xngq25alcwsi/IMG_8998.JPG?dl=0')

expect(result.async_job_id).to eq('VofXAX8DO1sAAAAAAAAD_Q')

returns the saved file on success



13
14
15

# File 'spec/endpoints/files/save_url_spec.rb', line 16

result = @client.save_url('/photo_2.jpg', 'https://static1.squarespace.com/static/518aa4bee4b050d373a7e8a2/t/558add71e4b062927077adc6/1435164035794/photo-1427348693976-99e4aca06bb9.jpg')

expect(result.async_job_id).to eq('VofXAX8DO1sAAAAAAAAD_w')

raises an error with an invalid URL



19
20
21

# File 'spec/endpoints/files/save_url_spec.rb', line 16

expect {
  file = @client.save_url('/photo_3.jpg', '1a6a24061000')
}.to raise_error(DropboxApi::Errors::InvalidUrlError)

# 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.

Specifications:

returns the saved file if job completed



7
8
9

# File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 14

result = @client.save_url_check_job_status 'VofXAX8DO1sAAAAAAAAD_Q'

expect(result).to be_a(DropboxApi::Metadata::File)

returns :in_progress if job not completed

# File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 14

save_url_result = @client.save_url('/file.zip', 'http://ipv4.download.thinkbroadband.com/1GB.zip')
status = @client.save_url_check_job_status save_url_result.async_job_id

expect(status).to eq(:in_progress)

returns a descriptive error if the job failed

# File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 14

save_url_result = @client.save_url('/missing_file.zip', 'http://ipv4.download.thinkbroadband.com/not_found.zip')
# sleep 30 # We may need to wait until job completes to get its failure
status = @client.save_url_check_job_status save_url_result.async_job_id

expect(status).to be_a(DropboxApi::Errors::DownloadFailedError)

# 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.

Specifications:

returns a list of matching results

# File 'spec/endpoints/files/search_spec.rb', line 22

result = @client.search('findable_file')

expect(result).to be_a(DropboxApi::Results::SearchV2Result)
match = result.matches.first
expect(match.resource.name).to eq('findable_file.txt')
expect(match.match_type).to eq(:filename)

raises an error if the file can't be found

# File 'spec/endpoints/files/search_spec.rb', line 22

options = DropboxApi::Metadata::SearchOptions.new(
  { 'path' => '/bad_folder' }
)

result = @client.search('/image.png', options)
expect(result.matches).to be_empty

# 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

#search_continue(cursor) ⇒ `Object`

search:2. Used to fetch the next page of results.

Parameters:

cursor (String) —
The cursor returned by your last call to

Specifications:

returns a SearchResult



15
16
17

# File 'spec/endpoints/files/search_continue_spec.rb', line 19

result = @client.search_continue(@cursor)

expect(result).to be_a(DropboxApi::Results::SearchV2Result)



19
20
21

# File 'lib/dropbox_api/endpoints/files/search_continue.rb', line 19

add_endpoint :search_continue do |cursor|
  perform_request cursor: cursor
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:

(DropboxApi::Results::ShareFolderLaunch) —
Shared folder metadata.

Specifications:

returns the shared folder



7
8
9

# File 'spec/endpoints/sharing/share_folder_spec.rb', line 37

folder = @client.share_folder('/folder_k')

expect(folder).to be_a(DropboxApi::Metadata::SharedFolder)

returns the shared folder, even if already shared



13
14
15

# File 'spec/endpoints/sharing/share_folder_spec.rb', line 37

folder = @client.share_folder('/already_shared')

expect(folder).to be_a(DropboxApi::Metadata::SharedFolder)

contains a shared folder id

# File 'spec/endpoints/sharing/share_folder_spec.rb', line 37

folder = @client.share_folder('/folder_k')

expect(folder.shared_folder_id.to_s)
  .to eq('1236414195')

# 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_revoke ⇒ `Object`

Revoke the access token for the current account

Specifications:

revokes the token

7	# File 'spec/endpoints/auth/token_revoke_spec.rb', line 11 account = @client.token_revoke



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.

Specifications:

unshares the file

7	# File 'spec/endpoints/sharing/unshare_file_spec.rb', line 14 file = @client.unshare_file('id:xyz123')

returns file access permission error



13
14
15

# File 'spec/endpoints/sharing/unshare_file_spec.rb', line 14

expect {
  @client.unshare_file('id:xyz123')
}.to raise_error(DropboxApi::Errors::NoPermissionError)

returns email unverified error



19
20
21

# File 'spec/endpoints/sharing/unshare_file_spec.rb', line 14

expect {
  @client.unshare_file('id:xyz123')
}.to raise_error(DropboxApi::Errors::EmailUnverifiedError)

# 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:

Metadata::WriteMode

Specifications:

uploads a file

# File 'spec/endpoints/files/upload_spec.rb', line 50

file = @client.upload("#{path_prefix}/file.txt", 'Hello Dropbox!')

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

works with an IO object

# File 'spec/endpoints/files/upload_spec.rb', line 50

content = File.open(File.join(DropboxScaffoldBuilder.fixtures_path, 'file.txt'))
file = @client.upload("#{path_prefix}/file_io.txt", content)

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file_io.txt')
expect(file.content_hash).to eq('709a5cf259366d6ca6b2fa4d3b53c02f5ce2b2764e9d580711e3ffd24d79f5e9')

uploads a file with `add` write mode

# File 'spec/endpoints/files/upload_spec.rb', line 50

file = @client.upload("#{path_prefix}/file.txt", 'Hola Dropbox!', {
  autorename: true,
  mode: :add
})

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file (1).txt')

uploads a file with `overwrite` write mode

# File 'spec/endpoints/files/upload_spec.rb', line 50

file = @client.upload("#{path_prefix}/file.txt", 'Hola Dropbox!', {
  autorename: true,
  mode: :overwrite
})

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

uploads a file with `update` write mode

# File 'spec/endpoints/files/upload_spec.rb', line 50

rev = @client.get_metadata("#{path_prefix}/file.txt").rev
file = @client.upload("#{path_prefix}/file.txt", 'Hallo Dropbox!', {
  autorename: true,
  mode: DropboxApi::Metadata::WriteMode.new(:update, rev)
})

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

uploads a file with `overwrite` write mode

# File 'spec/endpoints/files/upload_spec.rb', line 50

modified_at = Time.utc 2016, 12, 25, 12, 0

file = @client.upload("#{path_prefix}/another_file.txt", 'Our country is a mess!', {
  client_modified: modified_at
})

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('another_file.txt')
expect(file.client_modified).to eq(modified_at)

raises a DropboxApi::Errors::TooManyWriteOperations exception

# File 'spec/endpoints/files/upload_spec.rb', line 50

errors = []

15.times.map do |n|
  Thread.new do
    begin
      @client.upload("#{path_prefix}/file_#{n}.txt", 'Hello Dropbox!')
    rescue DropboxApi::Errors::TooManyWriteOperationsError => e
      errors << e
    end
  end
end.each(&:join)

expect(errors.any?).to be_truthy

raises an exception with info to retry

# File 'spec/endpoints/files/upload_spec.rb', line 50

errors = []

15.times.map do |n|
  Thread.new do
    begin
      @client.upload("#{path_prefix}/file_#{n}.txt", 'Hello Dropbox!')
    rescue DropboxApi::Errors::TooManyWriteOperationsError => e
      errors << e
    end
  end
end.each(&:join)

errors.each do |error|
  expect(error.retry_after).to be_a(Numeric)
end

uploads a file

# File 'spec/endpoints/virtual/upload_by_chunks_spec.rb', line 50

file = @client.upload_by_chunks("#{path_prefix}/file.txt", 'Hello Dropbox!')

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file.txt')

works with an IO object

# File 'spec/endpoints/virtual/upload_by_chunks_spec.rb', line 50

content = File.open(File.join(DropboxScaffoldBuilder.fixtures_path, 'file.txt'))
file = @client.upload_by_chunks("#{path_prefix}/file_io.txt", content)

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file_io.txt')
expect(file.content_hash).to eq('709a5cf259366d6ca6b2fa4d3b53c02f5ce2b2764e9d580711e3ffd24d79f5e9')

uploads a file with `add` write mode

# File 'spec/endpoints/virtual/upload_by_chunks_spec.rb', line 50

file = @client.upload_by_chunks("#{path_prefix}/file.txt", 'Hola Dropbox!', {
  autorename: true,
  mode: :add
})

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('file (1).txt')

# 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:

Metadata::WriteMode

# 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:

cursor (DropboxApi::Metadata::UploadSessionCursor) —
Contains the upload session ID and the offset. This cursor will have its offset updated after a successful call.

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

Specifications:

can be used to append an upload

# File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 39

chunks = ['123456789', 'Olá Dropbox!']

cursor = @client.upload_session_start(chunks.first)

@client.upload_session_append_v2(cursor, chunks.last)

commit = DropboxApi::Metadata::CommitInfo.new(
  'path' => '/target.txt',
  'mode' => :add
)

expect { @client.upload_session_finish(cursor, commit) }.not_to raise_error

will raise error if the cursor can't be found

# File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 39

cursor = DropboxApi::Metadata::UploadSessionCursor.new({
  'session_id' => 'INVALID_CURSOR',
  'offset' => 0
})

expect {
  @client.upload_session_append_v2(cursor, 'Hello Dropbox!')
}.to raise_error(DropboxApi::Errors::NotFoundError)

will raise error if the offset is wrong

# File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 39

chunk = '123456789'

cursor = @client.upload_session_start(chunk)

# Set an incorrect offset deliberately so Dropbox will return an error
cursor.instance_variable_set :@offset, 42

expect {
  @client.upload_session_append_v2(cursor, 'Hello Dropbox!')
}.to raise_error(DropboxApi::Errors::UploadSessionOffsetError)

# 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:

cursor (DropboxApi::Metadata::UploadSessionCursor) —
Contains the upload session ID and the offset.
commit (DropboxApi::Metadata::CommitInfo) —
Contains the path and other optional modifiers for the commit.

Specifications:

will create a file

# File 'spec/endpoints/files/upload_session_finish_spec.rb', line 22

cursor = @client.upload_session_start('Hello Dropbox!')
commit = DropboxApi::Metadata::CommitInfo.new({
  'path' => '/Homework/math/Matrices.txt',
  'mode' => :add
})

file = @client.upload_session_finish(cursor, commit)

expect(file).to be_a(DropboxApi::Metadata::File)
expect(file.name).to eq('Matrices.txt')

# 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:

(DropboxApi::Metadata::UploadSessionCursor) —
The session cursor that you can use to continue the upload afterwards.

Specifications:

returns a session

# File 'spec/endpoints/files/upload_session_start_spec.rb', line 26

cursor = @client.upload_session_start('Hello Dropbox!')

expect(cursor).to be_a(DropboxApi::Metadata::UploadSessionCursor)
expect(cursor.session_id).to eq('AAAAAAAMOCK_SESSION_ID')

# 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

Class: DropboxApi::Client

virtual collapse

sharing collapse

files collapse

users collapse

auth collapse

Instance Method Summary collapse

Constructor Details

#initialize(oauth_bearer = ENV['DROPBOX_OAUTH_BEARER'], access_token: nil, on_token_refreshed: nil) ⇒ Client

Instance Method Details

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

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

#copy(from, to) ⇒ Object

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

#copy_batch_check(async_job_id) ⇒ :in_progress, Array

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

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

#create_file_request(title, destination) ⇒ Object

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

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

#create_folder_batch_check(async_job_id) ⇒ Array

#create_shared_link_with_settings(path, settings = {}) ⇒ DropboxApi::Metadata::SharedLinkMetadata

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

#delete_batch(entries) ⇒ String, Array

#delete_batch_check(async_job_id) ⇒ :in_progress, Array

#download(path, &block) ⇒ Object

#get_account(account_id) ⇒ BasicAccount

#get_account_batch(account_ids) ⇒ Array<BasicAccount>

#get_current_account ⇒ BasicAccount

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

#get_preview(path, &block) ⇒ Object

#get_shared_link_metadata(preview_link, options = {}) ⇒ SharedFileMembers

#get_space_usage ⇒ SpaceUsage

#get_temporary_link(path) ⇒ Object

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

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

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

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

#list_folder_continue(cursor) ⇒ Object

#list_folder_get_latest_cursor(options = {}) ⇒ Object

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

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

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

#list_shared_links(options = {}) ⇒ ListSharedLinksResult

#middleware ⇒ Object

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

#namespace_id ⇒ Object

#namespace_id=(value) ⇒ Object

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

#restore(path, rev) ⇒ Object

#revoke_shared_link(url) ⇒ Object

#save_url(path, url) ⇒ Object

#save_url_check_job_status(job_id) ⇒ Object

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

#search_continue(cursor) ⇒ Object

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

#token_revoke ⇒ Object

#unshare_file(file) ⇒ Object

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

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

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

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

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

#initialize(oauth_bearer = ENV['DROPBOX_OAUTH_BEARER'], access_token: nil, on_token_refreshed: nil) ⇒ `Client`

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

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

#copy(from, to) ⇒ `Object`

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

#copy_batch_check(async_job_id) ⇒ `:in_progress`, `Array`

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

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

#create_file_request(title, destination) ⇒ `Object`

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

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

#create_folder_batch_check(async_job_id) ⇒ `Array`

#create_shared_link_with_settings(path, settings = {}) ⇒ `DropboxApi::Metadata::SharedLinkMetadata`

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

#delete_batch(entries) ⇒ `String`, `Array`

#delete_batch_check(async_job_id) ⇒ `:in_progress`, `Array`

#download(path, &block) ⇒ `Object`

#get_account(account_id) ⇒ `BasicAccount`

#get_account_batch(account_ids) ⇒ `Array<BasicAccount>`

#get_current_account ⇒ `BasicAccount`

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

#get_preview(path, &block) ⇒ `Object`

#get_shared_link_metadata(preview_link, options = {}) ⇒ `SharedFileMembers`

#get_space_usage ⇒ `SpaceUsage`

#get_temporary_link(path) ⇒ `Object`

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

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

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

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

#list_folder_continue(cursor) ⇒ `Object`

#list_folder_get_latest_cursor(options = {}) ⇒ `Object`

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

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

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

#list_shared_links(options = {}) ⇒ `ListSharedLinksResult`

#middleware ⇒ `Object`

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

#namespace_id ⇒ `Object`

#namespace_id=(value) ⇒ `Object`

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

#restore(path, rev) ⇒ `Object`

#revoke_shared_link(url) ⇒ `Object`

#save_url(path, url) ⇒ `Object`

#save_url_check_job_status(job_id) ⇒ `Object`

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

#search_continue(cursor) ⇒ `Object`

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

#token_revoke ⇒ `Object`

#unshare_file(file) ⇒ `Object`

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

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

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

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

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