Back to DropboxFiles - Upload Session - Finish Batch
This route helps you commit many files at once into a user's Dropbox. Use :route:upload_session/start
and :route:upload_session/append_v2
to upload file contents. We recommend uploading many files in parallel to increase throughput. Once the file contents have been uploaded, rather than calling :route:upload_session/finish
, use this route to finish all your upload sessions in a single request.
:field:UploadSessionStartArg.close
or :field:UploadSessionAppendArg.close
needs to be true for the last :route:upload_session/start
or :route:upload_session/append_v2
call. The maximum size of a file one can upload to an upload session is 350 GB.
This route will return a job_id immediately and do the async commit job in background. Use :route:upload_session/finish_batch/check
to check the job status.
For the same account, this route should be executed serially. That means you should not start the next job before current job finishes. We allow up to 1000 entries in a single request.
Input
type: object
properties:
data:
type: object
description: |
entries: Commit information for each file in the batch.
properties:
entries:
type: array
description: Commit information for each file in the batch.
items:
type: object
description: >
cursor: Contains the upload session ID and the offset.
commit: Contains the path and other optional modifiers for the
commit.
properties:
cursor:
type: object
description: >
session_id: The upload session ID (returned by
:route:`upload_session/start`).
offset: The amount of data that has been uploaded so far. We use
this to make sure upload data isn't lost or duplicated in the
event of a network error.
properties:
session_id:
type: string
description: >-
The upload session ID (returned by
:route:`upload_session/start`).
offset:
type: number
description: >-
The amount of data that has been uploaded so far. We use
this to make sure upload data isn't lost or duplicated in
the event of a network error.
commit:
type: object
description: >
path: Path in the user's Dropbox to save the file.
mode: Selects what to do if the file already exists.
autorename: If there's a conflict, as determined by
:field:`mode`, have the Dropbox server try to autorename the
file to avoid conflict.
client_modified: The value to store as the
:field:`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: Normally, users are made aware of any file modifications
in their Dropbox account via notifications in the client
software. If :val:`true`, this tells the clients that this
modification shouldn't result in a user notification.
property_groups: List of custom properties to add to file.
properties:
autorename:
type: boolean
description: >-
If there's a conflict, as determined by :field:`mode`, have
the Dropbox server try to autorename the file to avoid
conflict.
mute:
type: boolean
description: >-
Normally, users are made aware of any file modifications in
their Dropbox account via notifications in the client
software. If :val:`true`, this tells the clients that this
modification shouldn't result in a user notification.
client_modified:
type: string
description: >-
The value to store as the :field:`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.
mode:
type: object
description: >
Your intent when writing a file to some path. This is used
to determine what constitutes a conflict and what the
autorename strategy is.
In some situations, the conflict behavior is identical: (a)
If the target path doesn't refer to anything, the file is
always written; no conflict. (b) If the target path refers
to a folder, it's always a conflict. (c) If the target path
refers to a file with identical contents, nothing gets
written; no conflict.
The conflict checking differs in the case where there's a
file at the target path with contents different from the
contents you're trying to write.
add: Do not overwrite an existing file if there is a
conflict. The autorename strategy is to append a number to
the file name. For example, "document.txt" might become
"document (2).txt".
overwrite: Always overwrite the existing file. The
autorename strategy is the same as it is for :field:`add`.
update: Overwrite if the given "rev" matches the existing
file's "rev". The autorename strategy is to append the
string "conflicted copy" to the file name. For example,
"document.txt" might become "document (conflicted copy).txt"
or "document (Panda's conflicted copy).txt".
properties:
.tag:
title: Choice of WriteMode
type: string
enum:
- add
- overwrite
- update
update:
type: string
description: >-
Overwrite if the given "rev" matches the existing file's
"rev". The autorename strategy is to append the string
"conflicted copy" to the file name. For example,
"document.txt" might become "document (conflicted
copy).txt" or "document (Panda's conflicted copy).txt".
path:
type: string
description: Path in the user's Dropbox to save the file.
property_groups:
type: array
description: List of custom properties to add to file.
items:
type: object
description: >
A subset of the property fields described by the
corresponding :type:`PropertyGroupTemplate`. Properties
are always added to a Dropbox file as a
:type:`PropertyGroup`. The possible key names and value
types in this group are defined by the corresponding
:type:`PropertyGroupTemplate`.
template_id: A unique identifier for the associated
template.
fields: The actual properties associated with the
template. There can be up to 32 property types per
template.
properties:
fields:
type: array
description: >-
The actual properties associated with the template.
There can be up to 32 property types per template.
items:
type: object
description: >
Raw key/value data to be associated with a Dropbox
file. Property fields are added to Dropbox files as
a :type:`PropertyGroup`.
name: Key of the property field associated with a
file and template. Keys can be up to 256 bytes.
value: Value of the property field associated with a
file and template. Values can be up to 1024 bytes.
properties:
name:
type: string
description: >-
Key of the property field associated with a file
and template. Keys can be up to 256 bytes.
value:
type: string
description: >-
Value of the property field associated with a
file and template. Values can be up to 1024
bytes.
template_id:
type: string
description: A unique identifier for the associated template.
title: Data
Output
type: object
description: >
Result returned by :route:`upload_session/finish_batch` that may either launch
an asynchronous job or complete synchronously.
async_job_id: This response indicates that the processing is asynchronous. The
string is an id that can be used to obtain the status of the asynchronous job.
complete: None
other: None
properties:
.tag:
title: Choice of UploadSessionFinishBatchLaunch
type: string
enum:
- async_job_id
- complete
- other
async_job_id:
type: string
description: >-
This response indicates that the processing is asynchronous. The string is
an id that can be used to obtain the status of the asynchronous job.
complete:
type: object
description: |
entries: Commit result for each file in the batch.
properties:
entries:
type: array
description: Commit result for each file in the batch.
items:
type: object
description: |
success: None
failure: None
properties:
failure:
type: object
description: >
lookup_failed: The session arguments are incorrect; the value
explains the reason.
path: Unable to save the uploaded contents to a file. Data has
already been appended to the upload session. Please retry with
empty data body and updated offset.
properties_error: The supplied property group is invalid. The
file has uploaded without property groups.
too_many_shared_folder_targets: The batch request commits files
into too many different shared folders. Please limit your batch
request to files contained in a single shared folder.
too_many_write_operations: There are too many write operations
happening in the user's Dropbox. You should retry uploading this
file.
other: None
properties:
properties_error:
type: object
description: >
template_not_found: Template does not exist for the given
identifier.
restricted_content: You do not have permission to modify
this template.
other: None
path: None
unsupported_folder: This folder cannot be tagged. Tagging
folders is not supported for team-owned templates.
property_field_too_large: One or more of the supplied
property field values is too large.
does_not_fit_template: One or more of the supplied property
fields does not conform to the template specifications.
properties:
path:
type: object
description: >
malformed_path: None
not_found: There is nothing at the given path.
not_file: We were expecting a file, but the given path
refers to something that isn't a file.
not_folder: We were expecting a folder, but the given
path refers to something that isn't a folder.
restricted_content: The file cannot be transferred
because the content is restricted. For example,
sometimes there are legal restrictions due to copyright
claims.
other: None
properties:
malformed_path:
type: string
.tag:
title: Choice of LookupError
type: string
enum:
- malformed_path
- not_found
- not_file
- not_folder
- restricted_content
- other
.tag:
title: Choice of InvalidPropertyGroupError
type: string
enum:
- template_not_found
- restricted_content
- other
- path
- unsupported_folder
- property_field_too_large
- does_not_fit_template
template_not_found:
type: string
description: Template does not exist for the given identifier.
path:
type: object
description: >
malformed_path: None
conflict: Couldn't write to the target path because there
was something in the way.
no_write_permission: The user doesn't have permissions to
write to the target location.
insufficient_space: The user doesn't have enough available
space (bytes) to write more data.
disallowed_name: Dropbox will not save the file or folder
because of its name.
team_folder: This endpoint cannot move or delete team
folders.
too_many_write_operations: There are too many write
operations in user's Dropbox. Please retry this request.
other: None
properties:
malformed_path:
type: string
.tag:
title: Choice of WriteError
type: string
enum:
- malformed_path
- conflict
- no_write_permission
- insufficient_space
- disallowed_name
- team_folder
- too_many_write_operations
- other
conflict:
type: object
description: >
file: There's a file in the way.
folder: There's a folder in the way.
file_ancestor: There's a file at an ancestor path, so we
couldn't create the required parent folders.
other: None
properties:
.tag:
title: Choice of WriteConflictError
type: string
enum:
- file
- folder
- file_ancestor
- other
.tag:
title: Choice of UploadSessionFinishError
type: string
enum:
- lookup_failed
- path
- properties_error
- too_many_shared_folder_targets
- too_many_write_operations
- other
lookup_failed:
type: object
description: >
not_found: The upload session ID was not found or has
expired. Upload sessions are valid for 48 hours.
incorrect_offset: The specified offset was incorrect. See
the value for the correct offset. This error may occur when
a previous request was received and processed successfully
but the client did not receive the response, e.g. due to a
network error.
closed: You are attempting to append data to an upload
session that has alread been closed (i.e. committed).
not_closed: The session must be closed before calling
upload_session/finish_batch.
too_large: You can not append to the upload session because
the size of a file should not reach the max file size limit
(i.e. 350GB).
other: None
properties:
.tag:
title: Choice of UploadSessionLookupError
type: string
enum:
- not_found
- incorrect_offset
- closed
- not_closed
- too_large
- other
incorrect_offset:
type: object
description: >
correct_offset: The offset up to which data has been
collected.
properties:
correct_offset:
type: number
description: The offset up to which data has been collected.
.tag:
title: Choice of UploadSessionFinishBatchResultEntry
type: string
enum:
- success
- failure
success:
type: object
description: >
name: The last component of the path (including extension). This
never contains a slash.
id: A unique identifier for the file.
client_modified: For files, this is the modification time set by
the desktop client when the file was added to Dropbox. Since
this time is not verified (the Dropbox server stores whatever
the desktop client sends up), this should only be used for
display purposes (such as sorting) and not, for example, to
determine if a file has changed or not.
server_modified: The last time the file was modified on Dropbox.
rev: A unique identifier for the current revision of a file.
This field is the same rev as elsewhere in the API and can be
used to detect changes and avoid conflicts.
size: The file size in bytes.
path_lower: The lowercased full path in the user's Dropbox. This
always starts with a slash. This field will be null if the file
or folder is not mounted.
path_display: The cased path to be used for display purposes
only. In rare instances the casing will not correctly match the
user's filesystem, but this behavior will match the path
provided in the Core API v1, and at least the last path
component will have the correct casing. Changes to only the
casing of paths won't be returned by
:route:`list_folder/continue`. This field will be null if the
file or folder is not mounted.
parent_shared_folder_id: Please use
:field:`FileSharingInfo.parent_shared_folder_id` or
:field:`FolderSharingInfo.parent_shared_folder_id` instead.
media_info: Additional information if the file is a photo or
video.
symlink_info: Set if this file is a symlink.
sharing_info: Set if this file is contained in a shared folder.
property_groups: Additional information if the file has custom
properties with the property template specified.
has_explicit_shared_members: This flag will only be present if
include_has_explicit_shared_members is true in
:route:`list_folder` or :route:`get_metadata`. If this flag is
present, it will be true if this file has any explicit shared
members. This is different from sharing_info in that this could
be true in the case where a file has explicit members but is
not contained within a shared folder.
content_hash: A hash of the file content. This field can be used
to verify data integrity. For more information see our
:link:`Content hash /developers/reference/content-hash` page.
properties:
parent_shared_folder_id:
type: string
description: >-
Please use :field:`FileSharingInfo.parent_shared_folder_id`
or :field:`FolderSharingInfo.parent_shared_folder_id`
instead.
name:
type: string
description: >-
The last component of the path (including extension). This
never contains a slash.
property_groups:
type: array
description: >-
Additional information if the file has custom properties
with the property template specified.
items:
type: object
description: >
A subset of the property fields described by the
corresponding :type:`PropertyGroupTemplate`. Properties
are always added to a Dropbox file as a
:type:`PropertyGroup`. The possible key names and value
types in this group are defined by the corresponding
:type:`PropertyGroupTemplate`.
template_id: A unique identifier for the associated
template.
fields: The actual properties associated with the
template. There can be up to 32 property types per
template.
properties:
fields:
type: array
description: >-
The actual properties associated with the template.
There can be up to 32 property types per template.
items:
type: object
description: >
Raw key/value data to be associated with a Dropbox
file. Property fields are added to Dropbox files as
a :type:`PropertyGroup`.
name: Key of the property field associated with a
file and template. Keys can be up to 256 bytes.
value: Value of the property field associated with a
file and template. Values can be up to 1024 bytes.
properties:
name:
type: string
description: >-
Key of the property field associated with a file
and template. Keys can be up to 256 bytes.
value:
type: string
description: >-
Value of the property field associated with a
file and template. Values can be up to 1024
bytes.
template_id:
type: string
description: A unique identifier for the associated template.
rev:
type: string
description: >-
A unique identifier for the current revision of a file. This
field is the same rev as elsewhere in the API and can be
used to detect changes and avoid conflicts.
client_modified:
type: string
description: >-
For files, this is the modification time set by the desktop
client when the file was added to Dropbox. Since this time
is not verified (the Dropbox server stores whatever the
desktop client sends up), this should only be used for
display purposes (such as sorting) and not, for example, to
determine if a file has changed or not.
symlink_info:
type: object
description: |
target: The target this symlink points to.
properties:
target:
type: string
description: The target this symlink points to.
path_display:
type: string
description: >-
The cased path to be used for display purposes only. In rare
instances the casing will not correctly match the user's
filesystem, but this behavior will match the path provided
in the Core API v1, and at least the last path component
will have the correct casing. Changes to only the casing of
paths won't be returned by :route:`list_folder/continue`.
This field will be null if the file or folder is not
mounted.
has_explicit_shared_members:
type: boolean
description: >-
This flag will only be present if
include_has_explicit_shared_members is true in
:route:`list_folder` or :route:`get_metadata`. If this flag
is present, it will be true if this file has any explicit
shared members. This is different from sharing_info in that
this could be true in the case where a file has explicit
members but is not contained within a shared folder.
path_lower:
type: string
description: >-
The lowercased full path in the user's Dropbox. This always
starts with a slash. This field will be null if the file or
folder is not mounted.
server_modified:
type: string
description: The last time the file was modified on Dropbox.
sharing_info:
type: object
description: >
Sharing info for a file which is contained by a shared
folder.
read_only: True if the file or folder is inside a read-only
shared folder.
parent_shared_folder_id: ID of shared folder that holds this
file.
modified_by: The last user who modified the file. This field
will be null if the user's account has been deleted.
properties:
read_only:
type: boolean
description: >-
True if the file or folder is inside a read-only shared
folder.
parent_shared_folder_id:
type: string
description: ID of shared folder that holds this file.
modified_by:
type: string
description: >-
The last user who modified the file. This field will be
null if the user's account has been deleted.
media_info:
type: object
description: >
pending: Indicate the photo/video is still under processing
and metadata is not available yet.
metadata: The metadata for the photo/video.
properties:
.tag:
title: Choice of MediaInfo
type: string
enum:
- pending
- metadata
metadata:
type: object
description: |
Metadata for a photo or video.
dimensions: Dimension of the photo/video.
location: The GPS coordinate of the photo/video.
time_taken: The timestamp when the photo/video is taken.
properties:
dimensions:
type: object
description: |
Dimensions for a photo or video.
height: Height of the photo/video.
width: Width of the photo/video.
properties:
width:
type: number
description: Width of the photo/video.
height:
type: number
description: Height of the photo/video.
location:
type: object
description: |
GPS coordinates for a photo or video.
latitude: Latitude of the GPS coordinates.
longitude: Longitude of the GPS coordinates.
properties:
latitude:
type: number
description: Latitude of the GPS coordinates.
longitude:
type: number
description: Longitude of the GPS coordinates.
time_taken:
type: string
description: The timestamp when the photo/video is taken.
content_hash:
type: string
description: >-
A hash of the file content. This field can be used to verify
data integrity. For more information see our :link:`Content
hash /developers/reference/content-hash` page.
id:
type: string
description: A unique identifier for the file.
size:
type: number
description: The file size in bytes.