b2_upload_part
    • Dark
      Light

    b2_upload_part

    • Dark
      Light

    Article Summary

    Post
    /b2api/v3/b2_upload_part

    Uploads one part of a large file to B2, using an file ID obtained from b2_start_large_file

    Once all of the parts are uploaded, use b2_finish_large_file to make the file available for use.

    If you upload the same part number for the same file more than once, both uploads will succeed, and the second upload will overwrite the first.

    Request

    The upload request is a POST. The file name and other parameters are in the request headers, and the file to be uploaded is the request body.

    Use the b2_get_upload_part_url operation to get a URL you can use to upload files. The URL it returns will contain your bucket ID and the upload destination, and will look something like this:

    https://pod-000-1016-09.backblaze.com/b2api/v3/b2_upload_part/4_ze73ede9c9c8412db49f60715_f200b4e93fbae6252_d20150824_m224353_c900_v8881000_t0001/0037

    Some errors returned mean that you must call b2_get_upload_url again to get a new upload URL and authorization token. See Uploading for details.

    NOTE:

    You must set the Content-Length HTTP header when using either b2_upload_file or b2_upload_part.

    Chunked transfer encoding, which allows the Content-Length header to be omitted, is not supported.

    API Versions

    v1: Add uploadTimestamp field (August 30, 2018)

    The response now includes the same uploadTimestamp field returned by b2_list_buckets.

    v1: Application keys (July 26, 2018)

    Incompatible change: After calling b2_authorize_account with an application key that does not have the right permissions, this call will return a 401 Unauthorized.

    v1: Original release (September 22, 2015)


    Header parameters
    Authorization
    stringRequired

    An upload authorization token obtained from b2_get_upload_part_url.

    X-Bz-Part-Number
    stringRequired

    A number from 1 to 10000. The parts uploaded for one file must have contiguous numbers, starting with 1.

    Content-Length
    integerRequired

    The number of bytes in the file being uploaded.


    Note: Chunked transfer encoding, which allows the Content-Length header to be omitted, is not supported.


    When sending the SHA1 checksum at the end, the Content-Length should be set to the size of the file plus the 40 bytes of hex checksum.

    X-Bz-Content-Sha1
    stringRequired

    The SHA1 checksum of this part of the file. B2 will check this when the part is uploaded, to make sure that the data arrived correctly.


    The same SHA1 checksum must be passed to b2_finish_large_file.


    You may optionally provide the SHA1 at the end of the upload. See the section on Uploading.

    X-Bz-Server-Side-Encryption-Customer-Algorithm
    string

    This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption algorithm requested via b2_start_large_file.

    X-Bz-Server-Side-Encryption-Customer-Key
    string

    This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption customerKey requested via b2_start_large_file.

    X-Bz-Server-Side-Encryption-Customer-Key-Md5
    string

    This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption customerKeyMd5 requested via b2_start_large_file.

    Responses
    200

    The request succeeded.


    The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.

    Expand All
    object
    fileId
    string

    The file ID for uploading this file.

    Example4_ze73ede9c9c8412db49f60715_f200b4e93fbae6252_d20150824_m224353_c900_v8881000_t0001
    partNumber
    integer

    Which part this is.

    Example1
    contentLength
    integer

    The number of bytes stored in the part.

    Example100000000
    contentSha1
    string

    The SHA1 of the bytes stored in the part.

    Example062685a84ab248d2488f02f6b01b948de2514ad8
    contentMd5
    string

    The MD5 of the bytes stored in the part. Not all parts have an MD5 checksum, so this field is optional, and set to null for parts that do not have one.

    Example142be8357f26eda2ec6775cce257753b
    serverSideEncryption
    object

    When the file is encrypted with Server-Side Encryption, the mode ("SSE-B2" or "SSE-C") and algorithm used to encrypt the data. If the file is not encrypted with Server-Side Encryption, then both mode and algorithm will be null. This field is omitted when the action is "hide" or "folder".

    Example{ "algorithm": null, "mode": null }
    algorithm
    string
    mode
    string
    uploadTimestamp
    integer

    This is a UTC time when this part was uploaded. It is a base 10 number of milliseconds since midnight, January 1, 1970 UTC. This fits in a 64 bit integer such as the type "long" in the programming language Java. It is intended to be compatible with Java's time long. For example, it can be passed directly into the java call Date.setTime(long time).

    Example1559585435000
    400
    statuscodedescription
    400auth_token_limitThe auth token is already being used. For more information, see Uploading in Parallel.
    400bad_requestThe request had the wrong fields or illegal values. The message returned with the error will describe the problem.
    400bad_bucket_idThe requested bucket ID does not match an existing bucket.
    object
    status
    integer

    The numeric HTTP status code. Always matches the status in the HTTP response.

    Example400
    code
    string

    A single-identifier code that identifies the error.

    Exampleinvalid_bucket_name
    message
    string

    A human-readable message, in English, saying what went wrong.

    Examplebucket name is too long
    401
    statuscodedescription
    401bad_auth_tokenThe auth token used has expired. Call b2_get_upload_part_url again to get a new one.
    401expired_auth_tokenThe auth token used has expired. Call b2_get_upload_part_url again to get a new one.
    401unauthorizedThe auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account.
    405
    statuscodedescription
    405method_not_allowedonly POST is supported
    408
    statuscodedescription
    408request_timeoutThe service timed out reading the uploaded file
    503
    statuscodedescription
    503service_unavailableCall b2_get_upload_part_url again to get a new auth token.

    Was this article helpful?