Skip to content

chunked_uploads.md

Latest commit

 

History

History
600 lines (409 loc) · 22.8 KB

chunked_uploads.md

File metadata and controls

600 lines (409 loc) · 22.8 KB
Raw

ChunkedUploadsManager

This is a manager for chunked uploads (allowed for files at least 20MB).

Create upload session

Creates an upload session for a new file.

This operation is performed by calling function create_file_upload_session.

See the endpoint docs at API Reference.

client.chunked_uploads.create_file_upload_session(
    parent_folder_id, file_size, file_name
)

Arguments

  • folder_id str
    • The ID of the folder to upload the new file to.
  • file_size int
    • The total number of bytes of the file to be uploaded.
  • file_name str
    • The name of new file.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSession.

Returns a new upload session.

Create upload session for existing file

Creates an upload session for an existing file.

This operation is performed by calling function create_file_upload_session_for_existing_file.

See the endpoint docs at API Reference.

client.chunked_uploads.create_file_upload_session_for_existing_file(
    uploaded_file.id, file_size
)

Arguments

  • file_id str
    • The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/files/123 the file_id is 123. Example: "12345"
  • file_size int
    • The total number of bytes of the file to be uploaded.
  • file_name Optional[str]
    • The optional new name of new file.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSession.

Returns a new upload session.

Get upload session by URL

Return information about an upload session.

The actual endpoint URL is returned by the Create upload session endpoint.

This operation is performed by calling function get_file_upload_session_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.get_file_upload_session_by_url(status_url)

Arguments

  • url str
    • URL of getFileUploadSessionById method
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSession.

Returns an upload session object.

Get upload session

Return information about an upload session.

The actual endpoint URL is returned by the Create upload session endpoint.

This operation is performed by calling function get_file_upload_session_by_id.

See the endpoint docs at API Reference.

client.chunked_uploads.get_file_upload_session_by_id(upload_session_id)

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSession.

Returns an upload session object.

Upload part of file by URL

Uploads a chunk of a file for an upload session.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function upload_file_part_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.upload_file_part_by_url(
    acc.upload_part_url,
    generate_byte_stream_from_buffer(chunk_buffer),
    digest,
    content_range,
)

Arguments

  • url str
    • URL of uploadFilePart method
  • request_body ByteStream
    • Request body of uploadFilePart method
  • digest str
    • The [RFC3230][1] message digest of the chunk uploaded. SHA-1 and SHA-512 ([RFC5843][2]) are supported. The digest must be base64 encoded. The format of this header is as sha=BASE64_ENCODED_DIGEST for SHA-1, or sha-512=BASE64_ENCODED_DIGEST for SHA-512. To get the value for the digest, use the openSSL command to encode the file part: openssl sha1 -binary <FILE_PART_NAME> | base64 for SHA-1, or openssl sha512 -binary <FILE_PART_NAME> | base64 for SHA-512. [1]: https://tools.ietf.org/html/rfc3230 [2]: https://tools.ietf.org/html/rfc5843
  • content_range str
    • The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for content-range, remember that: * The lower bound of each part's byte range must be a multiple of the part size. * The higher bound must be a multiple of the part size - 1.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadedPart.

Chunk has been uploaded successfully.

The response always includes sha512. It also includes sha1 if the Digest header used SHA-1.

Upload part of file

Uploads a chunk of a file for an upload session.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function upload_file_part.

See the endpoint docs at API Reference.

client.chunked_uploads.upload_file_part(
    acc.upload_session_id,
    generate_byte_stream_from_buffer(chunk_buffer),
    digest,
    content_range,
)

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • request_body ByteStream
    • Request body of uploadFilePart method
  • digest str
    • The [RFC3230][1] message digest of the chunk uploaded. SHA-1 and SHA-512 ([RFC5843][2]) are supported. The digest must be base64 encoded. The format of this header is as sha=BASE64_ENCODED_DIGEST for SHA-1, or sha-512=BASE64_ENCODED_DIGEST for SHA-512. To get the value for the digest, use the openSSL command to encode the file part: openssl sha1 -binary <FILE_PART_NAME> | base64 for SHA-1, or openssl sha512 -binary <FILE_PART_NAME> | base64 for SHA-512. [1]: https://tools.ietf.org/html/rfc3230 [2]: https://tools.ietf.org/html/rfc5843
  • content_range str
    • The byte range of the chunk. Must not overlap with the range of a part already uploaded this session. Each part’s size must be exactly equal in size to the part size specified in the upload session that you created. One exception is the last part of the file, as this can be smaller. When providing the value for content-range, remember that: * The lower bound of each part's byte range must be a multiple of the part size. * The higher bound must be a multiple of the part size - 1.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadedPart.

Chunk has been uploaded successfully.

The response always includes sha512. It also includes sha1 if the Digest header used SHA-1.

Remove upload session by URL

Abort an upload session and discard all data uploaded.

This cannot be reversed.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function delete_file_upload_session_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.delete_file_upload_session_by_url(abort_url)

Arguments

  • url str
    • URL of deleteFileUploadSessionById method
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type None.

A blank response is returned if the session was successfully aborted.

Remove upload session

Abort an upload session and discard all data uploaded.

This cannot be reversed.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function delete_file_upload_session_by_id.

See the endpoint docs at API Reference.

client.chunked_uploads.delete_file_upload_session_by_id(upload_session_id)

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type None.

A blank response is returned if the session was successfully aborted.

List parts by URL

Return a list of the chunks uploaded to the upload session so far.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function get_file_upload_session_parts_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.get_file_upload_session_parts_by_url(list_parts_url)

Arguments

  • url str
    • URL of getFileUploadSessionParts method
  • offset Optional[int]
    • The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.
  • limit Optional[int]
    • The maximum number of items to return per page.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadParts.

Returns a list of parts that have been uploaded.

Each part includes the hash type used to upload it. Parts uploaded with a SHA-512 Digest header don't include sha1.

List parts

Return a list of the chunks uploaded to the upload session so far.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function get_file_upload_session_parts.

See the endpoint docs at API Reference.

client.chunked_uploads.get_file_upload_session_parts(upload_session_id)

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • offset Optional[int]
    • The offset of the item at which to begin the response. Queries with offset parameter value exceeding 10000 will be rejected with a 400 response.
  • limit Optional[int]
    • The maximum number of items to return per page.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadParts.

Returns a list of parts that have been uploaded.

Each part includes the hash type used to upload it. Parts uploaded with a SHA-512 Digest header don't include sha1.

Plan upload session by URL

Plan an upload session by checking which parts already exist on the server. This endpoint allows clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and only uploading missing parts.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function create_file_upload_session_plan_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.create_file_upload_session_plan_by_url(plan_url, parts)

Arguments

  • url str
    • URL of createFileUploadSessionPlan method
  • parts List[UploadPartPlan]
    • The list of parts to check for existence.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSessionPlanResponse.

Returns information about which parts already exist (hits) and which parts need to be uploaded (misses).

Plan upload session

Plan an upload session by checking which parts already exist on the server. This endpoint allows clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and only uploading missing parts.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function create_file_upload_session_plan.

See the endpoint docs at API Reference.

Currently we don't have an example for calling create_file_upload_session_plan in integration tests

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • parts List[UploadPartPlan]
    • The list of parts to check for existence.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type UploadSessionPlanResponse.

Returns information about which parts already exist (hits) and which parts need to be uploaded (misses).

Commit upload session by URL

Close an upload session and create a file from the uploaded chunks.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function create_file_upload_session_commit_by_url.

See the endpoint docs at API Reference.

client.chunked_uploads.create_file_upload_session_commit_by_url(
    commit_url, parts, digest
)

Arguments

  • url str
    • URL of createFileUploadSessionCommit method
  • parts List[UploadPart]
    • The list details for the uploaded parts. Each entry can include sha1 or sha512. Include sha512 on every entry or on none of them. A request where only some entries include sha512 is rejected. Include parts that the server already has, returned as hits by the Plan upload session endpoint. Use the part_id, offset, and size from the plan response. If the other entries include sha512, include the sha512 value from the plan response. Otherwise, leave the hash out of these entries.
  • digest str
    • The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as sha=BASE64_ENCODED_DIGEST. SHA-512 is not supported for the whole-file digest, even if the parts were uploaded with SHA-512 digests. [1]: https://tools.ietf.org/html/rfc3230
  • if_match Optional[str]
    • Ensures this item hasn't recently changed before making changes. Pass in the item's last observed etag value into this header and the endpoint will fail with a 412 Precondition Failed if it has changed since.
  • if_none_match Optional[str]
    • Ensures an item is only returned if it has changed. Pass in the item's last observed etag value into this header and the endpoint will fail with a 304 Not Modified if the item has not changed since.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type Optional[Files].

Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed.

Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed.

Commit upload session

Close an upload session and create a file from the uploaded chunks.

The actual endpoint URL is returned by the Create upload session and Get upload session endpoints.

This operation is performed by calling function create_file_upload_session_commit.

See the endpoint docs at API Reference.

client.chunked_uploads.create_file_upload_session_commit(
    upload_session_id, parts, digest
)

Arguments

  • upload_session_id str
    • The ID of the upload session. Example: "D5E3F7A"
  • parts List[UploadPart]
    • The list details for the uploaded parts. Each entry can include sha1 or sha512. Include sha512 on every entry or on none of them. A request where only some entries include sha512 is rejected. Include parts that the server already has, returned as hits by the Plan upload session endpoint. Use the part_id, offset, and size from the plan response. If the other entries include sha512, include the sha512 value from the plan response. Otherwise, leave the hash out of these entries.
  • digest str
    • The [RFC3230][1] message digest of the whole file. Only SHA1 is supported. The SHA1 digest must be Base64 encoded. The format of this header is as sha=BASE64_ENCODED_DIGEST. SHA-512 is not supported for the whole-file digest, even if the parts were uploaded with SHA-512 digests. [1]: https://tools.ietf.org/html/rfc3230
  • if_match Optional[str]
    • Ensures this item hasn't recently changed before making changes. Pass in the item's last observed etag value into this header and the endpoint will fail with a 412 Precondition Failed if it has changed since.
  • if_none_match Optional[str]
    • Ensures an item is only returned if it has changed. Pass in the item's last observed etag value into this header and the endpoint will fail with a 304 Not Modified if the item has not changed since.
  • extra_headers Optional[Dict[str, Optional[str]]]
    • Extra headers that will be included in the HTTP request.

Returns

This function returns a value of type Optional[Files].

Returns the file object in a list.Returns when all chunks have been uploaded but not yet processed.

Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed.

Upload big file

Starts the process of chunk uploading a big file. Should return a File object representing uploaded file.

This operation is performed by calling function upload_big_file.

client.chunked_uploads.upload_big_file(
    generate_byte_stream_from_buffer(file_buffer),
    file_name,
    file_size,
    parent_folder_id,
)

Arguments

  • file ByteStream
    • The stream of the file to upload.
  • file_name str
    • The name of the file, which will be used for storage in Box.
  • file_size int
    • The total size of the file for the chunked upload in bytes.
  • parent_folder_id str
    • The ID of the folder where the file should be uploaded.

Returns

This function returns a value of type FileFull.

Upload big file version

Starts the process of chunk uploading a new version of a big file. Should return a File object representing the uploaded file version. Returns nothing when commit responds with 202 because the file did not change.

This operation is performed by calling function upload_big_file_version.

client.chunked_uploads.upload_big_file_version(
    uploaded_file.id,
    generate_byte_stream(version_file_size),
    version_file_size,
    file_name=version_name,
)

Arguments

  • file_id str
    • The ID of the file to upload a new version of.
  • file ByteStream
    • The stream of the file to upload.
  • file_size int
    • The total size of the file for the chunked upload in bytes.
  • file_name Optional[str]
    • The optional new name of the file.

Returns

This function returns a value of type Optional[FileFull].