Class: DropboxApi::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dropbox_api/client.rb

sharing collapse

files collapse

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



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", "[email protected]"

Parameters:

  • folder_id (String) —

    The ID for the shared folder.

  • members (Array<AddMember,String>) —

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

Options Hash (options):

  • quiet (Boolean) —

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

  • custom_message (String) —

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

See Also:



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.



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_folder(path) ⇒ DropboxApi::Metadata::Folder

Create a folder at a given path.

Parameters:

  • path (String) —

    Path in the user's Dropbox to create.

Returns:



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

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

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.

Returns:



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

add_endpoint :create_shared_link_with_settings do |path, settings = {}|
  # NOTE: This endpoint accepts an additional option `settings` which
  #       hasn't been implemented.
  perform_request :path => path
end

#delete(path) ⇒ 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 FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

Parameters:

  • path (String) —

    Path in the user's Dropbox to delete.



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

add_endpoint :delete do |path|
  perform_request({
    :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.



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.



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.



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_account ⇒ BasicAccount

Get information about the current user's account.

Returns:

  • (BasicAccount) —

    Detailed information about the current user's account.



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.



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

add_endpoint :get_metadata do |path, options = {}|
  validate_options([:include_media_info, :include_deleted], 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.



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_space_usage ⇒ SpaceUsage

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

Returns:

  • (SpaceUsage) —

    Information about a user's space usage and quota.



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

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

Parameters:

  • path (String) —

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



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



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

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

Returns the contents of a folder.

Parameters:

  • path (String) —

    The path to the folder you want to read.



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

add_endpoint :list_folder do |path, options = {}|
  validate_options([
    :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.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.



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 API#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+, +FileMetadata.media_info+ is set for photo and video. The default for this field is +false+.

  • include_deleted (Boolean) —

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



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

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

  perform_request options
end

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

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

Parameters:

  • cursor (String) —

    A cursor as returned by list_folder or list_folder_continue.

Options Hash (options):

  • timeout (Numeric) —

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



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:



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.



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

List shared links of this user.

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

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

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

#middleware ⇒ Object 



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



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

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



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

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



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.



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.



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 = {}) ⇒ 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 ShareFolderArg.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.

Returns:

  • (ShareFolderLaunch) —

    Shared folder metadata.



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

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



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. Instead, create an upload session with #upload_session_start().

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.

See Also:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/dropbox_api/endpoints/files/upload.rb', line 43

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

  options[:mode] = build_write_mode_param(options[:mode]) if options[:mode]
  options[:client_modified] = options[:client_modified].utc.strftime("%FT%TZ") if options[:client_modified]

  perform_request(options.merge({
    :path => path
  }), content)
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 of file contents.

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


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

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 of file contents.

other optional modifiers for the commit.

Parameters:



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

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:



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