Class: DropboxApi::Client

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

virtual collapse

sharing collapse

files collapse

users collapse

auth collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Client



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

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

Instance Method Details

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

Adds specified members to a file.

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

Parameters:

  • file (String)

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

  • members

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

Options Hash (options):

  • quiet (Boolean)

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

  • custom_message (String)

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

  • access_level (AccessLevel)

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

  • add_message_as_comment (String)

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

See Also:

Specifications:

  • adds 1 member to a file
    
    
    6
    7
    8
    9
    10
    11
    12
    13
    14
    # File 'spec/endpoints/sharing/add_file_member_spec.rb', line 33
    
    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
    
    
    18
    19
    20
    21
    22
    23
    24
    25
    26
    # File 'spec/endpoints/sharing/add_file_member_spec.rb', line 33
    
    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
    
    
    30
    31
    32
    33
    34
    35
    36
    # File 'spec/endpoints/sharing/add_file_member_spec.rb', line 33
    
    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
    
    
    40
    41
    42
    43
    44
    45
    46
    47
    # File 'spec/endpoints/sharing/add_file_member_spec.rb', line 33
    
    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)


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

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
    
    
    6
    7
    # File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 38
    
    folder_id = "1236358158"
    folder = @client.add_folder_member folder_id, "somebody@test.com"
  • shares the folder, if the folder id is a number
    
    
    13
    14
    # File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 38
    
    folder_id = 1236358158
    folder = @client.add_folder_member folder_id, "somebody@test.com"
  • shares the folder, if the param is an AddMember object
    
    
    20
    21
    # File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 38
    
    folder_id = 1236358158
    folder = @client.add_folder_member folder_id, "somebody@test.com"
  • shares the folder, if the member param is an email string
    
    
    27
    28
    # File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 38
    
    folder_id = 1236358158
    folder = @client.add_folder_member folder_id, "somebody@test.com"
  • fails with an invalid folder id
    
    
    34
    35
    36
    37
    38
    # File 'spec/endpoints/sharing/add_folder_member_spec.rb', line 38
    
    folder_id = "xxx"
    expect {
      folder = @client.add_folder_member folder_id, "somebody@test.com"
    
    }.to raise_error(DropboxApi::Errors::InvalidIdError)


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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/copy_spec.rb', line 14
    
    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
    
    
    13
    14
    15
    # File 'spec/endpoints/files/copy_spec.rb', line 14
    
    expect {
      @client.copy("/z.jpg", "/b.jpg")
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • raises an error if the path is invalid
    
    
    19
    20
    21
    # File 'spec/endpoints/files/copy_spec.rb', line 14
    
    expect {
      @client.copy("/../invalid_path.jpg", "/b.jpg")
    }.to raise_error(DropboxApi::Errors::MalformedPathError)


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

add_endpoint :copy do |from, to|
  perform_request({
    :from_path => from,
    :to_path => to
  })
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:



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

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:



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

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
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/file_requests/create_file_request_spec.rb', line 14
    
    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
    
    
    14
    15
    16
    # File 'spec/endpoints/file_requests/create_file_request_spec.rb', line 14
    
    expect {
      @client.create_file_request 'Arizona, baby', "#{path_prefix}/regular_file.txt"
    }.to raise_error(DropboxApi::Errors::CreateFileRequestError)


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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/create_folder_spec.rb', line 12
    
    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
    
    
    13
    14
    15
    # File 'spec/endpoints/files/create_folder_spec.rb', line 12
    
    expect {
      @client.create_folder("/arizona\\baby")
    }.to raise_error(DropboxApi::Errors::MalformedPathError)
  • raises an error if the resource causes a conflict
    
    
    19
    20
    21
    # File 'spec/endpoints/files/create_folder_spec.rb', line 12
    
    expect {
      @client.create_folder("/b.jpg")
    }.to raise_error(DropboxApi::Errors::FileConflictError)


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

add_endpoint :create_folder do |path|
  perform_request({
    :path => path
  })
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:



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

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
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/files/delete_spec.rb', line 24
    
    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
    
    
    14
    15
    16
    # File 'spec/endpoints/files/delete_spec.rb', line 24
    
    expect {
      @client.delete "#{path_prefix}/wont_be_deleted.txt", :parent_rev => "1c0576c68d6"
    }.to raise_error(DropboxApi::Errors::FileConflictError)
  • returns the deleted folder
    
    
    20
    21
    22
    23
    # File 'spec/endpoints/files/delete_spec.rb', line 24
    
    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
    
    
    27
    28
    29
    # File 'spec/endpoints/files/delete_spec.rb', line 24
    
    expect {
      @client.delete "/unexisting folder"
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

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

  perform_request options.merge({
    :path => path
  })
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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/download_spec.rb', line 11
    
    file = @client.download "/file.txt"
    
    expect(file).to be_a(DropboxApi::Metadata::File)
    expect(file.name).to eq("file.txt")
  • yields the file contents
    
    
    13
    14
    15
    16
    17
    18
    # File 'spec/endpoints/files/download_spec.rb', line 11
    
    file_contents = ""
    file = @client.download "/file.txt" do |chunk|
      file_contents << chunk
    end
    
    expect(file_contents).to eq("Viva Rusia!\n")
  • raises an error if the name is invalid
    
    
    22
    23
    24
    # File 'spec/endpoints/files/download_spec.rb', line 11
    
    expect {
      @client.download("/c.jpg")
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/users/get_account_spec.rb', line 12
    
     = @client. "dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs"
    
    expect().to be_a(DropboxApi::Metadata::BasicAccount)
  • raises an error if the account can't be found
    
    
    12
    13
    14
    # File 'spec/endpoints/users/get_account_spec.rb', line 12
    
    expect {
      @client. "dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtXXX"
    }.to raise_error(DropboxApi::Errors::NoAccountError)


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

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
    
    
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # File 'spec/endpoints/users/get_account_batch_spec.rb', line 14
    
    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 can't e found
    
    
    20
    21
    22
    23
    24
    25
    26
    27
    # File 'spec/endpoints/users/get_account_batch_spec.rb', line 14
    
     = %w(
      dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtXXX
      dbid:AAAKVPLEKkkccsZMFkkZNXFeyXrPPhrtFxs
    )
    
    expect {
      @client. 
    }.to raise_error(DropboxApi::Errors::NoAccountError)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/users/get_space_usage_spec.rb', line 11
    
    space_usage = @client.get_space_usage
    
    expect(space_usage).to be_a(DropboxApi::Metadata::SpaceUsage)
  • returns the current account information
    
    
    6
    7
    8
    # File 'spec/endpoints/users/get_current_account_spec.rb', line 11
    
     = @client.
    
    expect().to be_a(DropboxApi::Metadata::BasicAccount)


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

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`
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 29
    
    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
    
    
    14
    15
    16
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 29
    
    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`
    
    
    20
    21
    22
    23
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 29
    
    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
    
    
    27
    28
    29
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 29
    
    expect {
      @client.("#{path_prefix}/unexisting_folder")
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • raises an error if an invalid option is given
    
    
    33
    34
    35
    # File 'spec/endpoints/files/get_metadata_spec.rb', line 29
    
    expect {
      @client.("#{path_prefix}/file.txt", :invalid_option => true)
    }.to raise_error ArgumentError


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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/get_preview_spec.rb', line 13
    
    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
    
    
    13
    14
    15
    # File 'spec/endpoints/files/get_preview_spec.rb', line 13
    
    expect {
      @client.get_preview("/unknown_file.jpg")
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

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
    
    
    10
    11
    12
    13
    14
    15
    16
    # File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 22
    
    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
    
    
    20
    21
    22
    23
    24
    25
    26
    # File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 22
    
    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
    
    
    30
    31
    32
    33
    34
    # File 'spec/endpoints/sharing/get_shared_link_metadata_spec.rb', line 22
    
    bad_link = "https://www.dropbox.com/sh/abcd/1234?dl=0"
    
    expect {
      @client. bad_link
    }.to raise_error(DropboxApi::Errors::SharedLinkNotFoundError)


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

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.



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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/get_temporary_link_spec.rb', line 13
    
    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
    
    
    13
    14
    15
    # File 'spec/endpoints/files/get_temporary_link_spec.rb', line 13
    
    expect {
      @client.get_preview "/unknown_file.jpg"
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/get_thumbnail_spec.rb', line 47
    
    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
    
    
    13
    14
    15
    # File 'spec/endpoints/files/get_thumbnail_spec.rb', line 47
    
    expect {
      @client.get_thumbnail "/unknown_file.jpg"
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • raises an argument error with invalid options
    
    
    19
    20
    21
    # File 'spec/endpoints/files/get_thumbnail_spec.rb', line 47
    
    expect {
      @client.get_thumbnail "/img.png", :invalid_arg => "value"
    }.to raise_error(ArgumentError)


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

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
    
    
    8
    9
    10
    11
    12
    13
    # File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 22
    
    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
    
    
    17
    18
    # File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 22
    
    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
    
    
    22
    23
    24
    # File 'spec/endpoints/files/get_thumbnail_batch_spec.rb', line 22
    
    expect {
      @client.get_thumbnail_batch ["#{path_prefix}/img.png"], :invalid_arg => "value"
    }.to raise_error(ArgumentError)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/sharing/list_file_members_spec.rb', line 36
    
    result = @client.list_file_members "1231273663"
    
    expect(result).to be_a(DropboxApi::Results::SharedFileMembers)
  • lists file members including member actions
    
    
    12
    13
    14
    # File 'spec/endpoints/sharing/list_file_members_spec.rb', line 36
    
    result = @client.list_file_members "1231273663", [:remove, :make_owner]
    
    expect(result).to be_a(DropboxApi::Results::SharedFileMembers)


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

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
    
    
    7
    8
    9
    # File 'spec/endpoints/files/list_folder_spec.rb', line 28
    
    result = @client.list_folder ""
    
    expect(result).to be_a(DropboxApi::Results::ListFolderResult)
  • raises an error if the file can't be found
    
    
    13
    14
    15
    # File 'spec/endpoints/files/list_folder_spec.rb', line 28
    
    expect {
      @client.list_folder "/unexisting_folder"
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • returns all entries as metadata objects
    
    
    19
    20
    21
    22
    23
    # File 'spec/endpoints/files/list_folder_spec.rb', line 28
    
    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
    
    
    27
    28
    29
    30
    31
    32
    33
    # File 'spec/endpoints/files/list_folder_spec.rb', line 28
    
    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
    
    
    37
    38
    39
    # File 'spec/endpoints/files/list_folder_spec.rb', line 28
    
    expect {
      @client.list_folder "/img.png", :invalid_arg => "value"
    }.to raise_error(ArgumentError)


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

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
    
    
    14
    15
    16
    # File 'spec/endpoints/files/list_folder_continue_spec.rb', line 16
    
    result = @client.list_folder_continue(@cursor)
    
    expect(result).to be_a(DropboxApi::Results::ListFolderResult)


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

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
    
    
    13
    14
    15
    16
    # File 'spec/endpoints/files/list_folder_get_latest_cursor_spec.rb', line 27
    
    result = @client.list_folder_get_latest_cursor :path => "/folder"
    
    expect(result)
      .to be_a(DropboxApi::Results::ListFolderGetLatestCursorResult)


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

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
    
    
    12
    13
    14
    # File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 24
    
    result = @client.list_folder_longpoll @cursor
    
    expect(result).to be_a(DropboxApi::Results::ListFolderLongpollResult)
  • indicates if there're changes
    
    
    18
    19
    20
    # File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 24
    
    result = @client.list_folder_longpoll @cursor
    
    expect(result.changes).to be_truthy
  • raises an error with an invalid cursor
    
    
    24
    25
    26
    # File 'spec/endpoints/files/list_folder_longpoll_spec.rb', line 24
    
    expect {
      @client.list_folder_longpoll "I believe in the blerch"
    }.to raise_error DropboxApi::Errors::HttpError


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/sharing/list_folder_members_spec.rb', line 29
    
    result = @client.list_folder_members "1231273663"
    
    expect(result).to be_a(DropboxApi::Results::SharedFolderMembers)
  • lists folder members including member actions
    
    
    12
    13
    14
    # File 'spec/endpoints/sharing/list_folder_members_spec.rb', line 29
    
    result = @client.list_folder_members "1231273663", [:remove, :make_owner]
    
    expect(result).to be_a(DropboxApi::Results::SharedFolderMembers)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/files/list_revisions_spec.rb', line 15
    
    result = @client.list_revisions "/file.txt"
    
    expect(result).to be_a(DropboxApi::Results::ListRevisionsResult)
  • raises an error if the file can't be found
    
    
    12
    13
    14
    # File 'spec/endpoints/files/list_revisions_spec.rb', line 15
    
    expect {
      @client.list_revisions "/unexisting_file"
    }.to raise_error(DropboxApi::Errors::NotFoundError)
  • returns all revisions as metadata objects
    
    
    18
    19
    20
    21
    22
    # File 'spec/endpoints/files/list_revisions_spec.rb', line 15
    
    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
    
    
    26
    27
    28
    # File 'spec/endpoints/files/list_revisions_spec.rb', line 15
    
    result = @client.list_revisions "/file.txt"
    
    expect(result.is_deleted?).to be_truthy


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

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)


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

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

  perform_request options
end

#middlewareObject



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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/move_spec.rb', line 19
    
    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
    
    
    13
    14
    15
    16
    # File 'spec/endpoints/files/move_spec.rb', line 19
    
    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
    
    
    20
    21
    22
    23
    # File 'spec/endpoints/files/move_spec.rb', line 19
    
    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
    
    
    27
    28
    29
    # File 'spec/endpoints/files/move_spec.rb', line 19
    
    expect {
      @client.move("/z.jpg", "/b.jpg")
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

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

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

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

Permanently delete the file or folder at a given path.

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

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

Parameters:

  • path (String)

    Path in the user's Dropbox to delete.

Options Hash (options):

  • parent_rev (String)

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

Specifications:

  • can't be tested without a Dropbox Business account :(
    
    
    7
    8
    9
    # File 'spec/endpoints/files/permanently_delete_spec.rb', line 20
    
    expect {
      @client.permanently_delete "#{path_prefix}/file.txt"
    }.to raise_error(DropboxApi::Errors::HttpError)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/files/restore_spec.rb', line 12
    
    file = @client.restore("/file.txt", "1a6a24061bdd")
    
    expect(file).to be_a(DropboxApi::Metadata::File)
  • raises an error with an invalid revision
    
    
    13
    14
    15
    # File 'spec/endpoints/files/restore_spec.rb', line 12
    
    expect {
      file = @client.restore("/file.txt", "1a6a24061000")
    }.to raise_error(DropboxApi::Errors::InvalidRevisionError)


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

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.



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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/files/save_url_spec.rb', line 15
    
    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
    
    
    12
    13
    14
    # File 'spec/endpoints/files/save_url_spec.rb', line 15
    
    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
    
    
    18
    19
    20
    # File 'spec/endpoints/files/save_url_spec.rb', line 15
    
    expect {
      file = @client.save_url("/photo_3.jpg", "1a6a24061000")
    }.to raise_error(DropboxApi::Errors::InvalidUrlError)


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

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
    
    
    6
    7
    8
    # File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 13
    
    result = @client.save_url_check_job_status "VofXAX8DO1sAAAAAAAAD_Q"
    
    expect(result).to be_a(DropboxApi::Metadata::File)
  • returns :in_progress if job not completed
    
    
    12
    13
    14
    15
    # File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 13
    
    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
    
    
    19
    20
    21
    22
    23
    # File 'spec/endpoints/files/save_url_check_job_status_spec.rb', line 13
    
    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)


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

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

#search(query, path = "", options = {}) ⇒ 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. The search string is split on spaces into multiple tokens. For file name searching, the last token is used for prefix matching (i.e. "bat c" matches "bat cave" but not "batman car").

  • path (String) (defaults to: "")

    The path in the user's Dropbox to search.

Options Hash (options):

  • start (Numeric)

    The starting index within the search results (used for paging). The default for this field is 0.

  • max_results (Numeric)

    The maximum number of search results to return. The default for this field is 100.

  • mode (:filename, :filename_and_content, :deleted_filename)

    The search mode. Note that searching file content is only available for Dropbox Business accounts. The default is filename.

Specifications:

  • returns a list of matching results
    
    
    6
    7
    8
    9
    10
    # File 'spec/endpoints/files/search_spec.rb', line 27
    
    result = @client.search("image.png")
    
    expect(result).to be_a(DropboxApi::Results::SearchResult)
    file = result.matches.first.resource
    expect(file.name).to eq("image.png")
  • raises an error if the file can't be found
    
    
    14
    15
    16
    # File 'spec/endpoints/files/search_spec.rb', line 27
    
    expect {
      @client.search("/image.png", "/bad_folder")
    }.to raise_error(DropboxApi::Errors::NotFoundError)


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

add_endpoint :search do |query, path = "", options = {}|
  validate_options([
    :start,
    :max_results,
    :mode
  ], options)
  options[:start] ||= 0
  options[:max_results] ||= 100
  options[:mode] ||= :filename

  perform_request options.merge({
    :query => query,
    :path => path
  })
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
    
    
    6
    7
    8
    # File 'spec/endpoints/sharing/share_folder_spec.rb', line 36
    
    folder = @client.share_folder("/folder_k")
    
    expect(folder).to be_a(DropboxApi::Metadata::SharedFolder)
  • returns the shared folder, even if already shared
    
    
    12
    13
    14
    # File 'spec/endpoints/sharing/share_folder_spec.rb', line 36
    
    folder = @client.share_folder("/already_shared")
    
    expect(folder).to be_a(DropboxApi::Metadata::SharedFolder)
  • contains a shared folder id
    
    
    18
    19
    20
    21
    # File 'spec/endpoints/sharing/share_folder_spec.rb', line 36
    
    folder = @client.share_folder("/folder_k")
    
    expect(folder.shared_folder_id.to_s)
      .to eq("1236414195")


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

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
    
    
    6
    # File 'spec/endpoints/auth/token_revoke_spec.rb', line 10
    
     = @client.token_revoke


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

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
    
    
    6
    # File 'spec/endpoints/sharing/unshare_file_spec.rb', line 13
    
    file = @client.unshare_file("id:xyz123")
  • returns file access permission error
    
    
    12
    13
    14
    # File 'spec/endpoints/sharing/unshare_file_spec.rb', line 13
    
    expect {
      @client.unshare_file("id:xyz123")
    }.to raise_error(DropboxApi::Errors::NoPermissionError)
  • returns email unverified error
    
    
    18
    19
    20
    # File 'spec/endpoints/sharing/unshare_file_spec.rb', line 13
    
    expect {
      @client.unshare_file("id:xyz123")
    }.to raise_error(DropboxApi::Errors::EmailUnverifiedError)


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

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
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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
    
    
    14
    15
    16
    17
    18
    19
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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
    
    
    23
    24
    25
    26
    27
    28
    29
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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
    
    
    33
    34
    35
    36
    37
    38
    39
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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
    
    
    43
    44
    45
    46
    47
    48
    49
    50
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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
    
    
    54
    55
    56
    57
    58
    59
    60
    61
    62
    # File 'spec/endpoints/files/upload_spec.rb', line 49
    
    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)
  • uploads a file
    
    
    7
    8
    9
    10
    # File 'spec/endpoints/virutal/upload_by_chunks_spec.rb', line 49
    
    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
    
    
    14
    15
    16
    17
    18
    19
    # File 'spec/endpoints/virutal/upload_by_chunks_spec.rb', line 49
    
    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
    
    
    23
    24
    25
    26
    27
    28
    29
    # File 'spec/endpoints/virutal/upload_by_chunks_spec.rb', line 49
    
    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")


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

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:



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

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
    
    
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    # File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 38
    
    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
    
    
    22
    23
    24
    25
    26
    27
    28
    29
    # File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 38
    
    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
    
    
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    # File 'spec/endpoints/files/upload_session_append_v2_spec.rb', line 38
    
    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)


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

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
    
    
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    # File 'spec/endpoints/files/upload_session_finish_spec.rb', line 21
    
    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")


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

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
    
    
    6
    7
    8
    9
    # File 'spec/endpoints/files/upload_session_start_spec.rb', line 25
    
    cursor = @client.upload_session_start("Hello Dropbox!")
    
    expect(cursor).to be_a(DropboxApi::Metadata::UploadSessionCursor)
    expect(cursor.session_id).to eq("AAAAAAAMOCK_SESSION_ID")


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

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