Class: DropboxApi::Client

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

virtual collapse

sharing collapse

files collapse

users collapse

auth collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Client.



4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 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:

Specifications:

  • adds 1 member to a file
    
    
    7
    8
    9
    10
    11
    12
    13
    14
    15
    # 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
    
    
    19
    20
    21
    22
    23
    24
    25
    26
    27
    # 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
    
    
    31
    32
    33
    34
    35
    36
    37
    # 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
    
    
    41
    42
    43
    44
    45
    46
    47
    48
    # 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)


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

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

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

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

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

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

Apps must have full Dropbox access to use this endpoint.

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

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

Examples:

client = DropboxApi::Client.new
client.add_folder_member "1363389221", "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:

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
    
    
    35
    36
    37
    38
    39
    # 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)


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

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

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

#copy(from, to) ⇒ Object

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

Parameters:

  • from (String)

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

  • to (String)

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

Returns:

  • The moved file.

Specifications:

  • returns the copied file on success
    
    
    7
    8
    9
    10
    # 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)


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

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

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

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

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

Note: No errors are returned by this endpoint.

Parameters:

  • entries (Array<Hash>)

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

Options Hash (options):

  • autorename (Boolean)

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

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.

Specifications:

  • returns an async job id
    
    
    8
    9
    10
    11
    12
    13
    14
    # 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
    
    
    18
    19
    20
    21
    22
    23
    24
    # 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')


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

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

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

#copy_batch_check(async_job_id) ⇒ :in_progress, Array

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

Parameters:

  • async_job_id (String)

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

Returns:

  • (:in_progress, Array)

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

Specifications:

  • returns all types of entries
    
    
    7
    8
    9
    10
    11
    # 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:

Specifications:

  • returns a copy reference
    
    
    8
    9
    10
    11
    12
    13
    # 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
    
    
    19
    20
    21
    22
    23
    24
    # 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)


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

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

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

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

Parameters:

  • copy_reference (String)

    A copy reference returned by #copy_reference_get.

  • path (String)

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

Returns:

Specifications:

  • returns the saved file
    
    
    10
    11
    12
    13
    # 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
    
    
    19
    20
    21
    22
    23
    # 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)


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

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

#create_file_request(title, destination) ⇒ Object

Create a file request for a given path.

Parameters:

  • title (String)

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

  • destination (String)

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

Specifications:

  • returns the new file request on success
    
    
    8
    9
    10
    11
    # 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)


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

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

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

Create a folder at a given path.

Parameters:

  • path (String)

    Path in the user's Dropbox to create.

Returns:

Specifications:

  • returns the new folder on success
    
    
    7
    8
    9
    10
    # 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)


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

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

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

Create multiple folders at once.

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

Note: No errors are returned by this endpoint.

Parameters:

  • paths (Array)

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

Options Hash (options):

  • autorename (Boolean)

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

  • force_async (Boolean)

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

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.

Specifications:

  • returns the created folders synchronously
    
    
    7
    8
    9
    10
    # 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
    
    
    14
    15
    16
    17
    18
    19
    # 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
    
    
    23
    24
    25
    26
    # 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)


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

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

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

#create_folder_batch_check(async_job_id) ⇒ Array

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

Parameters:

  • async_job_id (String)

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

Returns:

  • (Array)

    A list of one result for each entry.

Specifications:

  • returns mixed results with failure and success status for each entry
    
    
    7
    8
    9
    10
    11
    # 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)


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

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

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

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

Parameters:

  • path (String)

    The path to be shared by the shared link.

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

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

Options Hash (settings):

  • requested_visibility (Object)

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

  • link_password (Object)

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

  • expires (Object)

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

Returns:

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)


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

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

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

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

Delete the file or folder at a given path.

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

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

Parameters:

  • path (String)

    Path in the user's Dropbox to delete.

Options Hash (options):

  • parent_rev (String)

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

Specifications:

  • returns the deleted file
    
    
    8
    9
    10
    11
    # 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
    
    
    21
    22
    23
    24
    # 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)


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

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

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

#delete_batch(entries) ⇒ String, Array

Delete multiple files/folders at once.

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

Parameters:

  • entries (Array)

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

Returns:

  • (String, Array)

    Either the job id or the list of job statuses.

Specifications:

  • returns async_job_id for multiple entries
    
    
    9
    10
    11
    12
    13
    # 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
    
    
    17
    18
    19
    20
    21
    # 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')


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

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

#delete_batch_check(async_job_id) ⇒ :in_progress, Array

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

Parameters:

  • async_job_id (String)

    Id of the asynchronous job.

Returns:

  • (:in_progress, Array)

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

Specifications:

  • returns mixed results when complete
    
    
    7
    8
    9
    10
    11
    12
    # 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)


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

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

#download(path, &block) ⇒ Object

Download a file from a user's Dropbox.

Parameters:

  • path (String)

    The path of the file to download.

Specifications:

  • returns the file
    
    
    7
    8
    9
    10
    # 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
    
    
    14
    15
    16
    17
    18
    19
    # 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
    
     = @client. 'dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs'
    
    expect().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. '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 ||
  perform_request account_id: 
end

#get_account_batch(account_ids) ⇒ Array<BasicAccount>

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

Parameters:

  • account_ids (Array<String>)

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

Returns:

  • (Array<BasicAccount>)

    Basic information about any account.

Specifications:

  • returns account information of all given IDs
    
    
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    # 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. test_accounts.keys
    
    accounts.each do ||
      expect().to be_a(DropboxApi::Metadata::BasicAccount)
      expect(.name.display_name)
        .to eq(test_accounts[.])
    end
  • raises an error if one account cannot be found
    
    
    21
    22
    23
    24
    25
    26
    27
    28
    # File 'spec/endpoints/users/get_account_batch_spec.rb', line 15
    
     = %w(
      dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtXXX
      dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs
    )
    
    expect {
      @client. 
    }.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 ||
  perform_request account_ids: 
end

#get_current_accountBasicAccount

Get information about the current user's account.

Returns:

  • (BasicAccount)

    Detailed information about the current user's account.

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
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/users/get_current_account_spec.rb', line 12
    
     = @client.
    
    expect().to be_a(DropboxApi::Metadata::BasicAccount)
    expect(.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`
    
    
    8
    9
    10
    11
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 30
    
    file = @client.("#{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.("#{path_prefix}/file.txt")
    
    expect(file.client_modified).to eq(Time.new(1988, 12, 8, 1, 1, 0, '+00:00'))
  • may return a `Folder`
    
    
    21
    22
    23
    24
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 30
    
    folder = @client.("#{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.("#{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.("#{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.("#{path_prefix}/deleted_file.txt")
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • with `:include_deleted`, returns a `File`
    
    
    47
    48
    49
    50
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 30
    
    file = @client.("#{path_prefix}/deleted_file.txt", include_deleted: true)
    
    expect(file).to be_a(DropboxApi::Metadata::Deleted)
    expect(file.name).to eq('deleted_file.txt')


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

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

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

#get_preview(path, &block) ⇒ Object

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

Parameters:

  • path (String)

    The path of the file to preview.

Specifications:

  • returns the file
    
    
    7
    8
    9
    10
    # 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 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
    
    
    11
    12
    13
    14
    15
    16
    17
    # 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. shared_link.url
    
    expect(result).to be_a(DropboxApi::Metadata::FileLinkMetadata)
  • works with a folder
    
    
    21
    22
    23
    24
    25
    26
    27
    # 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. shared_link.url
    
    expect(result).to be_a(DropboxApi::Metadata::FolderLinkMetadata)
  • raises an error if the link can't be found
    
    
    31
    32
    33
    34
    35
    # 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. bad_link
    }.to raise_error(DropboxApi::Errors::SharedLinkNotFoundError)


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

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

  perform_request options.merge(
    url: preview_link
  )
end

#get_space_usageSpaceUsage

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

Returns:

  • (SpaceUsage)

    Information about a user's space usage and quota.



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

add_endpoint :get_space_usage do
  perform_request nil
end

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

Parameters:

  • path (String)

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

Specifications:

  • returns a GetTemporaryLinkResult with file and link
    
    
    7
    8
    9
    10
    # 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
    
    
    7
    8
    9
    10
    # 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)


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

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

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

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

Get a thumbnails for a batch of images.

Parameters:

  • paths (Array<String>)

    The paths to the image files you want thumbnails for.

Options Hash (options):

  • format (:jpeg, :png)

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

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

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

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

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

Specifications:

  • returns files
    
    
    9
    10
    11
    12
    13
    14
    # 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.).to be_a(DropboxApi::Metadata::File)
    expect(entry.thumbnail).to be_a(String)
    expect(entry..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)


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

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

  perform_request entries: build_entries_params(paths, options)
end

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

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

Apps must have full Dropbox access to use this endpoint.

Examples:

List file members.

client.list_file_members "1231273663"

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

client.list_file_members "1231273663", [:make_owner]

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

client.list_file_members "/my/file.pdf"

Parameters:

  • file_id (String)

    The ID for the shared file.

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

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

Options Hash (options):

  • include_inherited (Boolean)

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

  • limit (Numeric)

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

Returns:

  • (SharedFileMembers)

    Shared file user and group membership.

See Also:

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)


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

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

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

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

Returns the contents of a folder.

Parameters:

  • path (String)

    The path to the folder you want to read.

Options Hash (options):

  • recursive (Boolean)

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

  • include_media_info (Boolean)

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

  • include_deleted (Boolean)

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

  • limit (Numeric)

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

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
    
    
    20
    21
    22
    23
    24
    # 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
    
    
    28
    29
    30
    31
    32
    33
    34
    # 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
    
    
    50
    51
    52
    53
    54
    # 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
    
    
    58
    59
    60
    61
    62
    63
    64
    65
    # 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'


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

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

#list_folder_continue(cursor) ⇒ Object

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

Parameters:

  • cursor (String)

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

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
    
    
    14
    15
    16
    17
    # 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)


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

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

  perform_request options
end

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

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

Parameters:

  • cursor (String)

    A cursor as returned by list_folder or list_folder_continue.

Options Hash (options):

  • timeout (Numeric)

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

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


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

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

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

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

Returns shared folder membership by its folder ID.

Apps must have full Dropbox access to use this endpoint.

Examples:

List folder members.

client.list_folder_members "1231273663"

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

client.list_folder_members "1231273663", [:make_owner]

Parameters:

  • folder_id (String)

    The ID for the shared folder.

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

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

Options Hash (options):

  • limit (Numeric)

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

Returns:

  • (SharedFolderMembers)

    Shared folder user and group membership.

See Also:

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)


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

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

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

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

Return revisions of a file

Parameters:

  • path (String)

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

Options Hash (options):

  • limit (Numeric)

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

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
    
    
    19
    20
    21
    22
    23
    # 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


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

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

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

List shared links of this user.

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

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

Options Hash (options):

  • path (String)
  • cursor (String)

    The cursor returned by your last call.

  • direct_only (Boolean)

Returns:

  • (ListSharedLinksResult)

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
    
    
    14
    15
    16
    17
    18
    19
    # 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
    
    
    23
    24
    25
    26
    27
    28
    29
    30
    # 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
    
    
    42
    43
    44
    45
    46
    47
    # 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
    ))


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

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

  perform_request options
end

#middlewareObject



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
    
    
    7
    8
    9
    10
    # 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
    
    
    14
    15
    16
    17
    # 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
    
    
    21
    22
    23
    24
    # 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)


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

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

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

#namespace_idObject



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)


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

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

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

#restore(path, rev) ⇒ Object

Restore a file to a specific revision

Parameters:

  • path (String)

    The path to the file you want to restore.

  • rev (String)

    The revision to restore for the file.

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)


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

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

Revoke a shared link.

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

A successful response indicates that the shared link was revoked.

Parameters:

  • url (String)

    shared url which needs to be revoked.

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)


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

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

#save_url(path, url) ⇒ Object

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

Parameters:

  • path (String)

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

  • url (String)

    The URL to be saved.

Returns:

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

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)


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

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

#save_url_check_job_status(job_id) ⇒ Object

Check the status of a save_url job.

Parameters:

  • job_id (String)

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

Returns:

  • The current status of the job.

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
    
    
    13
    14
    15
    16
    # 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
    
    
    20
    21
    22
    23
    24
    # 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)


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

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

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

Searches for files and folders.

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

Parameters:

  • query (String)

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

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

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

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

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

Specifications:

  • returns a list of matching results
    
    
    7
    8
    9
    10
    11
    12
    # 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
    
    
    16
    17
    18
    19
    20
    21
    # 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


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

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

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

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

  perform_request(params)
end

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

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
    
    
    19
    20
    21
    22
    # 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')


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

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

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

#token_revokeObject

Revoke the access token for the current account

Specifications:

  • revokes the token
    
    
    7
    # File 'spec/endpoints/auth/token_revoke_spec.rb', line 11
    
     = @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)


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

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

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

Creates a new file.

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

For larger files you can use #upload_by_chunks.

Examples:

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

Parameters:

  • path (String)

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

  • content

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

Options Hash (options):

  • mode (DropboxApi::Metadata::WriteMode)

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

  • autorename (Boolean)

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

  • client_modified (DateTime)

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

  • mute (Boolean)

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

See Also:

Specifications:

  • uploads a file
    
    
    8
    9
    10
    11
    # 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
    
    
    15
    16
    17
    18
    19
    20
    # 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
    
    
    24
    25
    26
    27
    28
    29
    30
    # 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
    
    
    34
    35
    36
    37
    38
    39
    40
    # 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
    
    
    44
    45
    46
    47
    48
    49
    50
    51
    # File 'spec/endpoints/files/upload_spec.rb', line 50
    
    rev = @client.("#{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
    
    
    55
    56
    57
    58
    59
    60
    61
    62
    63
    # 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
    
    
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    # 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
    
    
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    # 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
    
    
    8
    9
    10
    11
    # 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
    
    
    15
    16
    17
    18
    19
    20
    # 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
    
    
    24
    25
    26
    27
    28
    29
    30
    # 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')


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

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

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

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

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

Examples:

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

Parameters:

  • path (String)

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

  • content

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

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

    a customizable set of options

Options Hash (options):

  • mode (DropboxApi::Metadata::WriteMode)

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

  • autorename (Boolean)

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

  • client_modified (DateTime)

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

  • mute (Boolean)

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

  • chunk_size (Numeric)

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

See Also:



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

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

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

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

Append more data to an upload session.

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

A single request should not upload more than 150 MB.

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

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

Examples:

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

Parameters:

Options Hash (options):

  • close (Boolean)

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

See Also:

  • UploadSessionCursor

Specifications:

  • can be used to append an upload
    
    
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    # 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
    
    
    23
    24
    25
    26
    27
    28
    29
    30
    # 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
    
    
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    # 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)


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

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

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

  cursor.offset += content.bytesize
end

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

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

A single request should not upload more than 150 MB.

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

Parameters:

Specifications:

  • will create a file
    
    
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # 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')


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

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

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

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

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

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

Options Hash (options):

  • close (Boolean)

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

Returns:

Specifications:

  • returns a session
    
    
    7
    8
    9
    10
    # 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')


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

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

  session = perform_request(options, content)

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